快速入门

创建账户

请在 abrirconta.payzu.com.br 开通账户。审核通过后,您将获得:

Bearer token,用于所有请求。详见身份认证。
Base URL,https://pix.payzu.io/v1。

请将 token 保存在 vault 中(Google Secret Manager、AWS Secrets 等)。切勿提交到代码仓库,也不要在前端暴露。

验证身份认证

要确认 token 是否生效,可通过 GET /user/balance 查询余额。

curl https://pix.payzu.io/v1/user/balance \
  -H "Authorization: Bearer SEU_TOKEN" \
  -H "Content-Type: application/json"

const res = await fetch('https://pix.payzu.io/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 见参考文档。

curl -X POST https://pix.payzu.io/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"
  }'

const res = await fetch('https://pix.payzu.io/v1/pix', {
  method: 'POST',
  headers: {
    Authorization: `Bearer ${process.env.PAYZU_TOKEN}`,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    amount: 10.90,
    generatedName: 'João da Silva',
    generatedDocument: '12345678909',
    callbackUrl: 'https://seusite.com.br/webhooks/payzu',
    clientReference: 'pedido-2025-001',
  }),
});
const charge = await res.json();

响应包含 qrCodeText(复制粘贴码)、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": "PZ_xxx",
  "status": "COMPLETED",
  "amount": 10.90,
  "clientReference": "pedido-2025-001",
  "endToEndId": "E18236120202511231046s1235ee7",
  "paidAt": "2026-05-21T10:46:26.986Z"
}

重试机制、完整 payload 及安全相关详情见 Webhooks。

后续步骤

发起一笔付款查询账户明细在 Scalar 中试用

创建账户

验证身份认证

创建首笔 Pix 收款

接收 callback

后续步骤

On this page