Confirmar o pagamento
Saiba do pagamento pelo postback enviado à postbackUrl da cobrança ou, sem ela, pela consulta.
Receba o postback
A PayZu envia um POST assinado para a postbackUrl a cada mudança no Pix. O corpo traz event igual a charge.update e, em data, a cobrança completa, com os mesmos campos da consulta.
| Mudança | pixPayment.status |
|---|---|
| Pagamento confirmado | paid |
| QR Code vencido ou venda cancelada | canceled |
| Devolução concluída | refunded |
| Devolução não concluída | paid |
| Falha de um Pix pendente | failed |
O corpo de um Pix pago está em Cobrança atualizada. A assinatura, o prazo de resposta e as novas tentativas são os mesmos do cartão; veja Validação da assinatura.
Libere o pedido só com pixPayment.status igual a paid e pixPayment.refunds vazio.
Se o pagamento chegar no momento em que o QR Code vencido é cancelado, a cobrança vai a paid com uma devolução já pedida, e o valor volta ao pagador.
O mesmo aviso pode chegar mais de uma vez. Identifique a cobrança por data.id, aja pelo status que vem em data e libere o pedido uma só vez.
Consulte a cobrança
Sem postbackUrl, acompanhe o Pix pela consulta.
curl --request GET \
--url 'https://api.sandbox.payzu.dev/v1/charges/0b9c4e2a-6f1d-4c8e-9a37-2d5e8f1a4b6c' \
--header "Authorization: Bearer $PAYZU_TOKEN" \
--cert "$PAYZU_CLIENT_CERT" --key "$PAYZU_CLIENT_KEY"{
"id": "0b9c4e2a-6f1d-4c8e-9a37-2d5e8f1a4b6c",
"externalId": "pedido-1235",
"postbackUrl": "https://seusite.com.br/webhooks/payzu",
"amount": 10000,
"paymentType": "pix",
"customer": {
"name": "Maria Souza",
"identity": "11144477735",
"identityType": "CPF",
"email": null,
"birthdate": null,
"phone": null,
"address": null
},
"cart": [],
"creditCardPayment": null,
"pixPayment": {
"status": "paid",
"qrCode": "00020101021226800014br.gov.bcb.pix2558pix.example.com/qr/v2/9d36b84f-c70b-478f-b95c-12729b90ca255204000053039865802BR5912LOJA EXEMPLO6009SAO PAULO62070503***6304D233",
"expiresAt": "2026-06-12T17:02:10.000Z",
"paidAt": "2026-06-12T16:05:38.000Z",
"canceledAt": null,
"endToEndId": "E00000000202606121605a1B2c3D4e5F",
"refunds": []
},
"recurrence": null,
"recurrenceCycle": null,
"createdAt": "2026-06-12T16:02:10.000Z",
"updatedAt": "2026-06-12T16:05:41.000Z"
}Referência: Consultar uma cobrança
A consulta de um Pix pendente busca a situação atualizada no máximo uma vez a cada 30 segundos por cobrança.
Consultas mais frequentes recebem o último estado conhecido, então o postback é o jeito mais rápido de saber do pagamento.
As cobranças Pix também aparecem em Listar cobranças, com cada item no mesmo formato da consulta.
Erros desta operação
| Código | HTTP | Mensagem |
|---|---|---|
PZ100 | 404 | Cobrança não encontrada |
Os erros de autenticação e de validação e os demais códigos estão no Catálogo de erros.