Documentação do Webhook de Devolução
Visão Geral
Nosso sistema de webhook envia notificações em tempo real sobre o processamento de estornos (refunds). Quando um estorno é confirmado ou rejeitado, uma requisição POST é enviada para a callback_url da transação original com informações detalhadas do status do estorno.
O estorno é processado de forma assíncrona. Após a requisição inicial retornar com status IN_PROCESSING, a confirmação ou rejeição será enviada via webhook para a URL configurada na transação original.
Payload do Webhook
O webhook envia um payload JSON contendo os detalhes e status do estorno.
Descrição dos Campos
transactionId (string): Identificador único da transação no formato UUIDtransactionStatus (string): Status atual da transação. Valores possíveis:
REFUND: Estorno confirmado com sucessoREFUND_REJECTED: Estorno rejeitado
transactionType (string): Tipo da transação original (CASH_IN ou CASH_OUT)value (string): Valor da transação estornadaexternalId (string): ID de referência externa fornecido pelo cliente na transação originale2e_id (string, opcional): Identificador end-to-end da transação PIX (presente no refund confirmado)error_message (string, opcional): Mensagem de erro quando o estorno é rejeitado (ex: “AC06 - Conta bloqueada do Pix”)
Exemplos por Status
Refund Confirmado
Quando o estorno é processado com sucesso, o status da transação é alterado para REFUND e o webhook é enviado.
Refund Rejeitado
Quando o estorno é rejeitado, o status da transação original é mantido (não altera) e o webhook é enviado com transactionStatus: "REFUND_REJECTED" e o motivo da rejeição no campo error_message.
Códigos de Erro Comuns
Quando um estorno é rejeitado, o campo error_message contém o código de erro e a descrição. Os códigos mais comuns são:
- AC06: Conta bloqueada do Pix
- ED05: Pagamento rejeitado pelo PSP do recebedor
Regras de Negócio
Boas Práticas
O Webhook deve retornar Status Code 200
Para que o estorno tenha seu fluxo finalizado com sucesso é de extrema importância que seja retornado 200 na resposta!
