Receive Pix payment

From creating the charge and showing the QR code to knowing the moment your customer pays and marking the order as settled, walked through in curl and Node.js.

POST /pix GET /pix Webhooks Glossary

Generate charge

Endpoint: POST /pix. Only amount is required, in reais and never in cents; the other fields enrich the QR and reconciliation.

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

Response:

{
  "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"
}

Display QR Code to customer

Two ways:

Direct image, use qrCodeUrl in <img>:

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

Copy-and-paste, display qrCodeText in an input with a button:

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

PayZu generates a dynamic QR per charge.

Receive callback when paid

When the customer completes the Pix, PayZu sends a POST to your callbackUrl:

{
  "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"
}

Sample handler:

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

Respond within 5 seconds with 2xx; the full retry policy is in Webhooks.

Polling fallback

If the callback does not arrive, query directly via GET /pix. It accepts id, clientReference, endToEndId or virtualAccount, use only one.

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 should be a fallback. Configure the callback as the primary source.

Receipt

After payment, download the official receipt via GET /proof/{id}:

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

Next steps

Webhooks Error codes