快速开始

开户

在 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"
  }'

const res = await fetch('https://api.payzu.processamento.com/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（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": "PAYZU20251123104518DF75D20A8F",
  "status": "COMPLETED",
  "amount": 10.90,
  "clientReference": "pedido-2025-001",
  "endToEndId": "E18236120202511231046s1235ee7",
  "paidAt": "2025-11-23T10:46:26.986Z"
}

重试、完整 payload 和安全性详情请参见 Webhooks。如需手动检查或重发，请使用 GET /user/callbacks。

开户

测试认证

创建首笔 Pix 收款

接收 callback

On this page