PayZu Conta Hub

Webhooks e callbacks


Nesta páginaComo integrarEventosIdentificadoresOnde receberRetentativasResposta esperada

Receba num endereço HTTPS seu cada mudança de estado das operações da conta, sem precisar consultar a API.

Fluxo de uma entrega: o evento da conta vira um POST assinado para o seu endpoint, que tem até 10 segundos para responder; com 2xx a entrega fica DELIVERED; sem 2xx há novas tentativas, até 10, e depois a entrega fica ABANDONED

Como integrar

Eventos

Cada entrega é um POST com um único evento, num envelope JSON descrito no Modelo de callback. Os headers e o corpo de cada evento estão na página dele.

Identificadores

Para chegar à operação, use o identificador que vem em data.

IdentificadorOnde usar
paymentIdConsultar uma cobrança. É o mesmo id que a criação retornou.
withdrawIdConsultar o status de um saque. É o mesmo id que a criação retornou.
transferIdConsultar uma transferência entre contas. É o mesmo id que a criação retornou.
depositId de DEPOSIT_RECEIVEDConsultar um depósito.
protocolConsultar uma infração MED. No extrato, aparece em infractionProtocol.
refundIdÉ o id da tentativa dentro de refunds, na cobrança ou no depósito devolvido.

Onde receber

DestinoO que recebe
Webhook cadastradoOs eventos que você escolheu, de toda a conta.
callbackUrl da operaçãoTodos os avisos dela, sem filtro por evento, além dos webhooks cadastrados.

A callbackUrl só é aceita depois de criado o segredo dos callbacks. A de uma cobrança também recebe os avisos de devolução e de MED dessa cobrança.

Vão só aos webhooks cadastrados:

  • DEPOSIT_RECEIVED e os avisos de devolução e de MED de um depósito;
  • WITHDRAW_REFUND_RECEIVED;
  • ACCOUNT_BLOCKED e ACCOUNT_UNBLOCKED;
  • INTERNAL_TRANSFER_RECEIVED, que pertence à conta de destino e não vai para a callbackUrl de quem enviou.

Retentativas

RegraComo funciona
ConfirmaçãoSó com 2xx em até 10 segundos. Um 3xx conta como falha, porque redirecionamentos não são seguidos.
Nova tentativaA mesma entrega chega de novo, com o mesmo sentAt.
EsperaCresce de 4 segundos até 6 horas. As 10 tentativas se estendem por cerca de 18 horas.
FimDepois da décima sem 2xx, a entrega para e fica ABANDONED.
OrdemOs avisos de uma conta saem um de cada vez, na ordem em que aconteceram.

Enquanto uma entrega espera nova tentativa, os avisos seguintes da conta também esperam.

Isso inclui os avisos de outros webhooks. Quando a entrega fica ABANDONED, a fila da conta segue.

Resposta esperada

Qualquer status 2xx serve. Responda assim também quando o id já foi processado, ou o aviso volta.

Deduplique pelo id do envelope.

Nunca pela assinatura ou pelo X-Payzu-Timestamp.