☰

Navigation:

OAuth 2.0 authentication

OAuth 2.0 (IdentityServer) is the updated authentication method used for many of Viva's APIs. We obtain consent securely, ensuring the integrity and confidentiality of security credentials and authentication codes.

Overview

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.

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

How to authenticate using OAuth 2.0

Please follow the steps below to authenticate using OAuth 2.0 when using Viva’s APIs:

Step 1: Find your client credentials

Depending on your use case, different credentials may be required. You can locate these credentials as below:

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.

You can request a token by passing your credentials in one of the following two ways:

Please see the relevant API endpoints below:

Environment Endpoint
Demo https://demo-accounts.vivapayments.com/connect/token
Production https://accounts.vivapayments.com/connect/token
In Base64-encoded format

Using this method, you must first Base64-encode your credentials in the format Client_ID:Client_Secret. This gives a result such as:

Z2VuZXJpY19hY3F1aXJpbmdfY2xpZW50LmFwcHMudml2YXBheW1lbnRzLmNvbTpnZW5lcmljX2FjcXVpcmluZ19jbGllbnQ

To generate a bearer token for Smart Checkout, please use the Smart Checkout Client ID and Client Secret as outlined on this page, and as mentioned above

You can then use the encoded credentials in your request as shown in the below cURL example.

post    /connect/token

Run in Postman

 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'
As parameters in an HTTP call

You can also pass your credentials as parameters in an HTTP call. The following example uses the Postman client:

Under the Authorization tab of your API call, select the Basic Auth option and enter the following credentials:

Access Credentials

Step 3: Receive access token

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

Response example
 {
     "access_token": "eyJhbGciOiJSUzI1NiIsImtpZCI6IjBEOEZCOEQ2RURFQ0Y1Qzk3RUY1MjdDMDYxNkJCMjMzM0FCNjVGOUZSUzI1NiIsInR5cCI6ImF0K2p3dCIsIng1dC",
     "expires_in": 3600,
     "token_type": "Bearer",
     "scope": "urn:viva:payments:core:api:redirectcheckout"
 }

Each token lasts for 3600 seconds (one hour), before expiration. After this time you will need to request a new token

Step 4: Make API calls 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 must include the access token at the authorization header with bearer instead of basic selected

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!