OAuth2 authentication

Viva Wallet’s Obligations API and APIs for issuing use 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.

sequenceDiagram participant Client participant IdentityServer participant User Client->>IdentityServer:authorize request loop User login IdentityServer->>User: Login prompt User-->>IdentityServer: Login end IdentityServer-->>Client:authorization code Client->>IdentityServer:token request Note left of Client: ID Token
Access Token IdentityServer-->>Client:token response

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:

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. The overall process is as follows:

  1. Find your client credentials
  2. Request access token
  3. Receive access token
  4. Make calls to the API using the access token

Step 1: Find your client credentials

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 (with no 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 request as shown in the below cURL example:

 curl -L -X POST 'https://demo-accounts.vivapayments.com/connect/token' \
 -H 'Content-Type: application/x-www-form-urlencoded' \
 -H 'Authorization: Basic ZzI0N2NmbnlwYzV3cmszaHAwZnU2cTk3N2YzZzYxY2hnODV1NzJzZmJkb3c3LmFwcHMudml2YXBheW1lbnRzLmNvbTowYk9xOHRkMzhMQVF4b3ptaWVqUDYwUzdzQnJkVkQ=' \
 --data-urlencode 'grant_type=client_credentials'

Run in Postman

Step 3: Receive access token

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

{
  "access_token":"7e53b85b7a1de2a1e777729b925b877c3636124c0ff57bfa2f54021c279ecc2e",
  "expires_in":3600,
  "token_type":"Bearer",
  "scope":"urn:viva:payments:core:api:acquiring urn:viva:payments:core:api:acquiring:cards:tokens urn:viva:payments:core:api:nativecheckoutv2"
}

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 using the access token

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

Further information

Check out the related tutorials below for more details about basic / OAuth 2 authentication: