Webhooks for payments

Viva Wallet supports webhooks, a simple and powerful solution that allows you to receive notifications each time a specific event takes place.


To receive webhook notifications, you need to create a public URL resource that can receive (via POST) objects of type Message<TransactionEventData>.

Message has the following properties:

TransactionEventData has the following properties:


The following events are available for which a notification can be sent:

Webhook URL verification

The API call below uses basic auth.

To receive your unique webhook authorization code, all you need to do is call the following API action with standard API authentication headers. Set the response to application/json. The demo environment has a base URL of https://demo.vivapayments.com/ and for the live environment it’s https://www.vivapayments.com/.

get    /api/messages/config/token

This call will give you a key (example below) which you can print to the page as is. You can always disable a webhook (without deleting it), to temporarily stop receiving notifications.

Response example


In order to use a new webhook URL, Viva Wallet needs to verify that the given URL is available for immediate use.

Each time you enter a new webhook URL via the banking app, you need to verify it (by clicking on the “verify” link next to URL input textbox). This action will start the process of a simple GET http call to your URL. We send this request using TLS 1.2 so your server configuration needs to match that. Your page should print a JSON response such as the one shown above.

Retry policy

Viva Wallet will assume you have successfully received a webhook notification if you respond with http status 200 to the POST calls received from us. In any other case (e.g. http status 404,401,500) a retry mechanism will start and run once per hour until a status 200 is received or the maximum retries threshold is reached (72 retries / 3 days).

Viva Wallet IP addresses for whitelisting

In case you need to set up IP restrictions, webhooks are sent from the following Viva Wallet IP addresses:



Further information

Check out the related tutorial below for more details on this topic: