跳到主要内容

创建定期付款（旅程 2）

旅程 2 — 仅含定期付款数据的 QR 码

概述

是什么

仅呈现定期付款数据供付款人授权的 QR 码，无需立即收费。

适用场景

无初始收费的入驻；用于销售点、柜台、屏幕或印刷材料。

如何运作

付款人扫描 QR 码 → 在应用中查看定期付款数据 → 授权 → 可安排未来收费。

优势

通过 QR 码快速启用；可大量低摩擦地获取客户，且 QR 码可重复用于新定期付款。

请求​

ENDPOINT
/account/account_key/outgoing_recurrence/journey_two
方法
POST

请求 Path Params​

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

Request Body​

Request Body: 创建定期付款（旅程 2）
{
    "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": "124587624",
        "address": {
            "street": "Av. Brigadeiro Faria Lima",
            "state": "SP",
            "city": "São Paulo",
            "neighborhood": "Jardim Paulistano",
            "number": "2391",
            "postal_code": "01452905",
            "complement": "Complemento"
        }
    },
    "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_amountnumber可变金额定期付款的最低交易金额（以分为单位）。-
start_date *string定期付款开始日期（ISO 8601 格式，如 "2025-07-01"）。-
end_datestring定期付款结束日期；无限期情况发送 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
注意

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_idstring订阅者合同标识符。100
address *Object订阅者地址。Objeto address

Objeto address​

字段类型描述字符数
streetstring街道。-
statestring州。-
citystring城市。-
neighborhoodstring街区。-
numberstring门牌号。-
postal_codestring邮政编码。-
complementstring补充信息。-

Objeto retry_configuration​

字段类型描述字符数
retry_allowedboolean是否允许重试。-
retry_ruleObject重试规则。Objeto retry_rule

Objeto retry_rule​

字段类型描述字符数
first_retryObject第 1 次重试配置。Objeto retry_detail
second_retryObject第 2 次重试配置。Objeto retry_detail
third_retryObject第 3 次重试配置。Objeto retry_detail

Objeto retry_detail​

字段类型描述字符数
daystring重试日期。-

响应​

STATUS
200
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"  
    },
    "created_at": "2021-10-22T20:30:23.459Z"
}

Response Body​

字段类型描述字符数
request_control_keyuuid客户端发送的请求控制键。36
recurrence_keyuuid订阅定期付款的唯一标识键。36
recurrence_statusenumerator定期付款的当前状态。Enumeradores recurrence_status
qr_code_dataobjectQR 码数据。Objeto qr_code_data
created_atstring定期付款创建的日期和时间（ISO 8601 格式）。-

Objeto qr_code_data​

字段类型描述字符数
qr_code_urlstringQR 码复制粘贴的 URL。-
qr_code_keyuuidQR 码的唯一标识键。36
qr_code_imagestringQR 码图像 Base64。-

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
400QIT000002Bad RequestInvalid request schema.Erro no esquema da requisição.
403APX000030Unauthorized TransactionUser is not authorized to create this recurrence.Usuário não autorizado a criar esta recorrência.
403APX000018Endpoint Access DeniedRequester lacks permission to access this endpoint.Requester não possui permissão para acessar este endpoint.
404APX000021Subscription Not FoundSubscription {subscription_key} not found.Assinatura {subscription_key} não encontrada.
404APX000002Recurrence Not FoundRecurrence {recurrence_key} not found.Recorrência {recurrence_key} não encontrada.
406APX000027Invalid Transaction AmountTransaction amount {minimum_transaction_amount} is invalid.Valor da transação {minimum_transaction_amount} é inválido.
409APX000014Request Control Key ConflictThe request_control_key {request_control_key} is already in use.A request_control_key {request_control_key} já está em uso.