Authentication

Here you can find information about each of the two authentication types we use for connection to our APIs.


Basic authentication

Viva Wallet’s Simple Checkout, Redirect Checkout, Native Checkout v1 and Payment API (except card tokenization) use basic HTTP authentication over SSL.

Every request should include a standard authorization header with the following:

  • Username
    This is your unique MerchantId available on your profile page in the banking app.

  • Password
    The transaction password or API Key is also shown on your profile page. This is different from the password you use to access your account from the Viva Wallet website.

You can view examples of passing the authorization header in the sample code available under CreateOrder   within our public GitHub account.

Create unlimited demo accounts  . For the demo environments, you are required to set a new transaction password in your demo profile.


IdentityServer (OAuth 2) authentication

Viva Wallet’s Native Checkout v2, card tokenization, SmartMoney API, Issuing API and Account API exploit IdentityServer (OAuth 2) for authentication. We obtain consent securely from customers and ensures the integrity and confidentiality of the personalised security credentials and of authentication codes.

Authorization code flow

Logging in to an application is performed by a redirection to our Viva Payments Identity Server (OAuth 2 specification) in which the user provides their credentials through a secure channel (HTTPS). Redirection ensures that no malicious client-side scripting can run on the page, and no other client-side script can access the contents of the log-in page.

Environment Endpoint
Demo https://demo-accounts.vivapayments.com/connect/token
Production https://accounts.vivapayments.com/connect/token

IdentityServer is an OpenID Connect Provider. It is used to:

  • manage and authenticate client applications
  • issue identity and access tokens to client applications
  • validate tokens.

OAuth 2 token generation

Follow the steps below to generate a bearer token for use with our APIs. The token has a time limit of one hour after which it expires.

Step 1: Apply for client credentials

Before you can request an access token, you need to obtain client credentials from Viva Wallet. Please raise an issue via our public GitHub account, specify which of our API(s) you want to use and let us know whether you need demo or production access.

For security reasons, do not include your merchant ID(s) at this stage. We’ll reply back and ask you to email us those along with any other information we need. The turnaround time is normally up to 24 hours. If you’re requesting production access, it may take a little longer.

For Viva Wallet accounts containing a number of merchant accounts, a different set of credentials is required for each.

Step 2: Request access token

Resource access is allowed to clients only with the use of access tokens. The first step before issuing any calls to the Viva Payments API is to obtain an access token by making a POST request.

Before proceeding you need to encode the client credentials without any spaces and separated by a colon:

[Client ID]:[Client Secret]

into Base64 format. This gives a result such as:

Z2VuZXJpY19hY3F1aXJpbmdfY2xpZW50LmFwcHMudml2YXBheW1lbnRzLmNvbTpnZW5lcmljX2FjcXVpcmluZ19jbGllbnQ

You can then use in your HTTP request as shown below:

 POST https://demo-accounts.vivapayments.com/connect/token HTTP/1.1
 Authorization: Basic Z2VuZXJpY19hY3F1aXJpbmdfY2xpZW50LmFwcHMudml2YXBheW1lbnRzLmNvbTpnZW5lcmljX2FjcXVpcmluZ19jbGllbnQ [client credentials encoded in base64 format]
 Accept: application/json
 Content-Type: application/x-www-form-urlencoded
 grant_type=client_credentials

Below is a php code sample showing the request:


<?php

$authurl =  'https://demo-accounts.vivapayments.com/connect/token';
$client_id = '9dd8b7b2-f65d-4eff-b715-6dee12eaf4ac.apps.vivapayments.com';
$client_secret = '9dd8b7b2-f65d-4eff-b715-6dee12eaf4ac';
$postdata = [
    "grant_type"=>"client_credentials"
];

$curl = curl_init($authurl);
curl_setopt($curl, CURLOPT_USERPWD, $client_id . ":" . $client_secret);
curl_setopt($curl, CURLOPT_RETURNTRANSFER, true);
curl_setopt($curl, CURLOPT_POST, true);
curl_setopt($curl, CURLOPT_POSTFIELDS, $postdata);
$jsonResponse = curl_exec($curl);
if(curl_errno($curl)){
    throw new Exception(curl_error($curl));
}

$response = json_decode($jsonResponse, true);
$access_token = $response['access_token'];
$access_token_type = $response['token_type'];

echo $access_token_type . ' : ' . $access_token;die("eeee");

?>

To try out in Postman, you would enter the client credentials directly as shown below and click on the Send button:

Request access token

Step 3: Accept and store access token

After successful authentication the identity server will respond by providing the access token requested:

     {
       "access_token":
       "eyJhbGciOiJSUzI1NiIsImtpZCI6IjBEOEZCOEQ2RURFQ0Y1Qzk3RUY1MjdDMDYxNkJCMjMzM0FCNjVGOUYiLCJ0eXAiOiJKV1QiLCJ4NXQiOiJEWS00MXUzczljbC05U2ZBWVd1eU16cTJYNTgifQ.eyJuYmYiOjE1NjAxNTc4MDQsImV4cCI6MTU2MDE2MTQwNCwiaXNzIjoiaHR0cHM6Ly9kZW1vLWFjY291bnRzLnZpdmFwYXltZW50cy5jb20iLCJhdWQiOlsiaHR0cHM6Ly9kZW1vLWFjY291bnRzLnZpdmFwYXltZW50cy5jb20vcmVzb3VyY2VzIiwiY29yZV9hcGkiXSwiY2xpZW50X2lkIjoiZ2VuZXJpY19hY3F1aXJpbmdfY2xpZW50LmFwcHMudml2YXBheW1lbnRzLmNvbSIsInNjb3BlIjpbInVybjp2aXZhOnBheW1lbnRzOmNvcmU6YXBpOmFjcXVpcmluZyIsInVybjp2aXZhOnBheW1lbnRzOmNvcmU6YXBpOmFjcXVpcmluZzpjYXJkcyIsInVybjp2aXZhOnBheW1lbnRzOmNvcmU6YXBpOmFjcXVpcmluZzpjYXJkczp0b2tlbnMiXX0.GNjeRJhQQir3M_rqvjC0C9Up_pA2AFxlv9dhpr-7C-Lk0Xr5gJyGwgb0BD7Bvp2Oku-CjgG8tqE0s8KaWGHYIqGQyFJIUWiHWMejRKRqkuzt128NbThX7f4w-tN6DoyP1EouDhBsMs5BwrxOkbkIXtSjBxkE7jEOrRJ4YNAv-DjuDsPtAjC0cTLEDQBnMHLHAE-c2XHJ84I9WLFnOUX6-lwdwWuefv5o6BpvfNFC6y0mR-DcAi9KE82jRFVoY5G7xY6HQnS6RqaNDC5ifhdZKZcpgUxxdPTIWpS5L2F81RXsoMq3BSAWqvwuNeT8QTWDvtAsv_fgUABs06P7-slnvg",
       "expires_in": 3600,
       "token_type": "Bearer"
     }

The token lasts for 3600 seconds which equates to one hour, after which you need to request a new one.

Step 4: Make calls to the API

From now on the client can access API resources with the use of the access token until it expires and needs renewing. Subsequent calls to the API must include the access token at the authorization header with bearer instead of basic selected.