Handle Card Tokens

How to handle card tokens.

• Overview
• Flow
• Notes: Check if paid with card (not a digital wallet transaction)
  • Get the card unique reference number with Retrieve Transaction API call
  • Get the card unique reference number from Transaction Payment Created webhook
• Notes: Check if card already saved
• Notes: Create card token
• Notes: Create payment order using saved card tokens of customer
• Get Support

Overview

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.

Flow

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

• First, the customer makes a payment and the merchant gets the transactionId.(Refer to Step 3 of the Smart Checkout Integration)

• Then, the merchant either waits for the Transaction Payment Created webhook, or makes an API call to Retrieve transaction (Refer to Step 4 of the Smart Checkout Integration). In both cases, the merchant verifies the payment was successful, and then the merchant checks whether the customer paid using a card (not a digital wallet transaction) by checking the transactionTypeId response parameter (transactionTypeId can have a number of different values, see the transactionTypeId parameter on our Response codes page for the full list).

• If the customer has indeed paid with a card (not a digital wallet transaction), then the merchant checks whether they have a card token for that card already saved in their backend (in case the customer had used this card in the past and the merchant saved back then the card token). This is done by checking whether the merchant already has saved the cardUniqueReference saved in their backend.

• If the merchant does not have a card token for that card already saved in their backend, then the merchant makes an API call to Create card token and receives the card token.

• Then, the merchant saves the pair (cardUniqueReference, token) in their backend and associates with the specific customer.

• Afterwards, whenever the merchant redirects a customer to Smart Checkout, they pass along the saved card tokens (if any) to the cardTokens request parameter during the API call to Create payment order. The provided card tokens will then be presented to the customer on Smart Checkout to pay with (keep in mind the customer may choose to pay with a new card or with another payment method entirely).

The below sequence diagram summarises the handling card token procedure.

Notes: Check if paid with card (not a digital wallet transaction)

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 (not a digital wallet transaction), 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.

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.

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
}

Get Support

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