Native Checkout v2 API

A custom API to request charge tokens and to perform 3DSecure 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/.

  1. Complete our OAuth 2 token generation procedure.
  2. Create a payment source selecting Redirection/Native Checkout v2 as the integration method.
  3. Make a note of your time-limited access token.

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:

post    /nativecheckout/v2/chargetokens

Request example

The card number 4111111111111111 can be used for demo purposes and will trigger the 3DS functionality during testing. You can use any future date as the card expiration date and any CVV.

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

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.

Create transaction

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": 1000,
  "preauth": false,
  "sourceCode": "<payment source code>",
  "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"
}

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"
}

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" : "4111111111111111"

Response example

{
  "maxInstallments": 3
}