从零到第一笔 Pix 收款落到你系统里，用不了十分钟：开户、测 token、创建一笔收款、收到确认回调。
Pix
开户
在 abrirconta.payzu.com.br 开通账户。审核通过后您将获得：
- Bearer token，用于所有请求。详见 认证。
- Base URL：
https://api.payzu.processamento.com/v1。
请将 token 保存在密钥库中（Google Secret Manager、AWS Secrets 等）。 切勿提交到代码仓库，也不要暴露在前端。
测试认证
为确认 token 有效，请使用 GET /user/balance endpoint 查询账户余额。
curl https://api.payzu.processamento.com/v1/user/balance \
-H "Authorization: Bearer SEU_TOKEN" \
-H "Content-Type: application/json"const res = await fetch('https://api.payzu.processamento.com/v1/user/balance', {
headers: {
Authorization: `Bearer ${process.env.PAYZU_TOKEN}`,
'Content-Type': 'application/json',
},
});
const balance = await res.json();如果返回包含余额的 JSON，说明认证成功。如果返回 401，请检查 token（空格、编码）或联系支持。详见 术语表中的 HTTP 状态码。
创建首笔 Pix 收款
通过 POST /pix 创建收款。完整 schema 参见 API 参考。
curl -X POST https://api.payzu.processamento.com/v1/pix \
-H "Authorization: Bearer SEU_TOKEN" \
-H "Content-Type: application/json" \
-d '{
"amount": 10.90,
"generatedName": "João da Silva",
"generatedDocument": "12345678909",
"callbackUrl": "https://seusite.com.br/webhooks/payzu",
"clientReference": "pedido-2025-001"
}'使用官方 payzu-pix SDK：
示例使用 ESM 和顶层 await。请保存为 .mjs 文件(或在 package.json 中设置 "type": "module")。
npm install payzu-piximport { PayZu } from 'payzu-pix';
const payzu = new PayZu({ token: process.env.PAYZU_TOKEN });
const charge = await payzu.pix.create({
amount: 10.90,
generatedName: 'João da Silva',
generatedDocument: '12345678909',
callbackUrl: 'https://seusite.com.br/webhooks/payzu',
clientReference: 'pedido-2025-001',
});
console.log(charge.id, charge.status, charge.qrCodeText);响应返回 qrCodeText（copia-e-cola）、qrCodeUrl 以及交易的 id。各字段在 术语表 中均有说明。
金额始终以**雷亚尔（BRL）**为单位。10.90 表示 R$ 10,90。
接收 callback
当付款方完成 Pix 支付后，PayZu 会向您提供的 callbackUrl 发送 POST 请求，携带更新后的交易对象（status: "COMPLETED"）。请在 5 秒内返回 2xx 响应。
POST /webhooks/payzu
Content-Type: application/json
{
"id": "PAYZU20260811K7M2X9QP4T000000",
"status": "COMPLETED",
"amount": 10.90,
"clientReference": "pedido-2025-001",
"endToEndId": "E18236120202608111046s1235ee7a91",
"paidAt": "2026-08-11T10:46:26.986Z"
}重试、完整 payload 和安全性详情请参见 Webhooks。如需手动检查或重发，请使用 GET /user/callbacks。