Card Tokenization API

The Viva Wallet Card Tokenization API enables you to offer customers the option of returning to your checkout with their card details stored for re-use. Tokenization means we collect sensitive card details directly from your customers securely via a token you use to take future payments in place of the actual card details. This ensures that sensitive card data is kept safe, and allows your integration to operate in a PCI-compliant way.

For information about how to set up recurring payments, which are different from card tokenization, see Create transaction in our Payment API section.

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.

Integration flow diagram

The below sequence diagram outlines the card tokenization procedure from beginning to end.

sequenceDiagram participant Merchant app participant Merchant backend participant Viva Wallet API Note over Merchant backend: Initial payment Merchant app->>Viva Wallet API: Generate initial charge token using card details Viva Wallet API-->>Merchant app: Initial charge token, e.g. "ctok_Rc4c27orSU56SSMOLDijTMYA8X4" Merchant app->>Viva Wallet API: Generate card token using initial charge token Viva Wallet API-->>Merchant backend: Card token, e.g. "0FB1A1EBF41440FDF88A359" Merchant backend->>Merchant backend:Save card token Merchant app->>Viva Wallet API: Make the actual charge using the initial charge token Viva Wallet API-->>Merchant backend:Transaction ID (200 OK) Note over Merchant backend: Future payments loop Each subsequent payment Merchant app->>Viva Wallet API: Generate one-time charge token using saved card token Viva Wallet API-->>Merchant app: One-time charge token, e.g. "ctok_F3Lxb-PC0SM4d_2IQoyALEl9vaQ" Merchant app->>Viva Wallet API: Make the actual charge using the one-time charge token Viva Wallet API-->>Merchant backend:Transaction ID (200 OK) end

Integration flow instructions

Card tokenization consists of the following steps:

  1. Generate initial charge token using card details
  2. Generate card token using initial charge token
  3. Make the actual charge using the initial charge token
  4. Verify transaction and set webhook (optional)
  5. Generate one-time charge token using saved card token
  6. Make the actual charge using the one-time charge token
  7. Verify transaction and set webhook (optional)

Step 1: Generate initial charge token using card details

Follow steps 1, 2, 3 and 4 in our Native Checkout v2 integration guide to generate the initial charge token. 3DS authentication must have been successful otherwise the PaymentsCardHolderAuthenticationInvalidStatus error will be returned in the response.

Step 2: Generate card token using initial charge token

You can generate and then save the card token for future transactions by using the following call:

get    /acquiring/v1/cards/tokens?chargetoken={chargetoken}

Request example

curl -X GET \
  'https://demo-api.vivapayments.com/acquiring/v1/cards/tokens?chargetoken=ctok__pEfMPKCt-FHnN0vS3T23Gz1aDk' \
  -H 'Authorization: Bearer [access token]' \
  -H 'Content-Type: application/json'

Response example

{
  "token": "05FB1A1EBF41440FDF88A359C46645B6D1EE3EF5"
}
Property Description
token This is a random, unique string that represents a card’s details. It is unique per card and can be traded for a chargeToken.

Step 3: Make the actual charge using the initial charge token

With the one-time charge token created in step 1, above, a charge, can be created. This will transfer the amount from the card to your wallet:

post    /nativecheckout/v2/transactions

Sample request

Tip: The below call cannot be made through a browser. Use a backend channel instead.

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

currencyCode is an ISO 4217 code. It should be set to the same currency as your Viva Wallet account. In the example above, the currency is GBP. If registered your account in a Eurozone country, it would be EUR with a code of 978.

requestLang and countryCode should be set appropriately for the customer’s language and country.

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 containing the charge’s transactionId:

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

Step 4: Verify transaction and set webhook (optional)

You can make a call to Retrieve transactions in order to verify the status of a payment. To get automatic notifications you can make use of our webhooks functionality.

Step 5: Generate one-time charge token using saved card 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 '{
		"token": [card token],
    "amount": 100,
    "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.

Step 6: Make the actual charge using the charge token

Now that you have acquired the one-time charge token from the previous step, you will need to create a charge, in order to conclude the payment:

post    /nativecheckout/v2/transactions

Request example

Tip: The below call cannot be made through a browser. Use a backend channel instead. Replace [access token] with the one you obtained during the OAuth 2 token generation procedure outlined on our Authentication page. You should swap [4-digit code of your payment source] for the code of the payment source you created earlier. Overwrite [charge token] with the time-limited token generated in step 4 above.

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

<?php

$curl = curl_init();

curl_setopt_array($curl, array(
  CURLOPT_URL => 'https://demo-api.vivapayments.com/nativecheckout/v2/transactions',
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_FOLLOWLOCATION => true,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => 'POST',
  CURLOPT_POSTFIELDS =>'{
 "amount": 100,
 "tipAmount": 50, //optional
 "preauth": false,
 "sourceCode": "[4-digit code of your payment source]",
 "chargeToken": "[charge token]",
 "installments": 1,
 "merchantTrns": "Merchant transaction reference",
 "customerTrns": "Short description of items/services purchased to display to your customer",
 "currencyCode": 978,
 "customer": {
      "email": "native@vivawallet.com",
      "phone": "442037347770",
      "fullname": "John Smith",
      "requestLang": "en",
      "countryCode": "GB"
   }
}',
  CURLOPT_HTTPHEADER => array(
    'Content-Type: application/json',
    'Authorization: Bearer 19D796327FDB4962B994D8F49B465F5323513F20D02A37F6A5B282369D176600'
  ),
));

$response = curl_exec($curl);

curl_close($curl);
echo $response;

currencyCode is an ISO 4217 code. It should be set to the same currency as your Viva Wallet account. In the example above, the currency is GBP. If you registered your account in a Eurozone country, it would be EUR with a code of 978.

requestLang and countryCode should be set appropriately for the customer’s language and country.

Response example

If the cardholder’s authentication was successful and all other requirements meet (e.g. account has enough balance etc.) then the payment will be successful and you should receive a response containing the charge’s transactionId:

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

Step 7: Verify transaction and set webhook (optional)

You can make a call to Retrieve transactions in order to verify the status of a payment. To get automatic notifications you can make use of our webhooks functionality.

Further information

Check out the related tutorials below for more details about OAuth 2 authentication and setting webhooks: