Receber pagamento Pix

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

import os, requests

res = requests.post(
    'https://api.payzu.processamento.com/v1/pix',
    headers={
        'Authorization': f'Bearer {os.environ["PAYZU_TOKEN"]}',
        'Content-Type': 'application/json',
    },
    json={
        '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,
    },
)
charge = res.json()

body := strings.NewReader(`{
  "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
}`)

req, _ := http.NewRequest("POST", "https://api.payzu.processamento.com/v1/pix", body)
req.Header.Set("Authorization", "Bearer " + os.Getenv("PAYZU_TOKEN"))
req.Header.Set("Content-Type", "application/json")
res, err := http.DefaultClient.Do(req)

<?php
$ch = curl_init('https://api.payzu.processamento.com/v1/pix');
curl_setopt_array($ch, [
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_POST => true,
  CURLOPT_HTTPHEADER => [
    'Authorization: Bearer ' . getenv('PAYZU_TOKEN'),
    'Content-Type: application/json',
  ],
  CURLOPT_POSTFIELDS => json_encode([
    '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,
  ]),
]);
$charge = json_decode(curl_exec($ch), true);

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 só gera QR dinâmico. QR estático não é suportado.

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

http.HandleFunc("/webhooks/payzu", func(w http.ResponseWriter, r *http.Request) {
    var tx Transaction
    if err := json.NewDecoder(r.Body).Decode(&tx); err != nil {
        w.WriteHeader(http.StatusBadRequest)
        return
    }
    if isProcessed(tx.ID, tx.Status) {
        w.WriteHeader(http.StatusOK)
        return
    }
    if tx.Type == "DEPOSIT" && tx.Status == "COMPLETED" {
        markOrderPaid(tx.ClientReference, tx)
    }
    w.WriteHeader(http.StatusNoContent)
})

<?php
$tx = json_decode(file_get_contents('php://input'), true);

if (isProcessed($tx['id'], $tx['status'])) {
    http_response_code(200);
    exit;
}

if ($tx['type'] === 'DEPOSIT' && $tx['status'] === 'COMPLETED') {
    markOrderPaid($tx['clientReference'], $tx);
}

http_response_code(204);

Responda em até 5 segundos com 2xx. Caso contrário, a PayZu inicia retry (até 72 tentativas com backoff exponencial). Detalhes 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();

res = requests.get(
    'https://api.payzu.processamento.com/v1/pix',
    params={'clientReference': 'pedido-2025-001'},
    headers={
        'Authorization': f'Bearer {os.environ["PAYZU_TOKEN"]}',
        'Content-Type': 'application/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"