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.

CanalComo identificar o aviso
WebhookPelo evento, no cabeçalho X-Callback-Event.
callbackUrlA 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:

CampoTipoDescrição
callbackUrlstring ou nullURL informada na criação da transação. Não vem em GET /pix.
withdrawQrCodeTextstring ou nullCopia e cola pago em POST /withdraw/qrcode.
refundAmountstring ou nullSoma devolvida, em reais, como texto decimal ("30.5"). Em GET /pix vem como número.
qrCodeUrl, qrCodeBase64nullVêm sempre null no aviso. A imagem do QR Code sai na criação da cobrança e em GET /pix.
serviceFeeChargednumberTarifa em reais, com mais de duas casas quando houver. Pode faltar, conforme a configuração da conta.
receiverAccountNumberstring ou nullFalta no saque para chave liquidado como transferência entre contas PayZu (method: INTERNAL_TRANSFER).
infractionobjetoSó 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.