发送 Pix

通过 Pix 密钥向外部收款人付款（付款前会在 DICT 目录中核对收款人信息），或扫码支付，并可跟踪状态直至下载付款凭证。

支付前，通过 GET /pix/key 查询 DICT 以校验收款人。该接口确认密钥存在并返回持有人信息，便于与预期值进行比对。

curl "https://api.payzu.processamento.com/v1/pix/key?pixKey=joao@example.com" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json"

const url = new URL('https://api.payzu.processamento.com/v1/pix/key');
url.searchParams.set('pixKey', 'joao@example.com');

const res = await fetch(url, {
  headers: {
    Authorization: `Bearer ${process.env.PAYZU_TOKEN}`,
    'Content-Type': 'application/json',
  },
});
const dict = await res.json();

更多详情请参阅 DICT 查询。

执行付款

使用 POST /withdraw 并传入已校验的密钥。pixType 支持：cpf、cnpj、phone、email、evp。

curl -X POST https://api.payzu.processamento.com/v1/withdraw \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "amount": 250.00,
    "pixKey": "joao@example.com",
    "pixType": "email",
    "callbackUrl": "https://seusite.com.br/webhooks/payzu",
    "clientReference": "payout-2025-08-001",
    "description": "Pagamento referente ao pedido #1234"
  }'

const res = await fetch('https://api.payzu.processamento.com/v1/withdraw', {
  method: 'POST',
  headers: {
    Authorization: `Bearer ${process.env.PAYZU_TOKEN}`,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    amount: 250.00,
    pixKey: 'joao@example.com',
    pixType: 'email',
    callbackUrl: 'https://seusite.com.br/webhooks/payzu',
    clientReference: 'payout-2025-08-001',
    description: 'Pagamento referente ao pedido #1234',
  }),
});
const withdraw = await res.json();

方式 2：通过 QR Code

提前读取 QR（可选）

如果 QR 是从外部客户端扫描所得，支付前可通过 POST /pix/qrcode/read 提取其数据。

curl -X POST https://api.payzu.processamento.com/v1/pix/qrcode/read \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{ "qrCode": "00020126870014br.gov.bcb.pix..." }'

PayZu 同时处理动态和静态 QR Code。

执行支付

POST /withdraw/qrcode。如果 QR 已内嵌金额，可省略 amount。

curl -X POST https://api.payzu.processamento.com/v1/withdraw/qrcode \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "qrCode": "00020126870014br.gov.bcb.pix...",
    "amount": 100.00,
    "callbackUrl": "https://seusite.com.br/webhooks/payzu",
    "clientReference": "payout-qr-2025-08-001"
  }'

跟踪状态

Pix 付款初始为 PENDING，随后流转至 COMPLETED、CANCELED 或 ERROR。每次状态变更都会触发 callback。如需通过 GET /withdraw 手动查询：

curl "https://api.payzu.processamento.com/v1/withdraw?clientReference=payout-2025-08-001" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json"

凭证

状态变为 COMPLETED 后，通过 GET /withdraw/proof/{id} 下载官方凭证：

curl "https://api.payzu.processamento.com/v1/withdraw/proof/PAYZU2025..." \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json"

常见错误

错误	解决方案
余额不足	事先查询 `GET /user/balance`
Pix 密钥无效	先通过 DICT 校验
金额低于最低限额	`amount` ≥ R$ 0,01（密钥）或 ≥ R$ 0,10（QR）
收款人不一致	支付前将 `dict.name` 与预期值进行比对