Tokenize card

Viva Wallet uses tokenization to collect sensitive card details directly from your customers in a secure manner. A token representing this information is returned to your server to use. This ensures that no sensitive card data touches your server, and allows your integration to operate in a PCI-compliant way.

Make sure you read about the Create recurring transaction API. Using a previous transaction is, in most cases, superior to saving a card due to the extra work involved.

Some calls involved in the above flows use bearer token authentication, whereas others use basic authentication. See Authentication methods for more information.

Step 1 – Get charge token using card details

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

Environment Endpoint
Demo https://demo-api.vivapayments.com/acquiring/v1/cards/chargetokens
Production https://api.vivapayments.com/acquiring/v1/cards/chargetokens
POST https://demo-api.vivapayments.com/acquiring/v1/cards/chargetokens

Request

{
  "cvc": "111",
  "expirationMonth": 1,
  "expirationYear": 2018,
  "holderName": "Card Holder",
  "number": "4111111111111111"
}

Response

{
  "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 – Get card token using the charge token

You should save the card token for future usage.

GET https://demo-api.vivapayments.com/acquiring/v1/cards/tokens?chargeToken={chargeToken}

Response

{
     "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 – Get charge token using card token

GET https://demo-api.vivapayments.com/acquiring/v1/cards/chargetokens?token={cardtoken}

Response

{
  "chargeToken": "ctok_Zxng0anBhUGMRang_xrfUw2"
}

Step 4 – Create an Order

See Create order for more information.

Step 5 – Execute the payment

You should have by now an OrderCode and a Charge Token for the your customers card. To complete the payment, call Viva Payments’ API to execute the transaction.

POST https://demo.vivapayments.com/api/transactions

Request

{
  "OrderCode" : OrderCode,
  "SourceCode": 'Default',
  "CreditCard" : {
     "Token": 'Token'
  }
}

Response

A successful Payment Execution call results in a response 200 along with an object of the following type

{
    string StatusId;
    Guid TransactionId;
    int RemainingRefunds;
    int ErrorCode;
    string ErrorText;
    DateTime TimeStamp;
}

If the call is not successful, you will receive a different status response (e.g. 400, 403) along with a full description of the error as a ReasonPhrase.

Response status 200 indicates only a successful call to Viva Wallet API. To check the actual outcome of the transaction (whether the customer’s card was charged or not) you need to check property ErrorCode.

Migrating your recurring payments

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