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 allows your integration to operate in a PCI-compliant way.

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:
   • Sandbox/demo account, for testing purposes
   • Production/live account, for payments in the real world.
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.

Integration flow instructions

Card tokenization consists of the following steps:

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

Step 1: Generate one-time 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 the one-time charge token

You can generate and then 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 saved card token

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 using the one-time charge token

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": 100,
  "tipAmount": 50, //optional
  "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"
   }
}'

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 5: 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.