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.
- 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.
- Log in to your demo account or live account .
- Complete our Request access token procedure.
- 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.
- 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:
- Generate one-time charge token using card details
- Generate card token using the one-time charge token
- Generate one-time charge token using saved card token
- Make the actual charge using the one-time charge token
- 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:
/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: 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:
/acquiring/v1/cards/chargetokens?token={cardtoken}
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:
/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": "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.