创建定期付款

请求

ENDPOINT

/account/ACCOUNT_KEY/incoming_recurrence

方法

POST

请求 Path Params

字段	类型	描述	字符数
`account_key` *	uuid4	账户的唯一标识键。	36

Request Body

Request Body: 创建固定金额定期付款

{
  "request_control_key": "01585acf-b0c3-4389-baf3-a58abbe92d58",
  "end_to_end_id": "E73856642202309201429bZKfklNlbwu",
  "periodicity": "monthly",
  "journey_type": "journey_one",
  "start_date": "2025-04-01",
  "end_date": "2027-04-01",
  "target_pix_key": "pix_key@test.bcb.com",
  "pix_message": "Informação do pagamento",
  "is_retry_allowed": true,
  "transaction_amount": 150.04
}

Request Body: 创建可变金额定期付款

{
  "request_control_key": "12385acf-b0c3-4389-baf3-a58abbe92d58",
  "end_to_end_id": "E73856642202309201429bZKfklNlbwu",
  "periodicity": "monthly",
  "journey_type": "journey_one",
  "start_date": "2025-07-01",
  "end_date": null,
  "target_pix_key": "pix_key@test.bcb.com",
  "pix_message": "Pagamento da conta de energia elétrica",
  "is_retry_allowed": true,
  "minimum_transaction_amount": 50.00,
  "maximum_transaction_amount": 300.00
}

Body Params

字段	类型	描述	字符数
`request_control_key` *	uuid	客户端使用的 uuid4 格式请求唯一标识键。	36
`periodicity` *	enumerator	与付款关联的周期类型。	Enumeradores periodicity
`journey_type` *	enumerator	请求旅程类型。	Enumeradores journey_type
`start_date` *	string	定期付款开始日期。	-
`end_to_end_id` *	string	SPI（即时支付系统）内 Pix 交易的幂等键。该键在 Pix 键查询中返回。	32
`target_pix_key`	string	接收交易的账户 Pix 键。	100
`target_account`	Object	目标账户 - 仅用于手动转账。	Objeto target_account
`transaction_amount`	number	固定金额定期付款的转账金额。	10
`minimum_transaction_amount`	number	可变金额定期付款的最低转账金额。	10
`maximum_transaction_amount`	number	可变金额定期付款的最高转账金额。	10
`end_date`	string	定期付款结束日期，对于无限期情况发送 null。	-
`pix_message`	string	随 Pix 转账一起发送的消息。	140
`is_retry_allowed`	boolean	是否允许 Pix 交易重试。	-

Enumeradores periodicity

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

Enumeradores journey_type

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

Objeto target_account

字段	类型	描述	字符数
`account_branch`	string	账户支行。	6
`account_digit`	string	账户校验位。	1
`account_number`	string	账户号码。	20
`owner_document_number`	string	账户持有人的 CPF 或 CNPJ（仅数字）。	14
`owner_name`	string	账户持有人姓名。	150
`account_type`	enumerator	账户类型。	Enumerador account_type
`ispb`	string	基于金融机构 CNPJ 的代码（8位数字）。	8

信息

由于不同机构返回的信息不同，不同的枚举值可能表示同一种账户类型。

Enumerador account_type

枚举值	描述
`checking_account`	支票账户
`salary_account`	工资账户
`saving_account`	储蓄账户
`payment_account`	支付账户

响应

STATUS

200

Response Body: 定期付款已创建

{
  "incoming_recurrence_key": "cfa32109-a6dd-4304-94db-03a7b6d92a47",
  "incoming_recurrence_status": "pending_confirmation",
  "created_at": "2025-05-22T20:30:23.459Z",
}

字段	类型	描述	最大字符数
`incoming_recurrence_key`	uuid	授权的唯一标识键。	36
`incoming_recurrence_status`	string	定期付款状态标识符。	Enumerador incoming_recurrence_status
`created_at`	string	定期付款请求的创建时间。	-

Enumerador incoming_recurrence_status

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

STATUS

4XX

Response Body

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

HTTP 状态码	QI 代码 `code`	标题 `title`	描述（英文） `Description`	描述（葡文） `translation`
400	QIT000001	Bad Request	Schema Error	Erro de Schema
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.
406	APX000026	Invalid end_to_end_id	The end_to_end_id sent {end_to_end_id} is not valid.	O end_to_end_id enviado {end_to_end_id} não é válido
406	APX000005	Invalid Transaction Amount	Transaction amount of {transaction_amount} is not valid. It must be a positive value with at maximum 2 decimal places	O valor de transação {transaction_amount} não é válido. Deve ser um valor positivo com no máximo duas casas decimais
409	APX000013	Request Control Key Reuse Error	The request_control_key {request_control_key} already in use	A request_control_key {request_control_key} já utilizada

请求​

请求 Path Params​

Request Body​

Body Params​

Enumeradores periodicity​

Enumeradores journey_type​

Objeto target_account​

Enumerador account_type​

响应​

Enumerador incoming_recurrence_status​

请求