接收 Pix 付款

从生成收款、展示二维码，到第一时间得知客户已付款并将订单标记为已结清，全程用 curl 和 Node.js 演示。

生成收款单

endpoint：POST /pix。仅 amount 为必填项，以雷亚尔为单位，绝不用分；其他字段用于丰富 QR 和对账信息。

curl -X POST https://api.payzu.processamento.com/v1/pix \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "amount": 99.90,
    "generatedName": "João da Silva",
    "generatedDocument": "12345678909",
    "callbackUrl": "https://seusite.com.br/webhooks/payzu",
    "clientReference": "pedido-2025-001",
    "virtualAccount": "loja-rj-01",
    "expiresIn": 600
  }'

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: 99.90,
    generatedName: 'João da Silva',
    generatedDocument: '12345678909',
    callbackUrl: 'https://seusite.com.br/webhooks/payzu',
    clientReference: 'pedido-2025-001',
    virtualAccount: 'loja-rj-01',
    expiresIn: 600,
  }),
});
const charge = await res.json();

响应：

{
  "id": "PAYZU20260811R4TZ8WD1NC000000",
  "status": "PENDING",
  "amount": 99.90,
  "qrCodeText": "00020126870014br.gov.bcb.pix...",
  "qrCodeUrl": "https://api.payzu.processamento.com/v1/pix/qr-code/PAYZU20260811R4TZ8WD1NC000000",
  "clientReference": "pedido-2025-001",
  "virtualAccount": "loja-rj-01",
  "expiresAt": "2025-08-17T22:00:00.000Z"
}

向客户展示 QR Code

两种方式：

直接图片，在 <img> 中使用 qrCodeUrl：

<img src="https://api.payzu.processamento.com/v1/pix/qr-code/PAYZU2025..." />

复制粘贴，将 qrCodeText 显示在带按钮的 input 中：

<input value="00020126870014br.gov.bcb.pix2565..." readonly />
<button onclick="navigator.clipboard.writeText(qrCodeText)">复制</button>

PayZu 每笔收款生成动态 QR。

在付款时接收 callback

当客户完成 Pix 付款后，PayZu 将向您的 callbackUrl 发送 POST：

{
  "id": "PAYZU20260811R4TZ8WD1NC000000",
  "type": "DEPOSIT",
  "status": "COMPLETED",
  "amount": 99.90,
  "clientReference": "pedido-2025-001",
  "virtualAccount": "loja-rj-01",
  "endToEndId": "E60746948202508172200X7H4K2P9M5Q",
  "paidAt": "2025-08-17T22:00:12.000Z"
}

处理器示例：

import express from 'express';
const app = express();

app.post('/webhooks/payzu', express.json(), async (req, res) => {
  const tx = req.body;

  if (await isProcessed(tx.id, tx.status)) return res.status(200).end();

  if (tx.type === 'DEPOSIT' && tx.status === 'COMPLETED') {
    await markOrderPaid(tx.clientReference, tx);
  }

  res.status(204).end();
});

from flask import Flask, request
app = Flask(__name__)

@app.post('/webhooks/payzu')
def payzu_webhook():
    tx = request.get_json()
    if is_processed(tx['id'], tx['status']):
        return '', 200
    if tx['type'] == 'DEPOSIT' and tx['status'] == 'COMPLETED':
        mark_order_paid(tx['clientReference'], tx)
    return '', 204

请在 5 秒内以 2xx 响应；完整的重试策略请见 Webhooks。

通过 polling 后备查询

如果 callback 未送达，可直接通过 GET /pix 查询。接受 id、clientReference、endToEndId 或 virtualAccount，仅使用其中一个。

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

const res = await fetch(
  `https://api.payzu.processamento.com/v1/pix?clientReference=pedido-2025-001`,
  {
    headers: {
      Authorization: `Bearer ${process.env.PAYZU_TOKEN}`,
      'Content-Type': 'application/json',
    },
  },
);
const charge = await res.json();

polling 应作为后备方案。请将 callback 配置为主要来源。

凭证

付款完成后，通过 GET /proof/{id} 下载官方凭证：

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

下一步

Webhooks 错误代码

接收 Pix 付款

生成收款单

向客户展示 QR Code

在付款时接收 callback

通过 polling 后备查询

凭证

下一步

本页内容