Handle Card Tokens

Applicable to our Smart Checkout solution for payments with card only.

Smart Checkout offers merchant-side card tokenization (in addition to customer-side card tokenization). This means that the merchant can save the card tokens of their customers in the merchant backend, and then use the saved card tokens when the merchant will redirect their customers to Smart Checkout again in the future. The saved card tokens provided by the merchant will then be presented to the customer on Smart Checkout to use and pay with.

This feature is available only upon request. Please contact your sales representative or use our Live Chat to request this feature.

On this page:

Flow overview

Below we provide the flow for handling card tokens (merchant-side card tokenization).

The below sequence diagram summarises the handling card token procedure.

sequenceDiagram participant Merchant app participant Merchant backend participant Viva Wallet API Viva Wallet API-->>Merchant app:Customer paid & transaction created (1) Merchant backend->>Viva Wallet API:Retrieve payment details (use API, if no webhook is set up)(2) Viva Wallet API-->>Merchant backend:Payment details (webhook or API) (3) Merchant backend->>Merchant backend:Verify payment & check if paid with card (4) Note right of Merchant backend: Continue only
if paid with card Merchant backend->>Merchant backend:Check if card already saved (5) Note right of Merchant backend: Continue only
if card not already
saved Merchant backend->>Viva Wallet API:Create card token(6) Viva Wallet API-->>Merchant backend:Card token (7) Merchant backend->>Merchant backend:Save card token (8) Note right of Merchant backend: When customer
pays again Merchant backend->>Viva Wallet API:Create payment order using saved card tokens of customer (9)

Notes: Check if paid with card

Get the card unique reference number with Retrieve Transaction API call

When you use the Retrieve transaction API, you get the status of the payment with additional information including the transactionTypeId parameter that can be checked to determine if the payment is made with a card (transactionTypeId can have a number of different values, see the transactionTypeId parameter on our Response codes page for the full list).

You may find your Retrieve Transasction API request and response here.

Get the card unique reference number from Transaction Payment Created webhook

When using the Transaction Payment Created webhook to be notified, you get the status of the payment with additional information including the transactionTypeId parameter that can be checked to determine if the payment is made with a card (transactionTypeId can have a number of different values, see the transactionTypeId parameter on our Response codes page for the full list).

You may find an example of webhook payload here.

Notes: Check if card already saved

Provided the customer has paid using a card, you should check that you do not have a card token for that card already saved in your backend by checking that the cardUniqueReference of the current card payment is not already stored in your backend. You may already have the cardUniqueReference stored in your backend if the customer had used this card in the past and you have created a card token, and saved it along with its cardUniqueReference, back then.

Notes: Create card token

Provided you do not have a card token for that card already saved in your backend, to create a card token from a transaction id, you should call Create card token API. As soon as you create a card token, you should pair it with the relevant cardUniqueReference and save them in your backend.

It is vital to save the pair (cardUniqueReference, token) as you will need the cardUniqueReference in the future to check if you already have saved tokens for the cards used by the customers. This is mandatory because different transactions that were paid with the same card number will return different card tokens, so before saving a card token on your backend for a specific customer you first need to make sure that the ‘card unique reference’ of the transaction is different than the ones already saved for past transactions.

Please make sure that you associate the card token with the relevant user. It is your responsibility to have the customer’s consent to save the card token on your backend.

This API call uses OAuth2 authentication.

post    /acquiring/v1/cards/tokens

Create card token request

{
    "transactionId": "6cffe5bf-909c-4d69-b6dc-2bef1a6202f7",
}

Create card token response

{
    "token": "ct_480c964156d949c19abe1b1061b21108"
}

Notes: Create payment order using saved card tokens of customer

To redirect a customer to Smart Checkout and present him with his card tokens, you should append the cardTokens array to the body of the request of the Create Payment Order API call.

You can only send up to ten card tokens at once.

You cannot send card tokens if the payment order is for an open amount, i.e. if disableExactAmount is true.

To create a smart checkout form with pre-defined saved cards, you should append cardTokens array to the body of the request and call Create Payment Order API. You can send up to ten card tokens at once.

This API call uses OAuth2 authentication.

post    /checkout/v2/orders

Create payment order request

{
    "amount": 1200,
    "sourceCode": "Default",
    "paymentTimeout": 300,
    "customerTrns": "Short description of purchased items/services to display to your customer",
    "merchantTrns": "Short description of items/services purchased by customer",
    "cardTokens": ["ct_2121888454054a26bcee739a8f918adb"],
    "customer":
    {
        "email": "johdoe@vivawallet.com",
        "fullName": "John Doe",
        "phone": "+30999999999",
        "countryCode": "GB",
        "requestLang": "en-GB"
    }
}

Create payment order response

{
    "orderCode": 9877085190254231
}
Environment URL
Production https://api.vivapayments.com/checkout/v2/orders
Demo https://demo-api.vivapayments.com/checkout/v2/orders

Get Support

If you would like to integrate with Viva Wallet, or if you have any queries about our products and solutions, please see our Get Support page to see how we can help!