Webhooks e callbacks
Receba num endereço HTTPS seu cada mudança de estado das operações da conta, sem precisar consultar a API.
Como integrar
Escolha a URL e os eventos e guarde o segredo do webhook.
2. Segredo dos callbacksCrie o segredo que assina a callbackUrl das operações.
Valide o HMAC de cada aviso antes de processar.
4. Modelo de callbackVeja o envelope que todo evento usa.
5. Reenviar entregasConsulte o que foi enviado e reenvie o que o endpoint perdeu.
Eventos
| Assunto | Eventos |
|---|---|
| Cobrança | PAYMENT_CREATED, PAYMENT_PAID, PAYMENT_EXPIRED, PAYMENT_REFUNDED |
| Saque e pagamento de copia e cola | WITHDRAW_CREATED, WITHDRAW_COMPLETED, WITHDRAW_FAILED, WITHDRAW_REFUND_RECEIVED |
| Devolução | REFUND_COMPLETED, REFUND_FAILED |
| Depósito | DEPOSIT_RECEIVED |
| Transferência entre contas | INTERNAL_TRANSFER_SENT, INTERNAL_TRANSFER_RECEIVED |
| MED | INFRACTION_OPENED, INFRACTION_DEADLINE, INFRACTION_CLOSED |
| Bloqueio da conta | ACCOUNT_BLOCKED, ACCOUNT_UNBLOCKED |
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.
| Identificador | Onde usar |
|---|---|
paymentId | Consultar uma cobrança. É o mesmo id que a criação retornou. |
withdrawId | Consultar o status de um saque. É o mesmo id que a criação retornou. |
transferId | Consultar uma transferência entre contas. É o mesmo id que a criação retornou. |
depositId de DEPOSIT_RECEIVED | Consultar um depósito. |
protocol | Consultar 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
| Destino | O que recebe |
|---|---|
| Webhook cadastrado | Os eventos que você escolheu, de toda a conta. |
callbackUrl da operação | Todos 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_RECEIVEDe os avisos de devolução e de MED de um depósito;WITHDRAW_REFUND_RECEIVED;ACCOUNT_BLOCKEDeACCOUNT_UNBLOCKED;INTERNAL_TRANSFER_RECEIVED, que pertence à conta de destino e não vai para acallbackUrlde quem enviou.
Retentativas
| Regra | Como funciona |
|---|---|
| Confirmação | Só com 2xx em até 10 segundos. Um 3xx conta como falha, porque redirecionamentos não são seguidos. |
| Nova tentativa | A mesma entrega chega de novo, com o mesmo sentAt. |
| Espera | Cresce de 4 segundos até 6 horas. As 10 tentativas se estendem por cerca de 18 horas. |
| Fim | Depois da décima sem 2xx, a entrega para e fica ABANDONED. |
| Ordem | Os 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.