Webhooks
每当状态变化时,API 都会向创建充值或提现时提供的 callbackUrl 发送 POST 请求。请求体为 JSON,包含更新后的交易数据。
无需让您的系统不断询问"已支付了吗?",当事件发生时,PayZu 会主动调用您。
在每次创建请求中传入 callbackUrl(POST /pix、POST /withdraw 等):
{
"amount": 99.90,
"callbackUrl": "https://seusite.com.br/webhooks/payzu",
"clientReference": "order-2025-001"
}
该 endpoint 必须可公网访问,并在 5 秒内返回 HTTP 2xx,接受:
Content-Type: application/json
当未在 5 秒内收到 2xx 响应时,PayZu 会以指数退避加抖动的方式重新发送 callback,最多 72 次。
| 字段 | 类型 | 说明 |
|---|
id | string | PayZu 中交易的唯一标识符 |
clientReference | string | 您提供的外部标识符 |
type | string | DEPOSIT 或 WITHDRAW |
status | string | 参见交易状态 |
amount | number | 金额,单位雷亚尔(BRL) |
serviceFeeCharged | number | 已收取的手续费 |
| 字段 | 类型 | 说明 |
|---|
qrCodeText | string | Pix 复制粘贴码(EMV) |
qrCodeBase64 | string | QR Code 图像的 Base64 编码 |
qrCodeUrl | string | QR Code 的 PNG 公开 URL |
generatedName | string | 关联名称 |
generatedDocument | string | CPF 或 CNPJ |
generatedEmail | string | 关联邮箱 |
| 字段 | 类型 | 说明 |
|---|
payerName | string | 付款人姓名(如果有) |
payerDocument | string | 付款人证件号 |
payerInstitutionIspb | string | 付款人所属机构的 ISPB |
payerInstitutionName | string | 机构名称 |
| 字段 | 类型 | 说明 |
|---|
receiverName | string | 收款人姓名(如果提供) |
receiverDocument | string | 收款人证件号 |
receiverInstitutionIspb | string | 收款人所属机构的 ISPB |
receiverInstitutionName | string | 机构名称 |
| 字段 | 类型 | 说明 |
|---|
withdrawPixKey | string | 提现使用的 Pix 密钥 |
withdrawPixType | string | 参见密钥类型 |
| 字段 | 类型 | 说明 |
|---|
createdAt | string | 交易创建时间(ISO 8601) |
updatedAt | string | 最近更新时间 |
paidAt | string | null | 支付时间(若尚未支付则为 null) |
endToEndId | string | Pix 的 EndToEnd ID |
infraction | object | undefined | 仅在发生 MED 争议时出现,参见术语表 |
- 快速响应:在 5 秒内返回
2xx。耗时处理放入队列异步执行
- idempotência:存储
id + status 用于去重
- 使用
clientReference:在创建时传入外部标识符
- 按 IP 限制:仅接受来自 PayZu 官方 IP 的 callback
