交易 Webhook

Webhook 是交易事件发生时 API 自动发送的通知。

本页遵循 API 当前的契约：所有事件的基础 payload 相同，变化的是事件前缀以及各阶段特有的附加字段。

支持的事件

事件	发送时机
TRANSACTION_CREATED	交易创建时
TRANSACTION_PAID	交易被支付时
TRANSACTION_INFRACTION	交易进入违规状态时
TRANSACTION_REFUNDED	交易被退款时

payload 格式

字段	类型	必填	说明
type	string (enum) - TRANSACTION_CREATED, TRANSACTION_PAID, TRANSACTION_INFRACTION, TRANSACTION_REFUNDED	是	Webhook 中发送的事件类型
data	object	是	交易数据

根层级的 type 字段用于标识事件。data 内部的 type 字段用于标识实体的操作类型。

基础 payload

以下字段出现在所有交易 Webhook 中。

字段	类型	必填	说明
id	string (UUID)	是	交易的唯一标识
amount	number	是	交易金额，以分为单位
paymentMethod	string (enum) - PIX	是	支付方式
externalCode	string	是	由集成方传入的外部参考编号
isInfoProduct	boolean	是	标识该交易是否为数字商品
createdAt	string (ISO)	是	创建日期
status	string (enum) - PENDING, PIX_QRCODE_GENERATED, PAID, PROCESSING_REFUND, PROCESSING_INFRACTION, REFUNDED, INFRACTION, FAILED, BLOCKED	是	PENDING：交易已创建，等待处理 PIX_QRCODE_GENERATED：PIX 二维码已生成，等待付款 PAID：交易已支付 PROCESSING_REFUND：退款处理中 PROCESSING_INFRACTION：违规处理中 REFUNDED：交易已退款 INFRACTION：交易已退款（MED） FAILED：处理出错 BLOCKED：因开启 MED 而被冻结
type	string (enum) - TRANSACTION	是	操作类型

各事件的差异

TRANSACTION_CREATED

仅使用基础 payload。

TRANSACTION_PAID

在基础 payload 之外，另增加：

字段	类型	必填	说明
endToEnd	string	否	交易的 end-to-end 标识
amountPaid	number	是	实际支付金额
paymentDate	string (ISO)	否	支付日期
payer	object	否	付款方信息（参见子对象 AccountHolder）
paymentReceipt	string	否	支付凭证的 URL

TRANSACTION_INFRACTION

在基础 payload 之外，另增加：

字段	类型	必填	说明
endToEnd	string	否	交易的 end-to-end 标识
infractionAmount	number	是	违规金额
infractionDate	string (ISO)	否	违规日期

TRANSACTION_REFUNDED

在基础 payload 之外，另增加：

字段	类型	必填	说明
endToEnd	string	否	交易的 end-to-end 标识
refundAmount	number	是	退款金额
refundDate	string (ISO)	否	退款日期
endToEndRefund	string	否	退款的 end-to-end 标识
refundReceipt	string	否	退款凭证的 URL

子对象

AccountHolder

字段	类型	必填	说明
type	string (enum) - PF, PJ	是	持有人类型
name	string	是	持有人姓名
document	string	是	持有人证件号
bankAccount	object	是	银行信息（参见子对象 BankAccount）
pix	object	是	持有人的 PIX 密钥（参见子对象 PixKeyVo）

BankAccount

字段	类型	必填	说明
type	string	是	账户类型
digit	string	是	账户校验位
ispb	string	是	银行的 ISPB

PixKeyVo

字段	类型	必填	说明
key	string	是	PIX 密钥
type	string	是	PIX 密钥类型

payload 示例

数据脱敏

敏感信息可能以 *** 脱敏显示。

{
  "type": "TRANSACTION_PAID",
  "data": {
    "id": "553e8400-e29b-41d4-a716-436251480000",
    "amount": 10000,
    "paymentMethod": "PIX",
    "externalCode": "TRANS-123",
    "isInfoProduct": false,
    "createdAt": "2026-03-06T12:49:04.681Z",
    "status": "PAID",
    "type": "TRANSACTION",
    "endToEnd": "E2E123456789",
    "amountPaid": 10000,
    "paymentDate": "2026-03-06T12:49:04.681Z",
    "paymentReceipt": "https://files.exemplo.com.br/receipts/transaction-553e8400-e29b-41d4-a716-436251480000.pdf",
    "payer": {
      "type": "PF",
      "name": "Fulano de Tal",
      "document": "***456789**",
      "bankAccount": {
        "type": "CHECKING",
        "digit": "7",
        "ispb": "12345678"
      },
      "pix": {
        "key": "12345678910",
        "type": "CPF"
      }
    }
  }
}