查询定期付款

通过 incoming_recurrency_key 查询 Pix 定期付款

请求

ENDPOINT

/account/ACCOUNT_KEY/incoming_recurrence/INCOMING_RECURRENCE_KEY

方法

GET

Path Params

字段	类型	描述	字符数
account_key *	uuid4	QI 账户的唯一标识键。	36
incoming_recurrency_key *	uuid4	Pix 自动定期付款的唯一标识键。	36

响应

STATUS

200

Response Body: 查询定期付款

{
  "incoming_recurrence_key": "c2f3eefa-1b8e-4d5f-9b9d-123456789abc",
  "incoming_recurrence_status": "pending_confirmation",
  "request_control_key": "e04197f6-433e-48d2-8a8e-9258a70aba0b",
  "transaction_amount": "150.00",
  "periodicity": "monthly",
  "journey_type": "journey_one",
  "pix_transfer_type": "key",
  "end_to_end_id": "E1234567890123456789012",
  "start_date": "2025-06-01",
  "end_date": "2026-06-01",
  "next_execution_date": "2025-07-01",
  "receiver_conciliation_id": "rec-conc-789",
  "target_pix_key": "receiver@bank.com.br",
  "payer_document_number": "12345678900",
  "pix_message": "Pagamento mensal de serviço",
  "created_at": "2025-05-22T10:00:00Z",
  "updated_at": "2025-05-22T12:00:00Z",
}

字段	类型	描述	最大字符数
incoming_recurrence_key	uuid4	授权的唯一标识键。	36
incoming_recurrence_status	string	定期付款状态标识符。	Enumerador incoming_recurrence_status
request_control_key	uuid4	客户端使用的请求唯一标识键。	36
transaction_amount	number	固定金额定期付款的转账金额。	10
minimum_transaction_amount	number	可变金额定期付款的最低转账金额。	10
maximum_transaction_amount	number	可变金额定期付款的最高转账金额。	10
periodicity	enumerator	与付款关联的周期类型。	Enumeradores periodicity
journey_type	enumerator	请求旅程类型。	Enumeradores journey_type
pix_transfer_type	enumerator	要执行的 Pix 类型。	Enumeradores pix_transfer_type
end_to_end_id	string	SPI（即时支付系统）内 Pix 交易的幂等键。该键在 Pix 键查询中返回。	32
start_date	string	定期付款开始日期。	-
end_date	string	定期付款结束日期，对于无限期情况发送 null。
next_execution_date	string	定期付款下次交易的执行日期。	-
receiver_conciliation_id	string	接收方对账标识。	35
target_pix_key	string	交易账户的 Pix 键。	100
payer_document_number	string	交易付款人的文件编号。	14
pix_message	string	随 Pix 转账一起发送的消息。	140
created_at	string	定期付款请求的创建时间。	-
updated_at	string	定期付款请求的更新时间。	-

Enumerador incoming_recurrence_status

枚举值	描述
pending_confirmation	定期付款待确认
active	定期付款已激活
cancelled	定期付款已取消
suspended	定期付款已暂停
expired	定期付款已到期

Enumeradores periodicity

枚举值	描述
weekly	每周定期
monthly	每月定期
quarterly	每季定期
semiannual	每半年定期
annual	每年定期

Enumeradores journey_type

枚举值	描述
journey_one	通过应用内通知申请授权
jouney_two	通过扫描 QR 码申请授权
journey_three	通过扫描 QR 码进行即时 Pix 付款来授权定期付款
journey_four	付款或调度 Pix 后依次申请定期付款授权

Enumeradores pix_transfer_type

枚举值	描述
manual	使用目标账户数据的 Pix
key	使用 Pix 键的 Pix
static_qr_code	使用静态 QR 码的 Pix
dynamic_qr_code	使用动态 QR 码的 Pix

STATUS

4xx

Response Body: Error

{
  "title": "titulo",
  "description": "description in English",
  "translation": "descrição em portugues",
  "code": "codigo",
  "extra_fields": {}
}

HTTP 状态码	QI 代码 code	标题 title	描述（英文） Description	描述（葡文） translation
403	APX000025	User is not allowed to do this transaction	User is not allowed to do this transaction	Usuário não tem autorização para fazer essa transação
403	APX000017	Requester not allowed to access this endpoint	Requester has no permission to perform pix transfers on this endpoint	Requester não possui permissão de realizar transações pix através deste endpoint
404	APX000020	Account not Found	Account was not found	Conta {account_key} não foi encontrada.
404	APX000001	Recurrence not Found	Recurrence was not found	Recorrência {incoming_recurrence_key} não foi encontrada