Adicionar um endpoint
Painel → Webhooks → adicione sua URL HTTPS e escolha os eventos (comece compayment.confirmed). Você receberá um segredo de assinatura
(whsec_…).
Payload
Verificar a assinatura
Sempre verifique antes de confiar em qualquer dado:Eventos
Os payloads de
wallet.* e bridge.* incluem walletId/bridgeTransferId,
chain/route, amount, e os hashes de transação relevantes — no
mesmo formato de suas respostas de API em Wallets e
Bridge.
Disputas
Uma disputa é aberta quando um cliente, a partir da sua página de checkout, relata ter enviado fundos que não confirmaram automaticamente — valor errado, endereço errado, ou envio atrasado. É self-service do lado do cliente (eles recebem instantaneamente um resultadomatchedWallet / amountCovered / lateByMinutes), e
payment.dispute_opened te dá o mesmo nível de detalhe para que você
possa fazer o acompanhamento manual caso a verificação automática não
resolva — por exemplo, aprovar um pedido mesmo com um pagamento
ligeiramente incompleto, a seu critério.
Entrega e novas tentativas
- Responda
2xxem até 10 segundos; qualquer outra coisa conta como falha. - Tentamos novamente até 3 vezes com backoff; entregas e códigos de status ficam visíveis no painel.
- Os handlers devem ser idempotentes — use
paymentIntentIdcomo chave.