Native Checkout v2 API

This is a custom API to request charge tokens and to perform 3D-Secure cardholder authentication. For native applications – using a backend channel – the same functionality can be achieved as with Native Checkout v2 3DS. However, a browser is required for displaying the card issuer’s authentication window to the user.

Before you start

The demo environment has a base URL of https://demo-api.vivapayments.com/ and for the live environment it’s https://api.vivapayments.com/. For information on how to generate an access token, see OAuth 2 token generation on our Authentication page.

  1. Create an account with Viva Wallet, if you do not already have one. There are two types:
  2. Log in to your demo account or live account .
  3. Complete our Request access token procedure.
  4. Make a note of your access token which will expire after 3600 seconds (one hour). Include a function in your code that repeats step 3 above programmatically before each expiry.
  5. Create a payment source selecting Redirection/Native Checkout v2 as the integration method.

API calls

1. Create a one-time charge token

Custom integrations must be able to make HTTP calls directly to the Native Checkout v2 API from the user’s environment. Cardholder details, such as card numbers or the card’s verification value (CVV) must not be transmitted to any endpoint other than those provided by Viva Wallet, in order to ensure that your implementation remains compliant with PCI-DSS standards.

To retrieve a one-time charge token with your own checkout implementation, simply make an HTTP POST request to the chargetokens endpoint as shown below. The charge token will expire after 10 minutes.

post    /nativecheckout/v2/chargetokens

Request example

curl -X POST \
  https://demo-api.vivapayments.com/nativecheckout/v2/chargetokens \
  -H 'Authorization: Bearer [access token]' \
  -H 'Content-Type: application/json' \
  -d '{
		"amount": 100,
		"cvc": "111",
    "number": "[test card number]",
    "holderName": "John Doe",
    "expirationYear": 2030,
    "expirationMonth": 10,
    "sessionRedirectUrl": "[my redirect URL]"
}'

To simulate a successful payment in the demo environment, replace [test card number], above, with a number from one of our test cards. You can make a demo payment of 30¢/30p or more.

If your request was successful, a JSON response containing the charge token and the HTML code necessary to perform cardholder authentication, is returned (assuming the card is 3DS-enrolled).

Response example

{
    "chargeToken": "ctok_bcGN8H87tGi1qtxtEoYkliYgMrc",
    "redirectToACSForm": "<html><head></head><body>Hey there! Don't
      forget to render me!</body></html>"
}

When the redirectToACSForm HTML code is rendered, an authentication session is initiated: the user is redirected to their issuer’s page to authenticate before continuing with the transaction.

After completing the authentication session, the user is redirected to the URL defined in the sessionRedirectUrl parameter. The redirection signals the end of the authentication session. The final charge to the user’s card is applied when the charge token is submitted.

2. Make the actual charge using the one-time charge token

After a successful call to chargetokens, you need to create a new transaction.

post    /nativecheckout/v2/transactions

Request example

curl -X POST \
  https://demo-api.vivapayments.com/nativecheckout/v2/transactions \
  -H 'Authorization: Bearer [access token]' \
  -H 'Content-Type: application/json' \
  -d '{
  "amount": 100,
  "preauth": false,
  "sourceCode": "[4-digit code of your payment source]",
  "chargeToken": "[charge token]",
  "installments": 1,
  "merchantTrns": "Merchant transaction reference",
  "customerTrns": "Description that the customer sees",
  "currencyCode": 826,
  "customer": {
	  "email": "native@vivawallet.com",
	  "phone": "442037347770",
	  "fullname": "John Smith",
	  "requestLang": "en",
	  "countryCode": "GB"
   }
}'

Response example

If the cardholder’s authentication was successful and all other requirements meet (e.g. account has enough balance etc.) then you should receive a response similar to the one below:

{
  "transactionId": "1549bffb-f82d-4f43-9c07-0818cdcdb2c4"
}

3. Capture a pre-auth

For cases where a pre-authorization is created instead of a charge, a separate call to the transaction endpoint will be required. Pass the amount of the pre-authorization, or a smaller amount, to create the charge:

get    /nativecheckout/v2/transactions/{preauthTransactionId}

Request example

curl -X POST \
  https://demo-api.vivapayments.com/nativecheckout/v2/transactions/b1a3067c-321b-4ec6-bc9d-1778aef2a19d \
  -H 'Authorization: Bearer [access token]' \
  -H 'Content-Type: application/json' \
  -d '{
    "amount": 300,
}'

Response example

{
  "transactionId": "1549bffb-f82d-4f43-9c07-0818cdcdb2c4"
}

4. Check for installments

Pass the number as an HTTP header to retrieve the maximum number of installments allowed on a card:

get    /nativecheckout/v2/installments

Request example

// Card number as a header
"cardNumber" : "5239290700000101"

Response example

{
  "maxInstallments": 3
}