Webhooks for payments

Set up webhooks to receive notifications for events within your Viva account.


Viva supports webhooks, a simple and powerful solution that allows you to receive notifications each time a specific event takes place. Webhooks are particularly useful for asynchronous events such as asynchronous payments, for example, when the funds of the customer are transferred from his bank account into your Viva account.

You do not need to set up webhooks for the PrestaShop Smart Checkout plugin, the WooCommerce Standard Checkout plugin or the Shopify Smart Checkout plugin, as they are automatically created by the plugins

Webhook Events

The following events are available for which a notification can be sent. Please see the table below for a list of available webhooks and the unique IDs (EventTypeId) which can be used to identify these events:

Webhook EventTypeId Description
Transaction Payment Created 1796 A customer’s payment has been successful
Transaction Failed 1798 A customer’s payment failed (but the customer may retry and the customer’s payment may - eventually - be successful and thus trigger a Transaction Payment Created webhook)
Transaction Price Calculated 1799 A commission payment has been withdrawn from your account by Viva
Transaction Reversal Created 1797 A customer refund has been successfully actioned
Account Transaction Created 2054 A wallet account balance change
Command Bank Transfer Created 768 A bank transfer to an external IBAN has been created but not executed yet (the money has not yet been transferred from your wallet)
Command Bank Transfer Executed 769 A bank transfer to an external IBAN has been executed. In case of instant bank account transfer, money has been transferred immediately from your wallet - which is linked with your IBAN - to the external IBAN. In case of non-instant bank account transfer, money has been transferred from your wallet - which is linked with your IBAN - but not necessarily received yet to the external IBAN
Account Connected 8193 Marketplace & ISV only: triggered when an account is successfully connected to the platform/ISV account
Account Verification Status Changed 8194 Marketplace & ISV only: triggered when the verification status of a connected account changes
Transfer Created 8448 Marketplace only: triggered when a transfer is made
Sale Transactions The requested sale transactions are available to download
Obligation Created [DEPRECATED] 5632 Marketplace only: an obligation (e.g. refund request) has been successfully sent to a marketplace seller
Obligation Captured [DEPRECATED] 5633 Marketplace only: an obligation (e.g. refund request) has been successfully paid by a marketplace seller

Webhook notifications will not be triggered for cancelled transactions, or for payments that failed 3DS user authentication (see our Event ID codes).

Additionally, no notification will be triggered upon expiration of a payment order, but any subsequent successful payments will still trigger a webhook notification.

If you wish to test a Transaction Failed webhook, please use our Trigger a decline simulating functionality.

When you receive a webhook notification, before updating a transaction’s status on your system, you SHOULD always retrieve its details from Viva. Please use the transactionId in the payload and make a call to the Retrieve Transaction API. Validate the orderCode, statusId and amount you received in the Retrieve Transaction API response and update your system accordingly

Setting up Webhooks

You can start receiving webhook notifications by following the below steps:

Whitelist the Viva addresses

To successfully receive webhook notifications, you should whitelist the below IP addresses/ranges in both your server and in your network firewall. The webhooks’ IP source will be from the below IP addresses/ranges:

Production accounts
Demo accounts

Generate a webhook verification key

Before receiving a webhook notification to your website, you need to create a unique verification code for Viva to identify you as a merchant. To do this, make a simple GET request to the following API endpoint with basic authentication headers.

get    /api/messages/config/token

This call will give you a “Key”:“Value” pair in a JSON response(example below) which you can print it as is. You can disable a webhook (without deleting it) to temporarily stop receiving notifications.

Request example

The example below uses basic auth for authentication.

Run in Postman

Environment URL
Production https://www.vivapayments.com/api/messages/config/token
Demo https://demo.vivapayments.com/api/messages/config/token
curl '[Environment URL]'
-H 'Authorization: Basic [Base64-encoded Merchant ID and API key]'


$curl = curl_init();

curl_setopt_array($curl, array(
  CURLOPT_URL => '[Environment URL]',
    'Authorization: Basic [Base64-encoded Merchant ID and API key]'

$response = curl_exec($curl);

echo $response;

Response example

In order to use a new webhook URL, Viva 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.

Create a webhook endpoint

To receive webhooks, Viva requires that you respond to every notification. This is to ensure that your server is properly accepting notifications.

You should set up an HTTP endpoint on your server and make be sure that you can accept webhook requests with a POST method.

For test purposes, you can generate your webhook URL using Pipedream web application.

You SHOULD NOT set any redirection from your webhook endpoints to other locations. Otherwise, you may encounter 302 and similar errors, and webhook notifications MAY NOT be received successfully

Handle requests from Viva

You should configure your endpoint to read all the provided by Viva objects-parameters for every event type of webhook notifications you want to receive.

Every webhook notification includes the following properties:

The TransactionEventData will have different parameters in the webhook you will define for each event type.

You may confirm the transactions status through the StatusId parameter.

Viva sends all the events to your webhook endpoint as part of a POST request with a JSON payload. In order for Viva to assume you have successfully received a webhook notification, you need to respond with http status 200 to the POST calls received from us

The below Node JS may be useful as an example of the code you can use:

Environment URL
Production https://www.vivapayments.com/api/messages/config/token
Demo https://demo.vivapayments.com/api/messages/config/token
  if (steps.webhookEndpoint.event.method === 'POST') {
      status: 200,
      body: { message: 'ok' }

  const axios = require("axios");

  var merchantId = '[your demo/production Viva Merchant ID]';
  var apiKey = '[your demo/production Viva API key]';

  var credentials = Buffer.from(merchantId + ':' + apiKey).toString('base64');

  const resp = await axios({
    method: "GET",
    url: "[Environment URL]",
    headers: {
      "Authorization": "Basic " + credentials,

  var code = resp.data.Key;

    status: 200,
    headers: { "test-header": "value" },
    body: { key: code }
  console.log('Webhook has been validated')

Deploy your webhook

Deploy your webhook and make it public; not private. You can confirm it, visiting your URL using a browser and getting the key string number, as String parameter type in base64 format.

In the below example, the webhook URL was generated using the ‘Pipedream’ web application.

Verify Webhook

If you don’t get any key value then the authentication is not executed successfully, and your account credentials are not validated.

Set up and verify your webhook in Self Care

To set up your webhook endpoint within the viva banking app:

Retry policy

Viva 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 (HTTP error codes 3xx, 4xx, or 5xx) a retry mechanism will apply (72 retries / 3 days) will start and run once per hour until a status 200 is received or the maximum retries threshold is reached.

Get Support

If you would like to integrate with Viva, or if you have any queries about our products and solutions, please see our Contact & Support page to see how we can help!