PayZu Pix

Webhooks e callbacks


Nesta páginaComo integrarDois canaisEventosO que chega no seu endpointResposta esperada e retentativasConfira o que foi entregue

Receba no seu sistema um aviso a cada mudança de uma transação, como cobrança paga, saque concluído, devolução terminada ou infração MED aberta.

Fluxo da entrega: a transação muda, a PayZu envia o aviso ao seu endpoint e a resposta 2xx em até 5 segundos conclui a entrega; sem 2xx, o aviso volta para a fila e é tentado de novo, até 12 vezes no total

Como integrar

Dois canais

callbackUrl da transaçãoWebhook da conta
Onde se configuraCampo callbackUrl em POST /pix, POST /withdraw, POST /withdraw/qrcode e POST /internal-transferPOST /user/webhooks, até 5 ativos por conta
AlcanceSó a transação criada com eleTodas as transações da conta
Quando chegaEm toda atualização depois da criação, mesmo sem troca de status, e nos avisos de infraçãoEm cada troca de status, inclusive a criação (TRANSACTION_PENDING), em cada devolução concluída e em INFRACTION_CHANGED
Não recebeA criação da cobrança ou do saque e a troca de status feita pela PayZu. A devolução feita pelo MED pode não chegarAtualização sem troca de status, menos a devolução parcial concluída
Filtro por eventoNão temLista events; vazia recebe todos
Cabeçalho X-Callback-EventNão vemVem em toda entrega

Uma conta pode usar os dois canais ao mesmo tempo.

Eventos

EventoQuando dispara
TRANSACTION_PENDINGA cobrança ou o saque foi criado e aguarda liquidação.
TRANSACTION_COMPLETEDO Pix foi liquidado.
TRANSACTION_CANCELEDA transação foi encerrada sem liquidar.
TRANSACTION_EXPIREDA instituição confirmou que a cobrança venceu sem pagamento.
TRANSACTION_WAITING_FOR_REFUNDA instituição informou a devolução em processamento.
TRANSACTION_REFUNDEDUma devolução, total ou parcial, foi concluída.
TRANSACTION_ERRORA transação terminou em erro.
INFRACTION_CHANGEDUma infração MED foi aberta ou atualizada.

Cada evento leva o nome do novo status da transação, com duas exceções:

  • Devolução parcial: chega como TRANSACTION_REFUNDED, com status: COMPLETED enquanto a soma devolvida não alcança o valor da transação. Quando alcança, o status é REFUNDED.
  • INFRACTION_CHANGED: a transação chega com o status que já tinha, junto do objeto infraction. O reenvio pode vir sem ele.

O cadastro aceita também TRANSACTION_SUSPECTED_FRAUD e TRANSACTION_SUSPECTED_FRAUD_REVERSAL, que hoje não são disparados.

O que chega no seu endpoint

CabeçalhoO que traz
X-Callback-EventO evento, só nas entregas de webhook. O aviso do callbackUrl se identifica pelo corpo.
X-Callback-AttemptO número da tentativa, a partir de 1.
X-Callback-SignatureA assinatura, nos canais com segredo. Veja Assinatura dos callbacks.
User-AgentCallback-Service/1.0.

O corpo comum a todo aviso está em Modelo de callback. Os headers e o corpo de cada evento estão na página dele, linkada na tabela de eventos.

Resposta esperada e retentativas

RegraComo funciona
Resposta esperadaQualquer status 2xx em até 5 segundos. O corpo da sua resposta não muda nada; ele só fica no histórico.
FalhaOutro status, timeout ou conexão recusada fazem a entrega voltar para a fila.
TentativasAté 12 no total, a primeira e 11 retentativas.
EsperaA espera nominal começa em 5 min e dobra a cada vez (5, 10, 20… min); cada espera é sorteada entre metade e o valor cheio. A última tentativa sai entre cerca de 3,5 e 7 dias depois da primeira.
Nova tentativaLê a transação de novo e sai com o estado atual e uma assinatura nova.
RedirecionamentoResponda 2xx direto, sem redirecionar.
Resposta com mais de 1 MBConta como falha.
Destino interno ou reservadoÉ recusado sem retentativa.
RegistroCada tentativa enviada fica registrada com o status HTTP retornado (-1 quando não houve resposta), o corpo e os cabeçalhos da resposta e o tempo de resposta.

Um evento de webhook cujo status já mudou quando a entrega sai é descartado.

Não há tentativa, retentativa nem registro no histórico. O evento do status novo segue por conta própria, se o webhook o assinar. A exceção é o TRANSACTION_REFUNDED da devolução parcial, com a transação ainda COMPLETED: ele sai normalmente. Webhook pausado ou excluído também descarta o que estava na fila.

O mesmo aviso pode chegar mais de uma vez.

Isso acontece por retentativa, reenvio ou pelos dois canais. Trate o aviso pelo estado que o corpo traz, porque uma nova tentativa relê a transação. Deduplique os avisos de transação por id + updatedAt. Em INFRACTION_CHANGED, use só infraction.id + infraction.updatedAt, porque o updatedAt da transação não muda com a infração. Para ordenar, compare updatedAt nos avisos de transação e infraction.updatedAt nos de infração. O reenvio de INFRACTION_CHANGED pode vir sem infraction: consulte a infração em GET /user/infractions, com o id da transação no filtro transactionId.

Confira o que foi entregue

ParaUse
Ver as tentativas dos dois canaisHistórico de callbacks
Ver uma entrega de webhookConsultar uma entrega
Recuperar falhas antigasReenviar callbacks