Pay an outside recipient by Pix key, with the recipient's details checked against the DICT before the money leaves, or by reading a QR code, then track the status through to downloading the receipt.
Path 1: by Pix key
Look up the key in DICT
Before paying, validate the recipient by querying DICT via GET /pix/key. It confirms the key exists and returns the holder so you can compare with what you expect.
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();More details at DICT Lookup.
Execute the payment
Use POST /withdraw with the validated key. pixType accepts: 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();Path 2: by QR Code
Read the QR first (optional)
If the QR was scanned from an external client, extract the data before paying via 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 processes both dynamic and static QR Code.
Execute the payment
POST /withdraw/qrcode. If the QR already has an embedded amount, amount can be omitted.
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"
}'Track status
The withdrawal starts as PENDING and progresses to COMPLETED, CANCELED, or ERROR. The callback arrives at each transition. To query manually via GET /withdraw:
curl "https://api.payzu.processamento.com/v1/withdraw?clientReference=payout-2025-08-001" \
-H "Authorization: Bearer $TOKEN" \
-H "Content-Type: application/json"Receipt
After COMPLETED, download the official receipt via GET /withdraw/proof/{id}:
curl "https://api.payzu.processamento.com/v1/withdraw/proof/PAYZU2025..." \
-H "Authorization: Bearer $TOKEN" \
-H "Content-Type: application/json"Common errors
| Error | Resolution |
|---|---|
| Insufficient balance | Check GET /user/balance first |
| Invalid Pix key | Validate via DICT first |
| Amount below minimum | amount ≥ R$ 0.01 (key) or ≥ R$ 0.10 (QR) |
| Different recipient | Compare dict.name with what you expect before paying |