Transaction Notifications
Receive real-time information about your customers’ transactions.
Introduction
This webhook allows you to receive instant notifications for each of your customers’ transactions. With this information, you can act in real time and enhance the customer experience.
For example:
Was a transaction declined due to an incorrect CVV? You can send an automatic message to the customer, directing them straight to their virtual card details.
Was a transaction approved? You can notify the customer, confirming the purchase status and providing peace of mind.
Events We Notify You About
✅ Approved transactions (approved-authorization-advice)
| EVENT | STATUS DETAIL |
|---|---|
| Approved | APPROVED |
🛡️ Transactions rejected by Pomelo (authorization-advice)
| EVENT | STATUS DETAIL |
|---|---|
| Stand-In Flag (120) | OTHER |
| Restricted user | RESTRICTED_USER |
| Invalid message format | MISSING_FIELDS |
| Invalid PIN | INVALID_PIN |
| Invalid CVV | INVALID_CVV |
| Invalid expiration date | INVALID_EXPIRATION_DATE |
| Invalid amount | INVALID_AMOUNT |
| Invalid transaction | INVALID_TRANSACTION |
| Transaction not permitted | TRANSACTION_NOT_PERMITTED |
| Suspected fraud | REJECTED_FRAUD |
| Maximum PIN attempts exceeded | PIN_TRY_LIMIT_EXCEED |
| Timeout | CLIENT_TIMEOUT |
| Client unavailable | CLIENT_UNAVAILABLE |
| Pomelo internal error | INTERNAL_ERROR |
| Card not found | CARD_NOT_FOUND |
| Card not configured | CARD_NOT_CONFIGURED |
| Card disabled | CARD_DISABLED |
| Card inactive | CARD_NOT_ACTIVE |
🛡️ Transactions rejected by you (authorization-advice)
| EVENT | STATUS DETAIL |
|---|---|
| Insufficient customer funds | INSUFFICIENT_FUNDS |
| Blocked merchant | INVALID_MERCHANT |
| Invalid transaction amount by rule | INVALID_AMOUNT |
| System error | SYSTEM_ERROR |
| Other uncategorized reason | OTHER |
Implementation
To implement this webhook, follow the steps in this documentation. We also invite you to review all the specific technical documentation in our API reference.
Important:
You can identify approved vs. rejected transactions by their event type: approved transactions will have event_type: approved-authorization-advice, while rejected transactions will have authorization-advice.
Merchant Advice Code
This feature is designed so that acquirers and merchants have the necessary information to avoid multiple retry attempts when processing a transaction, helping reduce the costs of failed transactions. Additionally, by obtaining this data in real time, they can contact users to offer solutions so that the transaction can be completed successfully 😉
Use Cases
| Insufficient funds | We ask acquirers to try again later. If we inform the customer that the operation failed due to insufficient funds, they may add funds and the next attempt could be successful. |
| Expired card | We inform acquirers not to attempt processing the transaction again and to obtain the updated card details. |
| Paused or disabled card | We inform acquirers not to attempt processing the transaction again, as the card is not enabled. |
FAQs:
What type of notifications do we send?
Starting 09/15/25, we will send notifications for all transactions, not only the rejected ones.
Are retries performed for these webhooks?
Yes. If your response is different from HTTP Status 200, the notification is re-queued and retried every 10 minutes for the next 4 days.