Webhooks

什么是 webhook（callback）

webhook（也称为 callback）是当事件发生时，PayZu 向您的服务器发送的 POST 请求。与常规 API（由您调用 PayZu）相反，这里是反向的：由 PayZu 调用您。

设想一笔 Pix 收款。您创建了它，向客户展示了 QR，现在需要知道客户何时付款。有两个选择：

1. 轮询，每隔 X 秒不停地问"付了吗？付了吗？"（成本高、慢、不必要）。
2. webhook，让 PayZu 在款项到账时立即通知您（即时、高效、推荐）。

如何配置

您可以通过两种方式接收通知：

• 已注册的 webhook（推荐）：在 POST /user/webhooks 中注册一个持久化 URL，配置 HMAC 密钥和事件筛选。同一个 URL 适用于所有交易。
• 每笔交易的 callbackUrl：在每笔创建的交易 body 的 callbackUrl 字段中传入 URL：

{
  "amount": 99.90,
  "callbackUrl": "https://your-site.com/webhooks/payzu",
  "clientReference": "pedido-2025-001"
}

每当该交易状态发生变化时（PENDING → COMPLETED，COMPLETED → REFUNDED 等），PayZu 都会向该 URL 发送 callback。

事件

POST /user/webhooks 的 events 字段定义哪些变化触发通知。留空则接收全部。

有七个事件对应交易的 status，每个值对应一个：

三个事件不对应 status：

重试系统

PayZu 的 webhook 拥有强大的重试系统，能够在临时故障下也确保 投递成功。PayZu 会以指数退避加抖动的方式最多重试 40 次发送 同一个 callback，从而更均匀地分散负载，避免请求峰值。

安全性

为保障完整性和安全性，请限制对您 webhook endpoint 的访问。 向支持团队索取 PayZu Processamento 的官方 IP，仅接受来自该来源 的 callback。

投递的头信息

INFRACTION_CHANGED 到达时交易的 status 保持不变，因此当您订阅 多个事件时，X-Callback-Event 是区分投递的依据。

HMAC 验证

每次签名的投递都带有 X-Callback-Signature。签名所用的密钥取决于目标：

在处理 body 之前先验证签名：

Node.js 示例，使用 crypto.timingSafeEqual 以恒定时间比较签名：

const crypto = require("node:crypto");

const TOLERANCE_SECONDS = 300;

function verifyCallbackSignature(request, webhookSecret) {
  const header = request.headers["x-callback-signature"];
  if (typeof header !== "string") return false;

  const parts = Object.fromEntries(
    header.split(",").map((part) => part.trim().split("=")),
  );
  const timestamp = Number(parts.t);
  const signature = parts.v1;

  if (!Number.isInteger(timestamp) || !/^[0-9a-f]{64}$/i.test(signature ?? "")) {
    return false;
  }

  const age = Math.abs(Math.floor(Date.now() / 1000) - timestamp);
  if (age > TOLERANCE_SECONDS) return false;

  const expected = crypto
    .createHmac("sha256", webhookSecret)
    .update(`${timestamp}.${request.rawBody}`)
    .digest("hex");

  return crypto.timingSafeEqual(
    Buffer.from(expected, "hex"),
    Buffer.from(signature, "hex"),
  );
}

payload 字段

标识

状态与金额

COMMISSION 标识贷记到您账户的佣金入账，会伴随 TRANSACTION_COMPLETED 到达。

生成的收款单（存款）

付款方

收款方

通过 Pix 密钥的支付

结算与退款

时间戳

违规（Pix 争议）

最佳实践

• 快速响应：在 5 秒内返回 2xx。将繁重的处理放在 队列/worker 中，不要在 handler 内做。
• 幂等性：使用 id 加事件进行去重，而不仅仅是 id + status。 同一个 callback 可能到达多次（重试、连续变化），并且 INFRACTION_CHANGED 不会改变 status。参见 callback 去重。
• 使用 clientReference：在创建交易时传入外部标识符。 会在 callback 中返回，便于与您的订单关联。
• 按 IP 限制：仅接受来自 PayZu 官方 IP 的 callback。
• 返回 2xx 以结束投递：2xx 范围以外的任何响应， 包括 4xx，以及任何超时都会进入同样的最多 40 次重试循环。要 停止重发，请返回 2xx 并在您这边处理错误。
• 在日志中掩码 payerDocument：不做掩码就打印 payload 会带来 LGPD 风险。

测试与重发

本地测试

通过 ngrok 或 Cloudflare Tunnel 暴露您的 localhost，然后手动发送 payload：

curl -X POST https://your-tunnel.ngrok.io/webhooks/payzu \
  -H "Content-Type: application/json" \
  -d '{
    "id": "PAYZU20260811K7M2X9QP4T000000",
    "type": "DEPOSIT",
    "status": "COMPLETED",
    "amount": 99.90,
    "clientReference": "order-1234",
    "virtualAccount": "loja-rj-01",
    "paidAt": "2026-08-11T10:46:26.986Z"
  }'

await fetch('https://your-tunnel.ngrok.io/webhooks/payzu', {
  method: 'POST',
  headers: { 'Content-Type': 'application/json' },
  body: JSON.stringify({
    id: 'PAYZU20260811K7M2X9QP4T000000',
    type: 'DEPOSIT',
    status: 'COMPLETED',
    amount: 99.90,
    clientReference: 'order-1234',
    virtualAccount: 'loja-rj-01',
    paidAt: '2026-08-11T10:46:26.986Z',
  }),
});

import requests

requests.post(
    'https://your-tunnel.ngrok.io/webhooks/payzu',
    headers={'Content-Type': 'application/json'},
    json={
        'id': 'PAYZU20260811K7M2X9QP4T000000',
        'type': 'DEPOSIT',
        'status': 'COMPLETED',
        'amount': 99.90,
        'clientReference': 'order-1234',
        'virtualAccount': 'loja-rj-01',
        'paidAt': '2026-08-11T10:46:26.986Z',
    },
)

重发真实的 callback

重发的 endpoint 取决于目标 URL 的配置位置。

在交易中传入的 callbackUrl：

• POST /user/callbacks/resend/{transactionId}，单笔交易
• POST /user/callbacks/resend，按筛选条件批量，必须指定日期窗口

两者仅覆盖已填写 callbackUrl 的交易，不会为已注册 webhook 生成投递。

已注册的 webhook：

• POST /user/callbacks/resend/webhook/{webhookId}，重新入队该 webhook 上失败的投递

按 webhook 重发会针对每对交易与事件重新处理一次投递， 将 300 起的响应和无响应视为失败。status 已与当前交易状态 不匹配的事件在重发时依然会被丢弃。

响应在 enqueued 中返回，包含 count（接受重发的总数）、truncated 和 items。items 列表在 500 条时截断。当 truncated 为 true 时， 重发依然覆盖所有 count，只是响应中的列表被截断。

检查历史记录

PayZu 会保存所有投递尝试。用于排查失败很有用：

• GET /user/callbacks，分页列表
• GET /user/callbacks/{id}，包含 status code、response body、response time 的详情

下一步