PayZu PixWebhooks e callbacks
Modelo de callback
Todo aviso leva os campos de GET /pix, mais callbackUrl e withdrawQrCodeText; em avisos de infração, também o objeto infraction. O corpo é igual nos dois canais.
| Canal | Como identificar o aviso |
|---|---|
| Webhook | Pelo evento, no cabeçalho X-Callback-Event. |
callbackUrl | A presença de infraction marca o aviso de infração. Os demais se distinguem por status, refundStatus e refundAmount. |
Entrega
Entrega de um webhook
POST /payzu/webhook HTTP/1.1
Host: sualoja.com.br
Content-Type: application/json
User-Agent: Callback-Service/1.0
X-Callback-Attempt: 1
X-Callback-Event: TRANSACTION_COMPLETED
X-Callback-Signature: t=1760140800, v1=5f1c2e9a0b7d4c6e8f1a2b3c4d5e6f708192a3b4c5d6e7f8091a2b3c4d5e6f70
{"id":"PAYZU20260811R4TZ8WD1NC000000","type":"DEPOSIT","status":"COMPLETED", … ,"amount":10,"serviceFeeCharged":0.075}Corpo do aviso
O corpo é a transação como está no momento do envio, com os campos na ordem em que a PayZu os envia. Cada tentativa lê a transação de novo. O corpo completo de cada evento, com exemplo, está na página dele, a partir da tabela de eventos.
Estes campos pedem atenção no aviso:
| Campo | Tipo | Descrição |
|---|---|---|
callbackUrl | string ou null | URL informada na criação da transação. Não vem em GET /pix. |
withdrawQrCodeText | string ou null | Copia e cola pago em POST /withdraw/qrcode. |
refundAmount | string ou null | Soma devolvida, em reais, como texto decimal ("30.5"). Em GET /pix vem como número. |
qrCodeUrl, qrCodeBase64 | null | Vêm sempre null no aviso. A imagem do QR Code sai na criação da cobrança e em GET /pix. |
serviceFeeCharged | number | Tarifa em reais, com mais de duas casas quando houver. Pode faltar, conforme a configuração da conta. |
receiverAccountNumber | string ou null | Falta no saque para chave liquidado como transferência entre contas PayZu (method: INTERNAL_TRANSFER). |
infraction | objeto | Só nos avisos de infração (INFRACTION_CHANGED). O reenvio pode vir sem ele e, no callbackUrl, fica igual a um aviso da transação: depois de pedir um reenvio, consulte as infrações da transação em GET /user/infractions. |
Converta refundAmount em número antes de comparar.
No aviso ele chega como texto decimal, e em GET /pix, como número. Cada aviso traz o total devolvido até ali, e não a parcela.