Authentication

Here you can find information about the two authentication types used for connection to our APIs.

Basic authentication

Once you’ve registered with Viva Wallet, you can use basic authentication to implement our Simple Checkout, Redirect Checkout and Payment API.

Basic Authentication is the least secure of the supported authentication mechanisms. Your credentials are not encrypted or hashed; they are Base64-encoded only.

How to authenticate using basic auth

With basic authentication, you pass your Viva Wallet credentials (Merchant ID and API Key) in each request to our APIs. You can pass your credentials as a Base64-encoded header or as parameters in an HTTP client.

If using Postman, under Authorization you select Basic Auth and enter the following:

• Username – same as Viva Wallet Merchant ID
• Password – same as Viva Wallet API Key

When you pass your credentials in the header, you must Base64-encode them. The following is an example of an encoded HTTP basic authentication header:

Authorization: Basic ZmJmMWUwOTAtNjVkZS00Yzc1LWI1ODAtZDlkOWJjNDk0YWQyOldEdi1WKw==

With a client such as cURL, you pass your encoded credentials in the header with the -H option, as the following example shows:

curl -X POST \
  https://demo.vivapayments.com/api/orders \
  -H 'Authorization: Basic ZmJmMWUwOTAtNjVkZS00Yzc1LWI1ODAtZDlkOWJjNDk0YWQyOldEdi1WKw==' \
  -H 'Content-Type: application/json' \
  -d '{
  "Tags": [
    "sample string 1",
    "sample string 2",
    "sample string 3"
  ],
  "Email": "customer@domain.com",
  "Phone": "2117604000",
  "FullName": "Customer name",
  "PaymentTimeOut": 86400,
  "RequestLang": "en-US",
  "MaxInstallments": 12,
  "AllowRecurring": true,
  "IsPreAuth": true,
  "amount": 100,
  "MerchantTrns": "Your reference",
  "CustomerTrns": "Description that the customer sees"
}'

Running the above from the command line should result in a response containing an order code generated by the Create payment order call from our Payment API.

IdentityServer (OAuth 2) authentication

Viva Wallet’s Native Checkout v2, 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.

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.

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: Generate client credentials

Before you can request an access token, you need to obtain client credentials from Viva Wallet. To do this:

1. Log in to Viva Wallet, demo or live , and select the required account.

2. Click on Settings in the left navigation:
   
   

3. Click on API Access:
   
   

4. Find the Native Checkout v2 Credentials section within the page:
   
   

5. Copy and paste your Client ID and Client Secret to a temporary location.

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:

Demo environment

 POST https://demo-accounts.vivapayments.com/connect/token HTTP/1.1
 Authorization: Basic Z2VuZXJpY19hY3F1aXJpbmdfY2xpZW50LmFwcHMudml2YXBheW1lbnRzLmNvbTpnZW5lcmljX2FjcXVpcmluZ19jbGllbnQ
 Accept: application/json
 Content-Type: application/x-www-form-urlencoded
 grant_type=client_credentials

Production environment

 POST https://accounts.vivapayments.com/connect/token HTTP/1.1
 Authorization: Basic Z2VuZXJpY19hY3F1aXJpbmdfY2xpZW50LmFwcHMudml2YXBheW1lbnRzLmNvbTpnZW5lcmljX2FjcXVpcmluZ19jbGllbnQ
 Accept: application/json
 Content-Type: application/x-www-form-urlencoded
 grant_type=client_credentials

Step 3: Generate 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.