Webhooks

由于转账以异步方式进行，正确映射和处理发送的 Webhooks 至关重要。

注意！

QI Tech 的 Webhooks 不应以限制性方式映射。 我们 API 返回的 Webhook 载荷中可能会添加额外字段。

Pix 自动定期付款创建 Webhook

包含客户定期付款创建信息的 Webhook。

Webhook Request Body

Request Body: 创建定期付款

{
    "webhook_type": "baas.automatic_pix.incoming_recurrence",
    "webhook_datetime": "2025-10-22T20:30:23.459Z",
    "data": {
        "account_key": "13385acf-b0c3-4389-baf3-a58abbe92d58",
        "incoming_recurrence_key": "12385acf-b0c3-4389-baf3-a58abbe92d58",
        "incoming_recurrence_status": "pending_confirmation",
        "transaction_amount": "150.00",
        "periodicity": "monthly",
        "journey_type": "journey_one",
        "pix_transfer_type": "key",
        "end_to_end_id": "E1234567890123456789012",
        "start_date": "2025-06-01",
        "end_date": "2026-06-01",
        "receiver_conciliation_id": "rec-conc-789",
        "target_pix_key": "receiver@bank.com.br",
        "payer_document_number": "12345678900",
        "pix_message": "Pagamento mensal de serviço",
        "created_at": "2025-05-22T10:00:00Z",
        "updated_at": "2025-05-22T12:00:00Z"
    }
}

Webhook Body Param

字段	类型	描述	最大字符数
webhook_type	string	定义报告事件类型的枚举值。	23
webhook_datetime	string	Webhook 发送日期和时间。	20
account_key	uuid4	账户的唯一标识键。	36
incoming_recurrence_key	uuid4	授权的唯一标识键。	36
incoming_recurrence_status	string	Pix 定期付款状态标识符。	Enumeradores incoming_recurrence_status
transaction_amount	number	固定金额定期付款的转账金额。	10
minimum_transaction_amount	number	可变金额定期付款的最低转账金额。	10
maximum_transaction_amount	number	可变金额定期付款的最高转账金额。	10
periodicity	enum	与付款关联的周期类型。	Enumeradores periodicity
journey_type	enum	请求旅程类型。	Enumeradores journey_type
pix_transfer_type	enum	要执行的 Pix 类型。	Enumeradores pix_transfer_type
end_to_end_id	string	SPI 内 Pix 交易的幂等键。	32
start_date	string	定期付款开始日期。	-
end_date	string	定期付款结束日期，对于无限期情况发送 null。	-
receiver_conciliation_id	string	接收方对账标识。	35
target_pix_key	string	交易账户的 Pix 键。	100
payer_document_number	string	交易付款人的文件编号。	14
pix_message	string	随 Pix 转账一起发送的消息。	140
created_at	string	定期付款请求的创建时间。	-
updated_at	string	定期付款请求的更新时间。	-

Enumerador incoming_recurrence_status

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

Enumeradores periodicity

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

Enumeradores journey_type

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

Enumeradores pix_transfer_type

枚举值	描述
manual	使用目标账户数据的 Pix
key	使用 Pix 键的 Pix
static_qr_code	使用静态 QR 码的 Pix
dynamic_qr_code	使用动态 QR 码的 Pix