Notificações de transações
Receba em tempo real informações sobre as transações dos seus clientes.
Introdução
Este webhook permite receber notificações instantâneas de cada transação dos seus clientes. Com essas informações, você pode agir em tempo real e melhorar a experiência do cliente.
Por exemplo:
Uma transação foi recusada por CVV incorreto? Você pode enviar uma mensagem automática ao cliente, direcionando-o diretamente aos dados do seu cartão virtual.
Uma transação foi aprovada? Você pode notificar o cliente, confirmando o status da compra e transmitindo tranquilidade.
Eventos que notificamos
✅ Transações aprovadas (approved-authorization-advice)
| EVENTO | STATUS DETAIL |
|---|---|
| Aprovada | APPROVED |
🛡️ Transações recusadas pela Pomelo (authorization-advice)
| EVENTO | STATUS DETAIL |
|---|---|
| Stand-In Bandeira (120) | OTHER |
| Usuário restrito | RESTRICTED_USER |
| Formato de mensagem inválido | MISSING_FIELDS |
| PIN inválido | INVALID_PIN |
| CVV inválido | INVALID_CVV |
| Data de validade inválida | INVALID_EXPIRATION_DATE |
| Valor inválido | INVALID_AMOUNT |
| Transação inválida | INVALID_TRANSACTION |
| Transação não permitida | TRANSACTION_NOT_PERMITTED |
| Suspeita de fraude | REJECTED_FRAUD |
| Tentativas máximas de PIN excedidas | PIN_TRY_LIMIT_EXCEED |
| Timeout | CLIENT_TIMEOUT |
| Cliente indisponível | CLIENT_UNAVAILABLE |
| Erro interno da Pomelo | INTERNAL_ERROR |
| Cartão inexistente | CARD_NOT_FOUND |
| Cartão não configurado | CARD_NOT_CONFIGURED |
| Cartão desativado | CARD_DISABLED |
| Cartão inativo | CARD_NOT_ACTIVE |
🛡️ Transações recusadas por você (authorization-advice)
| EVENTO | STATUS DETAIL |
|---|---|
| Saldo insuficiente do cliente | INSUFFICIENT_FUNDS |
| Estabelecimento bloqueado | INVALID_MERCHANT |
| Valor inválido de transação por regra | INVALID_AMOUNT |
| Erro no seu sistema | SYSTEM_ERROR |
| Outro motivo não categorizado acima | OTHER |
Implementação
Para implementar este webhook, siga os passos desta documentação. Também convidamos você a consultar toda a documentação técnica específica na nossa API reference.
Importante:
Você poderá identificar as transações aprovadas das recusadas pelo tipo de evento: as aprovadas terão no campo event_type: approved-authorization-advice, enquanto as recusadas terão authorization-advice.
Merchant Advice Code
Esta funcionalidade foi pensada para que adquirentes e estabelecimentos tenham informações para evitar múltiplas tentativas de processar uma transação, ajudando a reduzir custos de transações com falha. Além disso, ao obter esses dados em tempo real, poderão entrar em contato com os usuários para oferecer uma solução que permita concluir a operação com sucesso 😉
Casos de uso
| Saldo insuficiente | Orientamos os adquirentes a tentar novamente mais tarde. Se informarmos ao cliente que a operação falhou por falta de saldo, ele poderá adicionar fundos e a próxima tentativa poderá ser bem-sucedida. |
| Cartão expirado | Informamos aos adquirentes para não tentar processar a transação novamente e obter os novos dados do cartão. |
| Cartão pausado ou desativado | Informamos aos adquirentes para não tentar processar a transação novamente, pois o cartão não está habilitado. |
Perguntas frequentes:
Que tipo de notificações enviamos?
A partir de 15/09/25, enviaremos notificações de todas as transações, e não apenas das recusadas.
Esses webhooks são reenviados em caso de falha?
Sim. Caso sua resposta seja diferente de HTTP Status 200, a notificação é reencaminhada e nova tentativa é feita a cada 10 minutos durante os 4 dias seguintes.