创建定期付款（旅程 4）

旅程 4 — QR 码 + 付款或调度 + 提供 Pix 自动支付

概述

是什么

客户扫描 QR 码进行付款或调度，之后收到激活 Pix 自动支付定期付款的邀请。

适用场景

适用于账单、收据或需要提出定期授权的付款，但仅在初始付款或调度之后。

如何运作

付款人扫描 QR 码 → 付款或调度 → 完成后收到激活 Pix 自动支付的邀请（可选）。

优势

灵活性：定期付款的决定在付款/调度后做出，允许付款人自愿自发地参与。

注意事项

定期付款提议仅在付款/调度后做出——客户可以拒绝。如果该情况不适用定期付款，仅继续付款，不提供定期付款。

请求

ENDPOINT

/account/account_key/outgoing_recurrence/journey_four

方法

POST

请求 Path Params

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

Request Body

Request Body: 创建定期付款（旅程 4）

{
    "request_control_key": "98fc62fd-b0a0-4604-9bea-475e91a9dc82",
    "periodicity": "monthly",
    "minimum_recurrence_amount": 125,
    "start_date": "2025-06-10",
    "end_date": "2027-06-10",
    "pix_message": "Conta de Luz Residencial nº123",
    "recurrence_type": "variable_amount",
    "debtor_data": {
        "name": "Sebastião",
        "email": "sebastiao@test.com",
        "document_number": "05431134850",
        "contract_id": "12345",
        "address": {
            "street": "Av. Brigadeiro Faria Lima","state": "SP","city": "São Paulo",
            "neighborhood": "Jardim Paulistano","number": "2391","postal_code": "01452905","complement": "Complemento"
        }
    },
    "initial_payment_data": {
        "amount": 22.34,
        "pix_key": "3d7d6a2b-f72f-44z7-bb20-79a94dff5645",
        "qr_code_type": "dynamic_term",
        "additional_data": [{"key_name": "Juros e Multa","value": "Juros 2 ao mes e multa de 1%"}],
        "fine_amount": 3,"interest_amount": 2,"expiration_date": "2023-03-25","max_payment_days": 128,"rebate_amount": 1,"discounts": [],
        "receiver_conciliation_id": "3d7d6a2bf72f44z7bb2079a94dff5645"		
    },
    "retry_configuration": {
        "retry_allowed": true,
        "retry_rule": {"first_retry": {"day": "1"},"second_retry": {"day": "3"},"third_retry": {"day": "4"}}
    },
    "settlement_date_type": "workdays"
}

Body Params

字段	类型	描述	字符数
`request_control_key` *	uuid	uuid4 格式的请求唯一标识键。	36
`periodicity` *	enumerator	与订阅定期付款关联的周期类型。	Enumeradores periodicity
`minimum_recurrence_amount`	float	可变金额定期付款的最低交易金额。	-
`start_date` *	string	定期付款开始日期（ISO 8601 格式）。	-
`end_date`	string	定期付款结束日期；无限期情况发送 null。	-
`pix_message` *	string	随 Pix 交易一起发送的消息。	140
`debtor_data` *	Object	债务人（订阅者）数据。	Objeto debtor_data
`retry_configuration` *	Object	未完成交易的重试配置。	Objeto retry_configuration
`settlement_date_type` *	enumerator	结算日期调整类型。	Enumeradores settlement_date_type
`recurrence_type` *	enumerator	定期付款类型。	Enumeradores recurrence_type
`initial_payment_data` *	Object	创建订阅时进行的初始收费数据。	Objeto initial_payment_data

注意

minimum_recurrence_amount 字段为可选字段，仅适用于可变金额定期付款。若为固定金额定期付款，应发送 recurrence_amount 字段及定期付款金额。recurrence_type 枚举值也应与定期付款类型对应。

Enumeradores periodicity

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

Enumeradores settlement_date_type

枚举值	描述
`workdays`	工作日
`calendar_days`	日历天数

Enumeradores recurrence_type

枚举值	描述
`fixed_amount`	固定金额定期付款
`variable_amount`	可变金额定期付款

Objeto debtor_data

字段	类型	描述	字符数
`name` *	string	订阅者姓名。	50
`email` *	string	订阅者电子邮件。	100
`document_number` *	string	订阅者 CPF 或 CNPJ。	14
`contract_id`	string	订阅者合同标识符。	100
`address` *	Object	订阅者地址。	Objeto address

Objeto address

字段	类型	描述	字符数
`street`	string	街道。	-
`state`	string	州。	-
`city`	string	城市。	-
`neighborhood`	string	街区。	-
`number`	string	门牌号。	-
`postal_code`	string	邮政编码。	-
`complement`	string	补充信息。	-

Objeto retry_configuration

字段	类型	描述	字符数
`retry_allowed`	boolean	是否允许重试。	-
`retry_rule`	Object	重试规则。	Objeto retry_rule

Objeto retry_rule

字段	类型	描述	字符数
`first_retry`	Object	第 1 次重试配置。	Objeto retry_detail
`second_retry`	Object	第 2 次重试配置。	Objeto retry_detail
`third_retry`	Object	第 3 次重试配置。	Objeto retry_detail

Objeto retry_detail

字段	类型	描述	字符数
`day`	string	重试日期。	-

Objeto initial_payment_data

字段	类型	描述	字符数
`amount` *	number	初始收费的主要金额（巴西雷亚尔 R$）。	-
`pix_key` *	string	付款目标 Pix 键。	77
`qr_code_type` *	enumerator	初始收费的 QR 码类型。	Enumeradores qr_code_type
`additional_data` *	array	与收费相关的附加信息列表。	Objetos additional_data
`fine_amount`	number	付款逾期时的罚款金额。	-
`interest_amount`	number	付款逾期时的利息金额。	-
`expiration_date` *	string	初始收费到期日期（ISO 8601 格式）。	-
`max_payment_days`	integer	到期后可接受付款的最大天数。	-
`rebate_amount`	number	提前付款折扣金额。	-
`discounts`	array	适用的附加折扣列表（如有）。	-
`receiver_conciliation_id`	string	接收方付款对账的唯一标识符。	32

Enumeradores qr_code_type

枚举值	描述
`dynamic_instant`	即时付款动态 QR 码（立即到期）。
`dynamic_term`	具有定义截止日期的动态 QR 码。

响应

STATUS

200

注意

当付款用户收到通知时，可以选择调度 Pix 或立即付款。如果付款人立即付款，将发送包含已填写信息的 Webhook；如果是调度，相关值将为 null。

Response Body

{
    "request_control_key": "98fc62fd-b0a0-4604-9bea-475e91a9dc82",
    "outgoing_recurrence_key": "8cb70dea-9fb0-4a68-9572-99a72849c8d6",
    "outgoing_recurrence_status": "pending_confirmation",
    "qr_code_data": {
        "qr_code_url": "url",
        "qr_code_key": "98fc62fd-b0a0-4604-9bea-475e91a9dc85",
        "qr_code_image": "imageb64"
    },
    "initial_payment_data": {
        "receiver_conciliation_id": "6f270b64-1b7a-4269-91f8-3f9cf30ba0bb"
    },
    "created_at": "2021-10-22T20:30:23.459Z"
}

Response Body

字段	类型	描述	字符数
`request_control_key`	uuid	客户端发送的请求控制键。	36
`recurrence_key`	uuid	订阅定期付款的唯一标识键。	36
`recurrence_status`	enumerator	定期付款的当前状态。	Enumeradores recurrence_status
`qr_code_data`	object	QR 码数据。	Objeto qr_code_data
`initial_payment_data`	object	初始付款信息。	-
`created_at`	string	定期付款创建的日期和时间（ISO 8601 格式）。	-

Enumeradores recurrence_status

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

STATUS

4XX

Response Error

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

HTTP 状态码	QI 代码 `code`	标题 `title`	描述（英文） `description`	描述（葡文） `translation`
400	QIT000002	Bad Request	Invalid request schema.	Erro no esquema da requisição.
403	APX000030	Unauthorized Transaction	User is not authorized to create this recurrence.	Usuário não autorizado a criar esta recorrência.
403	APX000018	Endpoint Access Denied	Requester lacks permission to access this endpoint.	Requester não possui permissão para acessar este endpoint.
404	APX000021	Subscription Not Found	Subscription {subscription_key} not found.	Assinatura {subscription_key} não encontrada.
404	APX000002	Recurrence Not Found	Recurrence {recurrence_key} not found.	Recorrência {recurrence_key} não encontrada.
406	APX000027	Invalid Transaction Amount	Transaction amount {minimum_transaction_amount} is invalid.	Valor da transação {minimum_transaction_amount} é inválido.
409	APX000014	Request Control Key Conflict	The request_control_key {request_control_key} is already in use.	A request_control_key {request_control_key} já está em uso.

概述

请求​

请求 Path Params​

Request Body​

Body Params​

Enumeradores periodicity​

Enumeradores settlement_date_type​

Enumeradores recurrence_type​

Objeto debtor_data​

Objeto address​

Objeto retry_configuration​

Objeto retry_rule​

Objeto retry_detail​

Objeto initial_payment_data​

Enumeradores qr_code_type​

响应​

Response Body​

Enumeradores recurrence_status​

请求