创建定期付款（旅程 3）

旅程 3 — QR 码 + 首次付款（立即激活定期付款）

概述

是什么

一个 QR 码，允许在同一流程中立即付款并激活定期付款。

适用场景

需要初始收费的情况（如加入费、注册费、首月费用）。

如何运作

付款人扫描 QR → 首次付款 → 立即授权定期付款。

优势

即时收入 + 定期付款已配置，减少摩擦和逾期。

旅程 3 流程

扫描 QR 码 — 用户扫描为初始收费生成的动态 QR 码。
立即付款 — 处理即时付款，记录初始收费。
授权定期付款 — 在同一体验中，用户确认定期付款授权。
定期付款已激活 — 后续周期自动化；必要时只需对账金额。

请求

ENDPOINT

/account/account_key/outgoing_recurrence/journey_three

方法

POST

Path Params

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

Request Body

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

{
  "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

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

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 格式，如 "2023-03-25"）。	-
`max_payment_days`	integer	到期后可接受付款的最大天数。	-
`rebate_amount`	number	提前付款折扣金额。	-
`discounts`	array	适用的附加折扣列表（如有）。	-
`receiver_conciliation_id`	string	接收方付款对账的唯一标识符。	32

Enumeradores qr_code_type

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

Objeto additional_data

字段	类型	描述
`key_name`	string	附加信息字段名称（如 "Juros e Multa"）。
`value`	string	附加信息的值或描述。

响应

STATUS

200

注意

当付款用户收到通知时，可以选择调度 Pix 或立即付款。如果付款人立即付款，将发送包含已填写信息的 baas.automatic_pix.outgoing_recurrence.status_change 类型 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": "6f270b64-1b7a-4269-91f8-3f9cf30ba0bb",
        "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	已启动付款的信息。	Objeto initial_payment_data response
`created_at`	string	定期付款创建的日期和时间（ISO 8601 格式）。	-

Objeto qr_code_data

字段	类型	描述	字符数
`qr_code_url`	string	QR 码复制粘贴的 URL。	-
`qr_code_key`	uuid	QR 码的唯一标识键。	36
`qr_code_image`	string	QR 码图像 Base64。	-

Objeto initial_payment_data（响应）

字段	类型	描述	字符数
`receiver_conciliation_id`	string	接收方付款对账的唯一标识符。	32

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.

概述

旅程 3 流程​

请求​

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​

Objeto additional_data​

响应​

Response Body​

Objeto qr_code_data​

Objeto initial_payment_data（响应）​

Enumeradores recurrence_status​