Setting up webhooks

Viva Wallet uses webhooks to notify you when an event happens in your account. 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 Wallet account.

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

• Whitelist the Viva Wallet addresses in your server and on your firewall
• Identify the event(s) you want to monitor
• Generate a webhook verification key
• Create a webhook endpoint as an HTTP endpoint (URL) on your server
• Handle requests from Viva Wallet parsing each event object and returning HTTP 2xx response status codes
• Deploy your webhook endpoint and make it as public; it should be accessible as HTTPS URL
• Set up and verify your webhook endpoint per event through Self Care
• Get Support

Whitelist the Viva Wallet addresses

To receive successfully webhook notifications, you should whitelist the below IP addresses in your server and in your network firewall too. The webhooks IP source will be one of the below IP addresses:

Identify the event(s) you want to monitor

You can define webhooks for the following events:

• Obligation Created – a marketplace obligation (e.g. refund request) has been successfully sent to a marketplace seller.
• Obligation Captured – a marketplace obligation (e.g. refund request) has been successfully paid by a marketplace seller.
• Account Transaction Created – wallet account balance change.
• Transaction Payment Created – a customer’s payment has been successful.
• Transaction Price Calculated – a commission payment has been withdrawn from your account by Viva Wallet.
• Transaction Reversal Created – a customer refund has been successfully actioned.
• Transaction Failed – a customer payment has been declined by their issuing bank.
• Command Bank Transfer Created – a beneficiary has been successfully created for a bank transfer to an external IBAN.
• Command Bank Transfer Executed – a bank transfer to an external IBAN has been successful.

Generate a webhook verification key

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

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.

curl '[Environment URL]'
-H 'Authorization: Basic [Base64-encoded Merchant ID and API key]'

<?php

$curl = curl_init();

curl_setopt_array($curl, array(
  CURLOPT_URL => '[Environment URL]',
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => '',
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 0,
  CURLOPT_FOLLOWLOCATION => true,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => 'GET',
  CURLOPT_HTTPHEADER => array(
    'Authorization: Basic [Base64-encoded Merchant ID and API key]'
  ),
));

$response = curl_exec($curl);

curl_close($curl);
echo $response;

Response example

{
  "Key":"B3248222FDCD1885AEAFE51CCC1B5607F00903F6"
}

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.

Create a webhook endpoint

To receive webhooks, Viva Wallet 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.

Handle requests from Viva Wallet

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

Every webhook notification includes the following properties:

• EventData ( TransactionEventData ): the actual notification
• EventTypeId ( int ): the type of the event that triggered the notification
• Created ( datetime ): the date and time the notification was initially created

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

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

  if (steps.webhookEndpoint.event.method === 'POST') {
    console.dir(steps.webhookEndpoint.event.body);
    $respond({
      status: 200,
      body: { message: 'ok' }
    })
    return;
  }

  const axios = require("axios");

  var merchantId = '[your demo/production Viva Wallet Merchant ID]';
  var apiKey = '[your demo/production Viva Wallet 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;

  $respond({
    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 generated using Pipedream web application.

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 Wallet banking app:

• Log in to Viva Wallet, demo or live , and select the required account.
• Visit Settings > API Access > Webhooks.
• Click on the Create Webhook link. The New Webhook dialog box is displayed.
• Enter your webhook URL in the URL field.
• Click on the Verify link. If verified successfully, a confirmation message is displayed.
  
  If the verification is not successful, an error message is displayed.
  
• Choose the desired webhook from the Event Type dropdown:

• Select the Active checkbox to activate notifications.
• Click on the Save button.

Get Support

If you have any questions about our solutions, or questions about how to integrate with our solutions, please refer to our Get Support page.