跳到主要内容

Pix 自动支付 Webhooks

Webhook 通知对于正确处理与 Pix 自动支付相关的异步事件至关重要，尤其是不同旅程类型的定期付款授权和执行。

注意！

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

定期付款状态 Webhook​

此 Webhook 用于报告 Pix 自动支付授权和定期付款周期的状态变更，区分不同的旅程类型。

Webhook Request Body​

旅程 1 – journey_one​

Request Body: 旅程 1
{
  "event_type": "baas.automatic_pix.outgoing_recurrence.status_change",
  "origin_key": "8cb70dea-9fb0-4a68-9572-99a72849c8d6",
  "data": {
    "request_control_key": "98fc62fd-b0a0-4604-9bea-475e91a9dc82",
    "outgoing_recurrence_key": "8cb70dea-9fb0-4a68-9572-99a72849c8d6",
    "outgoing_recurrence_status": "approved",
    "journey_type": "journey_one",
    "outgoing_recurrence_data": {
      "minimum_recurrence_amount": 123.45,
      "recurrence_amount": null
    },
    "payment_conciliation_batch_key": "uuid"
  }
}

旅程 2 – journey_two​

Request Body: 旅程 2
{
    "event_type": "baas.automatic_pix.outgoing_recurrence.status_change",
    "origin_key": "8cb70dea-9fb0-4a68-9572-99a72849c8d6",
    "data": {
        "request_control_key": "98fc62fd-b0a0-4604-9bea-475e91a9dc82",
        "outgoing_recurrence_key": "8cb70dea-9fb0-4a68-9572-99a72849c8d6",
        "outgoing_recurrence_status": "approved",
        "journey_type": "journey_two",
        "outgoing_recurrence_data": {
            "minimum_recurrence_amount": 123.45,
            "recurrence_amount": null
        },
        "payment_conciliation_batch_key": "uuid" or null
    }
}

旅程 3 – journey_three​

Request Body: 旅程 3
{
    "event_type": "baas.automatic_pix.outgoing_recurrence.status_change",
    "origin_key": "8cb70dea-9fb0-4a68-9572-99a72849c8d6",
    "data": {
        "request_control_key": "98fc62fd-b0a0-4604-9bea-475e91a9dc82",
        "outgoing_recurrence_key": "8cb70dea-9fb0-4a68-9572-99a72849c8d6",
        "outgoing_recurrence_status": "approved",
        "journey_type": "journey_three",
        "outgoing_recurrence_data": {
            "minimum_recurrence_amount": 123.45,
            "recurrence_amount": null,
            "qr_code_initial_payment_data": {
                "receiver_conciliation_id": "id",
                "transaction_data": {
                    "transaction_key": "uuid",
                    "pix_transfer_key": "uuid",
                    "end_to_end_id": "end_to_end"
                }
            },
            "payment_conciliation_batch_key": "uuid" or null
        }
    }
}

旅程 4 – journey_four​

Request Body: 旅程 4
{
    "event_type": "baas.automatic_pix.outgoing_recurrence.status_change",
    "origin_key": "8cb70dea-9fb0-4a68-9572-99a72849c8d6",
    "data": {
        "request_control_key": "98fc62fd-b0a0-4604-9bea-475e91a9dc82",
        "outgoing_recurrence_key": "8cb70dea-9fb0-4a68-9572-99a72849c8d6",
        "outgoing_recurrence_status": "approved",
        "journey_type": "journey_four",
        "outgoing_recurrence_data": {
            "minimum_recurrence_amount": 123.45,
            "recurrence_amount": null
        },
        "qr_code_initial_payment_data": {
            "receiver_conciliation_id": "id",
            "transaction_data": {
                "transaction_key": "uuid" or null,
                "pix_transfer_key": "uuid" or null,
                "end_to_end_id": "end_to_end" or null
            }
        },
        "payment_conciliation_batch_key": "uuid" or null
    }
}
注意

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

Webhook Body Params​

字段类型描述字符数
event_type *string报告的事件类型（如 baas.automatic_pix.outgoing_recurrence.status_change）。100
origin_key *string事件的唯一来源标识符（UUID）。36
data *Object包含自动定期付款详情的主对象。Objeto data

Objeto data​

字段类型描述字符数
request_control_key *string请求的唯一控制键（UUID4）。36
outgoing_recurrence_key *string自动定期付款的唯一标识符（UUID）。36
outgoing_recurrence_status *string定期付款的状态（如 approved、pending、rejected 等）。30
journey_type *enumeratorPix 自动支付授权的对应旅程类型（journey_one、journey_two 等）。Enumeradores journey_type
outgoing_recurrence_data *Object包含定期付款和旅程特定信息的对象。Objeto outgoing_recurrence_data
payment_conciliation_batch_keystring付款对账的分组标识符。可以为 null。36 或 null
qr_code_initial_payment_dataObject（旅程 3 和 4）初始 QR 码付款数据详情（如有）。Objeto qr_code_initial_payment_data

Objeto outgoing_recurrence_data​

字段类型描述字符数
minimum_recurrence_amountnumber授权定期付款的最低金额。-
recurrence_amountnumber定期付款总金额（不适用时可为 null）。-
qr_code_initial_payment_dataObject（旅程 3）使用 QR 码时初始付款的详细数据。Objeto qr_code_initial_payment_data
payment_conciliation_batch_keystring付款批次/对账标识符。36

Objeto qr_code_initial_payment_data​

字段类型描述字符数
receiver_conciliation_idstring接收方对账的唯一标识符。-
transaction_dataObject与初始 QR 码关联的交易详情。Objeto transaction_data

Objeto transaction_data​

字段类型描述字符数
transaction_keystring交易唯一键。36
pix_transfer_keystring关联 Pix 转账的标识符。36
end_to_end_idstringPix 端到端标识符。32

Enumeradores journey_type​

枚举值描述
journey_one银行应用内直接通知
journey_two定期收费的 QR 码体验
journey_three即时付款 + QR 码定期付款
journey_fourPix 操作后的定期授权

付款订单状态 Webhook​

此 Webhook 用于报告 Pix 自动支付付款订单的状态变更，包括取消、已付款和拒绝。

Webhook Request Body​

状态：已取消（cancelled）​

Request Body: 付款订单已取消
{
  "event_type": "baas.automatic_pix.payment_order.status_change",
  "origin_key": "8cb70dea-9fb0-4a68-9572-99a72849c8d6",
  "data": {
    "payment_order_key": "8cb70dea-9fb0-4a68-9572-99a72849c8d6",
    "payment_order_spi_id": "RR2222222220240429njua7shf40k",
    "outgoing_recurrence_key": "98fc62fd-b0a0-4604-9bea-475e91a9dc82",
    "payment_order_status": "cancelled",
    "receiver_conciliation_id": "cac0b5f7-4ee2-40f1-b2ad-16902506503d",
    "transaction_amount": 125.53,
    "payment_order_conciliation_batch_key": "21fc62fd-b0a0-4604-9bea-475e91a9dc82",
    "transaction_key": "21fc62fd-b0a0-4604-9bea-475e91a9dc56",
    "incoming_pix_transfer_key": "21fc62fd-b0a0-4604-9bea-475e91a9dc56"
  }
}

状态：已付款（paid）​

Request Body: 付款订单已付款
{
  "event_type": "baas.automatic_pix.payment_order.status_change",
  "origin_key": "8cb70dea-9fb0-4a68-9572-99a72849c8d6",
  "data": {
    "payment_order_key": "8cb70dea-9fb0-4a68-9572-99a72849c8d6",
    "payment_order_spi_id": "RR2222222220240429njua7shf40k",
    "outgoing_recurrence_key": "98fc62fd-b0a0-4604-9bea-475e91a9dc82",
    "payment_order_status": "paid",
    "receiver_conciliation_id": "cac0b5f7-4ee2-40f1-b2ad-16902506503d",
    "transaction_amount": 125.53,
    "payment_order_conciliation_batch_key": "21fc62fd-b0a0-4604-9bea-475e91a9dc82",
    "transaction_key": "21fc62fd-b0a0-4604-9bea-475e91a9dc56",
    "incoming_pix_transfer_key": "21fc62fd-b0a0-4604-9bea-475e91a9dc56",
    "paid_at": "2021-10-22T20:30:23.459Z"
  }
}

状态：已拒绝（rejected）​

Request Body: 付款订单已拒绝
{
  "event_type": "baas.automatic_pix.payment_order.status_change",
  "origin_key": "8cb70dea-9fb0-4a68-9572-99a72849c8d6",
  "data": {
    "payment_order_key": "8cb70dea-9fb0-4a68-9572-99a72849c8d6",
    "payment_order_spi_id": "RR2222222220240429njua7shf40k",
    "outgoing_recurrence_key": "98fc62fd-b0a0-4604-9bea-475e91a9dc82",
    "payment_order_status": "rejected",
    "receiver_conciliation_id": "cac0b5f7-4ee2-40f1-b2ad-16902506503d",
    "transaction_amount": 125.53,
    "payment_order_conciliation_batch_key": "21fc62fd-b0a0-4604-9bea-475e91a9dc82"
  }
}
信息

被拒绝的付款订单在达到最大重试次数后发送（如定期付款允许重试）。此时，transaction_key 和 incoming_pix_transfer_key 字段不包含在载荷中。

Webhook Body Params - Payment Order​

字段类型描述字符数
event_type *string报告的事件类型（baas.automatic_pix.payment_order.status_change）。100
origin_key *string事件的唯一来源标识符（付款订单的 UUID）。36
data *Object包含付款订单详情的主对象。Objeto data

Objeto data (Payment Order)​

字段类型描述字符数
payment_order_key *string付款订单的唯一键（UUID）。36
payment_order_spi_id *string付款订单的 SPI 标识符。29
outgoing_recurrence_key *string关联的自动定期付款的唯一标识符（UUID）。36
payment_order_status *string付款订单状态（cancelled、paid、rejected）。30
receiver_conciliation_id *string接收方对账标识符（UUID）。36
transaction_amount *number付款订单的交易金额。-
payment_order_conciliation_batch_key *string关联的对账批次标识符（UUID）。36
transaction_keystring交易唯一键（仅出现在 cancelled 和 paid 状态时）。36
incoming_pix_transfer_keystring入账 Pix 转账标识符（仅出现在 cancelled 和 paid 状态时）。36
paid_atstring付款日期和时间（仅出现在 paid 状态时，ISO 8601 格式）。-

Enumeradores payment_order_status​

枚举值描述
cancelled付款订单被付款方或接收方取消。
paid付款订单成功执行。
rejected付款订单在重试耗尽后被拒绝。

付款订单尝试状态 Webhook​

此 Webhook 用于报告 Pix 自动支付付款订单执行尝试的状态变更，尤其是拒绝尝试及拒绝原因。

Webhook Request Body​

状态：已拒绝（rejected）​

Request Body: 付款订单尝试已拒绝
{
  "event_type": "baas.automatic_pix.payment_order_attempt.status_change",
  "origin_key": "8cb70dea-9fb0-4a68-9572-99a72849c8d6",
  "data": {
    "request_control_key": "8cb70dea-9fb0-4a68-9572-99a72849c8d6",
    "payment_order_key": "8cb70dea-9fb0-4a68-9572-99a72849c8d6",
    "payment_order_attempt_key": "21fc62fd-b0a0-4604-9bea-475e91a9dc82",
    "payment_order_status": "pending",
    "payment_order_attempt_status": "rejected",
    "transaction_amount": 125.53,
    "reason": "Conta de destino inexistente",
    "outgoing_recurrence_key": "98fc62fd-b0a0-4604-9bea-475e91a9dc82"
  }
}
信息

每当付款订单的执行尝试被 SPI 拒绝时，都会发送此 Webhook。根据定期付款配置和拒绝原因，付款订单可能会有新的尝试。reason 字段包含基于 Bacen 错误代码的拒绝原因描述。

Webhook Body Params - Payment Order Attempt​

字段类型描述字符数
event_type *string报告的事件类型（baas.automatic_pix.payment_order_attempt.status_change）。100
origin_key *string事件的唯一来源标识符（付款订单的 UUID）。36
data *Object包含付款订单尝试详情的主对象。Objeto data

Objeto data (Payment Order Attempt)​

字段类型描述字符数
request_control_key *string请求的唯一控制键（付款订单的 UUID）。36
payment_order_key *string关联的付款订单的唯一键（UUID）。36
payment_order_attempt_key *string付款尝试的唯一键（UUID）。36
payment_order_status *string付款订单的当前状态（pending、accepted、cancelled 等）。30
payment_order_attempt_status *string付款尝试的状态（rejected）。30
transaction_amount *number付款尝试的交易金额。-
reason *string尝试拒绝原因（基于 Bacen 错误代码的错误描述）。200
outgoing_recurrence_key *string关联的自动定期付款的唯一标识符（UUID）。36

Enumeradores payment_order_attempt_status​

枚举值描述
rejected付款尝试因特定错误被 SPI 拒绝。

未结算的付款订单尝试 Webhook​

此 Webhook 用于通知付款订单尝试已被接受但未在预期时间内结算。

Webhook Request Body​

Request Body: 未结算的付款订单尝试
{
    "webhook_type": "baas.automatic_pix.payment_order_attempt.not_liquidated",
    "webhook_datetime": "2025-10-22T21:15:00.000Z",
    "data": {
        "payment_order_key": "8cb70dea-9fb0-4a68-9572-99a72849c8d6",
        "payment_order_spi_id": "RR2222222220240429njua7shf40k",
        "outgoing_recurrence_key": "98fc62fd-b0a0-4604-9bea-475e91a9dc82",
        "payment_order_status": "pending",
        "receiver_conciliation_id": "cac0b5f7-4ee2-40f1-b2ad-16902506503d",
        "transaction_amount": "125.53",
        "payment_order_conciliation_batch_key": "21fc62fd-b0a0-4604-9bea-475e91a9dc82",
        "payment_order_attempt_key": "21fc62fd-b0a0-4604-9bea-475e91a9dc83",
        "payment_order_attempt_status": "not_liquidated",
        "due_date": "2025-10-22",
        "end_to_end_id": "E1234567890123456789012"
    }
}

Webhook Body Param​

字段类型描述最大字符数
webhook_typestring定义报告事件类型的枚举值。100
webhook_datetimestringWebhook 发送日期和时间。20
payment_order_keyuuid4付款订单的唯一标识键。36
payment_order_spi_idstringSPI 中付款订单的标识符。50
outgoing_recurrence_keyuuid4关联的出账定期付款的唯一标识键。36
payment_order_statusstring付款订单的当前状态。Enumeradores payment_order_status
receiver_conciliation_idstring接收方对账标识。36
transaction_amountnumber付款订单的交易金额。-
payment_order_conciliation_batch_keyuuid4关联的对账批次的唯一标识键。36
payment_order_attempt_keyuuid4付款订单尝试的唯一标识键。36
payment_order_attempt_statusstring付款订单尝试的状态。Enumeradores payment_order_attempt_status
due_datestring付款订单尝试的到期日期（YYYY-MM-DD 格式）。10
end_to_end_idstringSPI 内 Pix 交易的幂等键。32

Enumeradores payment_order_status​

枚举值描述
pending_conciliation等待对账。
pending待付款。
paid成功付款。
rejected已拒绝，不会处理。
cancelled付款前已取消。

Enumeradores payment_order_attempt_status​

枚举值描述
sent付款尝试已发送。
accepted付款尝试已接受。
rejected付款尝试因特定错误被 SPI 拒绝。
not_liquidated付款尝试已接受但未在预期时间内结算。