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.

Process flow diagram

Sequence diagram showing the process flow:

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 by selecting Redirection/Native Checkout v2 as the integration method.
3. Make a note of your time-limited access token.

Setup instructions

Card tokenization consists of the following steps:

• Step 1: Generate one-time charge token using card details
• Step 2: Generate card token using the charge token (optional)
• Step 3: Generate one-time charge token using card token (optional)
• Step 4: Make the actual charge

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.

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

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

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

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

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:

Request example

curl -X GET \
  'https://demo-api.vivapayments.com/acquiring/v1/cards/chargetokens?token=2188A74B6BB8DE0D5671886B5385125121CAE870' \
  -H 'Authorization: Bearer <access token>' \
  -H 'Content-Type: application/json'

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:

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

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

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.