Card Tokenization API

Viva Wallet uses tokenization to collect sensitive card details directly from your customers securely. We return a token representing this information for your server to use. This ensures that sensitive card data is kept safe, and enables your integration to operate in a PCI-compliant way.

Have a look, first, at how to create a recurring transaction. Using a previous transaction is, in most cases, superior to saving a card. The latter involves extra work.

Overview

Sequence diagram showing the process flow:

sequenceDiagram participant Merchant app participant Merchant backend participant Viva Wallet API note over Merchant backend:Create identity token Merchant backend->>Viva Wallet API: Generate access token Viva Wallet API-->>Merchant backend: Access token (type = bearer) Merchant backend->>Merchant app: Access token (type = bearer) note over Merchant backend:Saving a card Merchant app->>Viva Wallet API: (1) Generaten one-time charge token from card details Viva Wallet API-->>Merchant app: Charge token, e.g. "ctok_Rc4c27orSU56SSMOLDijTMYA8X4" Merchant app->>Viva Wallet API: (2) Generate card token from charge token (optional) Merchant app->>Merchant backend: Charge token Merchant backend->>Viva Wallet API:Charge token Viva Wallet API-->>Merchant backend: Card token, e.g. "0FB1A1EBF41440FDF88A359" Merchant backend->>Merchant backend:Save card token note over Merchant backend:Charging a saved card Merchant app->>Viva Wallet API: (3) Make the actual charge Merchant app->>Merchant backend:Charge token Merchant backend->>Viva Wallet API:Charge token Viva Wallet API-->>Merchant backend:Transaction ID (200 OK)

Prerequisites

  1. Log in to the Viva Wallet banking app, demo or live .
  2. Complete our OAuth 2 token generation procedure.
  3. Create a payment source selecting Redirection/Native Checkout v2 as the integration method.

The demo environment has a base URL of https://demo-api.vivapayments.com/ and for the live environment it’s https://api.vivapayments.com/.

Setup instructions

Card tokenization consists of the following steps:

Step 1: Generate one-time charge token using card details

To limit your PCI scope and avoid sensitive data passing through your servers, you need to perform this call from the customer’s browser.

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": 1000,
    "cvc": "111",
    "number": "4111111111111111",
    "holdername": "John Doe",
    "expirationYear": 2030,
    "expirationMonth": 10,
    "sessionRedirectUrl": "https://www.example.com"
}'

Response example

{
  "chargeToken": "ctok_Zxng0anBhUGMRang_xrfUw2"
}
Property Description
chargeToken This is a random, unique string that can be used in place of card in order to initiate a transaction. It has a short expiration period and once it is used it is disposed. Disposed tokens are not reused.
HTTP Status Message Explanation
200 (OK) Successfully create a token that can be used to initiate a transaction
400 (Bad Request) Null or whitespace CVC Null or whitespace Cvc
400 (Bad Request) Invalid length for CVC Must be 3 or 4 characters
400 (Bad Request) Invalid ExpirationMonth Month [1 - 12]
400 (Bad Request) Invalid ExpirationYear Year [1 - 9999]
400 (Bad Request) Invalid card Expiration Date Past date
400 (Bad Request) Invalid CardNumber The card cardNumber field is not a valid card number or it is not supported

Step 2: Generate card token using the charge token (optional)

You can 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_Zxng0anBhUGMRang_xrfUw2' \
  -H 'Authorization: Bearer <access token>' \
  -H 'Content-Type: application/json' \
  -H 'Host: demo-api.vivapayments.com' \
  -d '{
  "preauth": false,
  "sourceCode": "4693",
  "chargeToken": "ctok_Zxng0anBhUGMRang_xrfUw2",
  "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

{
  "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: Generate one-time charge token using card token (optional)

Each time you want to charge a card you would generate a new charge token from the card token:

get    /acquiring/v1/cards/chargetokens?token={cardtoken}

Request example

curl -X GET \
  'https://demo-api.vivapayments.com/acquiring/v1/cards/chargetokens?token=05FB1A1EBF41440FDF88A359C46645B6D1EE3EF5' \
  -H 'Authorization: Bearer <access token>' \
  -H 'Content-Type: application/json' \
  -d '{
  "amount": 1000,
  "preauth": false,
  "sourceCode": "4693",
  "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

    {
      "chargeToken": "ctok_17wzXgZFCziELn22JzFm_g_0V74"
    }

Step 4: Make the actual charge

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

post    /nativecheckout/v2/transactions

Sample request
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": "4693",
  "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"
   }
}'

The above call cannot be made through a browser. Use a backend channel instead.

Always pass customer’s details so that the payment is recognizable and the receipt sent will be in your customer’s language.

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

Migrating your recurring payments

You can migrate your recurring payments implementation to Card Tokenization. Use our Retrieve transactions API endpoint to retrieve card tokens, which you can trade for charge tokens, and follow the above flows.