跳到主要内容

创建定期付款（旅程 1）

旅程 1 — 无 QR 码（应用内通知）

概述

是什么

直接在付款人银行应用内请求授权，无需扫描 QR 码。

适用场景

主动联系（电话、聊天、面对面）或已有客户关系。

如何运作

接收方使用付款人账户数据创建定期付款 → 付款人在应用内收到通知 → 批准定期付款 → 可安排未来收费。

优势

简单直接的体验；无需展示 QR 码。

请求​

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

请求 Path Params​

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

Request Body​

Request Body: 创建定期付款（旅程 1）
{
    "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": "Contrato de pagamento recorrente",
        "address": {
            "street": "Av. Brigadeiro Faria Lima",
            "state": "SP",
            "city": "São Paulo",
            "neighborhood": "Jardim Paulistano",
            "number": "2391",
            "postal_code": "01452905",
            "complement": "Complemento"
        },
        "account_data": {
            "account_number": "123456",
            "account_digit": "7",
            "account_branch": "0001",
            "ispb": "31872495"
        }
    },
    "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
account_data *Object订阅者银行数据。Objeto account_data

Objeto address​

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

Objeto account_data​

字段类型描述字符数
account_numberstring账户号码。-
account_digitstring账户校验位。-
account_branchstring账户支行。-
ispbstring金融机构 ISPB。-

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": "a7b9e3c1-f2d4-4a8b-9c7e-123456789abc",
    "recurrence_key": "b2c3d4e5-f6g7-4h8i-9j0k-l1m2n3o4p5q6",
    "recurrence_status": "pending_confirmation",
    "created_at": "2025-06-16T23:52:00.000Z"
}

Response Body​

字段类型描述字符数
request_control_keyuuid客户端发送的请求控制键。36
recurrence_keyuuid订阅定期付款的唯一标识键。36
recurrence_statusenumerator定期付款的当前状态。Enumeradores recurrence_status
created_atstring定期付款创建的日期和时间（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
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.