从在控制台创建凭证，到第一笔已支付的收款，并由你服务器上收到的 Webhook 确认。
本指南中的调用都发往生产环境：这里创建的收款是真实的。
创建凭证
在数字账户控制台 hub.payzu.com.br 中打开凭证区域，创建一个带有集成所需作用域的凭证。创建时需要输入账户持有人的操作 PIN。
本指南请勾选 PAYMENT_WRITE、PAYMENT_READ 和 WEBHOOK_WRITE。每个作用域允许的操作见作用域。
页面会显示 client_id、client_secret 和凭证令牌（pzu_…）。
client_secret 只显示一次。离开页面前请保存好。
用凭证换取令牌
把 client_id 和 client_secret 发送到 POST /oauth/token。返回的令牌有效期 15 分钟。
curl -X POST https://api.hub.payzu.com.br/api/v1/oauth/token \
-u "$PAYZU_CLIENT_ID:$PAYZU_CLIENT_SECRET" \
-d 'grant_type=client_credentials'const credentials = Buffer.from(`${process.env.PAYZU_CLIENT_ID}:${process.env.PAYZU_CLIENT_SECRET}`).toString('base64');
const response = await fetch('https://api.hub.payzu.com.br/api/v1/oauth/token', {
method: 'POST',
headers: {
Authorization: `Basic ${credentials}`,
'Content-Type': 'application/x-www-form-urlencoded',
},
body: 'grant_type=client_credentials',
});
const { access_token, expires_in } = await response.json();{
"access_token": "eyJhbGciOiJkaXIiLCJlbmMiOiJBMjU2R0NNIn0..mQ3Zy1hbVhpbXBsZQ.ZXhlbXBsbw.c2lnbmF0dXJl",
"token_type": "Bearer",
"expires_in": 900,
"scope": "PAYMENT_WRITE PAYMENT_READ WEBHOOK_WRITE"
}在其他调用中，把 access_token 放在 Authorization: Bearer 中。下面的示例中，它保存在 $PAYZU_TOKEN 里。令牌过期后，API 返回 401 和 TOKEN_INVALID：在同一路由再获取一个。
注册 Webhook
用 POST /transactions/webhooks（作用域 WEBHOOK_WRITE）注册你服务器上接收 Webhook 的 URL。URL 必须是 HTTPS 且可公开访问。
curl -X POST https://api.hub.payzu.com.br/api/v1/transactions/webhooks \
-H "Authorization: Bearer $PAYZU_TOKEN" \
-H "Content-Type: application/json" \
-d '{
"url": "https://sualoja.com.br/webhooks/payzu",
"events": ["PAYMENT_PAID", "PAYMENT_EXPIRED"]
}'const res = await fetch('https://api.hub.payzu.com.br/api/v1/transactions/webhooks', {
method: 'POST',
headers: {
Authorization: `Bearer ${process.env.PAYZU_TOKEN}`,
'Content-Type': 'application/json',
},
body: JSON.stringify({
url: 'https://sualoja.com.br/webhooks/payzu',
events: ['PAYMENT_PAID', 'PAYMENT_EXPIRED'],
}),
});
const { id, secret } = await res.json();201 响应带有为每个 Webhook 签名的 secret。它只出现在这个响应中：请保存好。也可以在控制台中注册。
如果返回 403 和 TOKEN_MISSING_SCOPE，说明凭证缺少某个作用域；缺少的作用域名称在 details.scope 中。
创建收款
用 POST /transactions/payment（作用域 PAYMENT_WRITE）创建一笔收款。金额以分为单位：1500 即 R$ 15,00。
curl -X POST https://api.hub.payzu.com.br/api/v1/transactions/payment \
-H "Authorization: Bearer $PAYZU_TOKEN" \
-H "Content-Type: application/json" \
-d '{
"amount": 1500,
"method": "PIX",
"description": "Pedido 4821",
"externalRef": "pedido-4821",
"metadata": { "pedido": "4821", "canal": "checkout-web" },
"customer": { "name": "Maria Souza", "document": "52998224725" }
}'const res = await fetch('https://api.hub.payzu.com.br/api/v1/transactions/payment', {
method: 'POST',
headers: {
Authorization: `Bearer ${process.env.PAYZU_TOKEN}`,
'Content-Type': 'application/json',
},
body: JSON.stringify({
amount: 1500,
method: 'PIX',
description: 'Pedido 4821',
externalRef: 'pedido-4821',
metadata: { pedido: '4821', canal: 'checkout-web' },
customer: { name: 'Maria Souza', document: '52998224725' },
}),
});
const cobranca = await res.json();201 响应返回 status: "PENDING" 的收款，Pix 复制粘贴码在 pix.qrCodeText 中。把它展示给客户，并用它生成二维码。用同一个 externalRef 重复调用会返回同一笔收款（200），不会再创建一笔。
接收 PAYMENT_PAID
客户付款后，你的服务器会收到 PAYMENT_PAID：
POST /webhooks/payzu
Content-Type: application/json
X-Payzu-Event: PAYMENT_PAID
X-Payzu-Delivery: cmu1r7x2k000a01s6h4f2b9qd
X-Payzu-Timestamp: 1791210790441
X-Payzu-Signature: sha256=8f3b2c1d...
{
"event": "PAYMENT_PAID",
"id": "cmu1r7x2k000a01s6h4f2b9qd",
"sentAt": "2026-10-05T14:33:10.441Z",
"accountId": "cmu0z8k2a000001s6acct0001",
"data": {
"paymentId": "cmu2wbljx0000e8gtlic8q1gi",
"status": "PAID",
"amount": 1500,
"serviceFee": 105,
"netAmount": 1395,
"metadata": { "pedido": "4821", "canal": "checkout-web" },
"externalRef": "pedido-4821",
"endToEndId": "E99999999202610051433a1b2c3d4e5f"
}
}用注册 Webhook 时得到的 secret 校验签名，方法见 Webhooks，并在 10 秒内返回任意 2xx。在这里，也就是收到 PAYMENT_PAID 时放行订单：创建时的 externalRef 和 metadata 会在 data 中返回。
不等 Webhook 直接查询
用 GET /transactions/payment/{paymentId}（作用域 PAYMENT_READ）查询收款，使用创建响应中的 id 或 Webhook 中的 paymentId：
curl https://api.hub.payzu.com.br/api/v1/transactions/payment/hubp-20261005K7Q2M9XB4T127431 \
-H "Authorization: Bearer $PAYZU_TOKEN"const res = await fetch('https://api.hub.payzu.com.br/api/v1/transactions/payment/hubp-20261005K7Q2M9XB4T127431', {
headers: {
Authorization: `Bearer ${process.env.PAYZU_TOKEN}`,
},
});
const cobranca = await res.json();要查找某个订单的收款，请使用带 ?externalRef= 的列出收款。