Receber pagamento Pix

Desde gerar a cobrança e mostrar o QR até saber na hora que o cliente pagou e dar baixa no pedido, com o passo a passo em curl e Node.js.

POST /pix GET /pix Webhooks Glossário

Gerar cobrança

Endpoint: POST /pix. Só amount é obrigatório; os demais campos enriquecem o QR e a reconciliação.

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();

Resposta:

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

Exibir QR Code ao cliente

Duas formas:

Imagem direta, use qrCodeUrl em <img>:

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

Copia-e-cola, exiba qrCodeText em input com botão:

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

PayZu gera QR dinâmico por cobrança.

Receber callback quando pago

Quando o cliente concluir o Pix, a PayZu envia POST para sua callbackUrl:

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

Handler de exemplo:

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

Responda em até 5 segundos com 2xx; a política completa de retry está em Webhooks.

Fallback por polling

Se o callback não chegar, consulte direto via GET /pix. Aceita id, clientReference, endToEndId ou virtualAccount, use apenas um.

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 deve ser fallback. Configure o callback como fonte primária.

Comprovante

Após o pagamento, baixe o comprovante oficial via GET /proof/{id}:

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

Próximos passos

Webhooks Códigos de erro