PayZu Gateway

Webhooks


Nesta páginaComo integrarEventosO que chega no seu endpointAssinaturaResposta esperada e retentativas

Receba no seu sistema um aviso quando uma fatura, uma assinatura ou uma contestação muda, nos eventos da tabela abaixo, sem precisar consultar a API. A mudança sem evento, como o QR Code vencido, se confere consultando o recurso.

Fluxo de um webhook: o recurso muda, a PayZu cria o evento com uma entrega por webhook e faz um POST assinado no seu endpoint; com 2xx em até 5 segundos a entrega fica delivered, sem 2xx há nova tentativa até a sexta, quando fica failed

Como integrar

Depois do cadastro, o webhook aceita estas operações:

OperaçãoPágina
Listar e consultarConsultar webhooks
Trocar o endereço ou os eventos, pausar e reativarAlterar um webhook
Gerar um segredo novoTrocar o segredo do webhook
ApagarExcluir um webhook

Eventos

EventoQuando dispara
invoice.createdFatura criada: avulsa, de adesão, de ciclo da assinatura ou pela compra no link de pagamento. Chega pending, com payments vazio.
invoice.paidFatura paga. Também quando um pagamento confirmado depois leva a fatura canceled ou expired a paid.
invoice.payment_failedUma tentativa passou a failed, com a fatura ainda pending: cartão ou Pix recusado, inclusive no ciclo da assinatura, ou cartão sem resposta da adquirente que terminou sem desfecho. O QR Code vencido não dispara.
invoice.payment_refundedUm pagamento confirmado numa fatura já paid, refunded ou chargedback foi devolvido. O status da fatura não muda.
invoice.expiredA fatura passou de billing.expires_at sem pagamento. Na fatura de ciclo e na de adesão, sai antes de subscription.canceled.
invoice.canceledVocê cancelou a fatura, sozinha ou junto com a assinatura, inclusive num estorno pedido por você que cancela a assinatura. Sai um evento por fatura. A fatura fechada pela contestação, pelo estorno que chega pela adquirente ou pelo fim da carência não dispara.
invoice.refund_requestedEstorno do Pix pedido e ainda não confirmado: o estorno em refunds está requested e a fatura segue paid. A devolução automática do pagamento em duplicidade não dispara.
invoice.refund_failedEstorno recusado: o estorno em refunds passou a failed. Na devolução automática do pagamento em duplicidade, sai no máximo uma vez. O status da fatura não muda.
invoice.refundedA fatura passou a refunded, com o estorno confirmado da tentativa que a quitou.
invoice.chargedbackA fatura passou a chargedback, e a contestação recebida no cartão que a quitou vem no campo chargeback.
subscription.createdAssinatura criada, no cartão ou no Pix. Chega incomplete.
subscription.activatedA fatura de adesão foi paga, e a assinatura passou de incomplete a active.
subscription.renewedUma fatura de ciclo foi paga com a assinatura active, por qualquer caminho. grace volta a null e, no cartão, billing.next_at vai ao ciclo seguinte.
subscription.grace_startedA carência começou, pela renovação recusada no cartão ou pela fatura de ciclo do Pix vencida. A assinatura segue active, com grace preenchido.
subscription.updatedAssinatura alterada: valor, cartão ou metadata.
subscription.canceledAssinatura cancelada, com o motivo em cancellation.reason: por você, pelo fim da carência, depois de invoice.expired, pela adesão vencida, pelo estorno da fatura que cancela a assinatura ou pela contestação.
subscription.reactivatedA assinatura cancelada voltou a active, pela reativação ou pelo pagamento de uma fatura depois do cancelamento.
chargeback.receivedContestação recebida.
chargeback.respondedResposta à contestação registrada, por aceite ou por defesa. O prazo vencido sem resposta não dispara.

Cada evento gera uma entrega para cada webhook ativo que tem o evento na lista events do cadastro. Em data, o evento traz o recurso que mudou, no mesmo formato da consulta dele na API.

O evento de teste ping sai só pelo painel, numa entrega só, sem nova tentativa. O envelope e o corpo de cada evento estão em Modelo de evento.

O que chega no seu endpoint

A PayZu faz um POST com o evento em JSON no endereço do webhook, com estes cabeçalhos:

CabeçalhoConteúdo
X-Webhook-EventTipo do evento, igual ao type do corpo.
X-Webhook-SignatureAssinatura da entrega.
X-Webhook-TimestampValor em milissegundos, que muda a cada tentativa.
X-Webhook-NonceValor que muda a cada tentativa.

Assinatura

Toda entrega chega assinada com o segredo do webhook. O cálculo e o código para conferir estão em Assinatura dos webhooks.

Resposta esperada e retentativas

Sua aplicação confere a assinatura, grava o aviso e responde.

  • Resposta: qualquer status 2xx em até 5 segundos. O corpo da sua resposta não é lido.
  • Falha: outro status, timeout ou conexão recusada. Redirecionamento não é seguido, então um 3xx também conta como falha.
  • Nova tentativa: leva o mesmo corpo e uma assinatura nova.
  • Endereço: a cada tentativa, a PayZu confere o endereço de novo e não conecta num domínio que resolve para endereço interno. Essa tentativa conta como falha.
  • Atraso: as entregas saem em rodadas, pouco depois da mudança. Quando precisar do estado na hora, consulte a API.
TentativaSai depois da anterior
2ª1 minuto
3ª10 minutos
4ª1 hora
5ª6 horas
6ª24 horas

Depois da sexta tentativa sem 2xx, a entrega fica failed. Uma entrega pode ser reenviada em qualquer status.

O mesmo evento pode chegar mais de uma vez e fora de ordem.

Descarte a repetição pelo id do evento no registro de cada sistema que trata os avisos: ele é o mesmo em todas as tentativas, no reenvio e em todos os webhooks que recebem o evento. Compare também o created_at do evento para saber qual é o mais recente. Com o mesmo created_at, consulte o recurso pela API.