☰

Navigation:

Card Tokenization

Viva offers two separate card tokenization methods: tokens presented to your customers as saved cards on Smart Checkout, and tokens used to trigger direct backend (native) payments such as recurring charges — without the customer or the card being present.

Overview

Card tokenization replaces a customer’s card details with a secure, non-sensitive token that you can store in your backend and reuse for future payments. Viva supports two tokenization methods:

  1. Card tokens for Smart Checkout (merchant-side tokenization): you store card tokens in your backend and pass them along when redirecting a returning customer to Smart Checkout. The customer sees their saved card(s) on the payment page, selects one, enters only their CVV, and completes the payment.

  2. Card tokens for direct backend payments (native tokenization): you generate a card token from any past sale and charge the customer directly from your backend — no card entry, no redirection, and no customer interaction. Ideal for recurring payments, subscriptions, and merchant-initiated transactions.

The merchant-side tokenization is applicable to cards only, and is unavailable for digital wallets such as Apple Pay, Google Pay, Samsung Pay, PayPal, etc.

Method 1: Card tokens for Smart Checkout (merchant-side tokenization)

Smart Checkout offers merchant-side card tokenization, in addition to customer-side card tokenization. You save the card tokens of your customers in your own backend and pass them to Smart Checkout when the customer returns. The saved cards are then displayed on the payment page — the customer simply selects one, enters their CVV, and pays.

The flow is as follows:

  1. Obtain a transaction ID: the customer completes a payment and you receive the transactionId (see Step 3 of the Smart Checkout Integration). A transactionId from an in-person (POS) sale can also be used, allowing you to display on Smart Checkout cards originally used in your physical store.
    1. Verify the payment & check it was paid with a card: via the Transaction Payment Created webhook or the Retrieve transaction API call, confirm the payment was successful and made with a card (not a digital wallet) by checking the transactionTypeId parameter.
    2. Check if the card is already saved: verify that the cardUniqueReference of the payment is not already stored in your backend.
    3. Create the card token: call the Create card token API with the transactionId, then save the (cardUniqueReference, token) pair against the customer.
    4. Present saved cards on Smart Checkout: when the customer returns, pass their token(s) in the cardTokens array of the Create Payment Order API call. The tokens are presented on Smart Checkout as saved cards (the customer may still pay with a new card or another payment method).
Always save the pair (cardUniqueReference, token) not the token alone. Different transactions paid with the same card return different card tokens; the cardUniqueReference is the only reliable way to know whether a card has already been tokenized. It is also your responsibility to obtain the customer’s consent before saving their card token.
You can send up to ten card tokens at once, and you cannot send card tokens if the payment order is for an open amount (disableExactAmount is true). For the full tutorial including request/response examples and the sequence diagram, see Handle Card Tokens.

Method 2: Card tokens for direct backend payments (native tokenization)

Available for ISV Partners and Merchants.

This method allows you to charge a customer’s card directly from your backend, without a payment page and without the customer being present. It is used for recurring payments and merchant-initiated transactions, where the original sale may have happened in any environment — e-commerce or in-person (POS).

  • Merchants need Native credentials, which are shared by Viva.com upon request (contact your sales representative or use our Live Chat)
  • ISV partners perform the same flow on behalf of their merchants using their own ISV credentials
  • Make sure to request the tokenization role to be enabled on your Viva.com account. This feature is subject to approval.

The flow is as follows:

  1. Obtain a transaction ID (e-commerce or in-person): from a Smart Checkout payment, or from a sale on a Viva POS terminal via App to App, Cloud Terminal API, ECR Protocol, or Local Terminal API.
    1. Retrieve the transaction details: to obtain the card’s expiration date, needed later for the charge token. Merchants use the Retrieve Transaction API call; ISV partners use the Retrieve Transaction for ISVs API call.
    2. Create the card token: call the Create card token API with the transactionId. The generated token (ct_...) represents the customer’s tokenized payment method and can be stored for future charges.
    3. Create a charge token: exchange the card token for a one-time charge token (ctok_...) via POST /nativecheckout/v2/chargetokens (merchants, with Native credentials) or POST /nativecheckout/v2/isv/chargetokens?MerchantId=xxx (ISV partners).
    4. Charge the card token: complete the payment via POST /nativecheckout/v2/transactions (merchants) or POST /nativecheckout/v2/isv/transactions?MerchantId=xxx (ISV partners). For each subsequent recurring charge, repeat steps 4–5 with the same stored card token.
    5. Capture a pre-auth (optional): if a pre-authorization was created instead of a charge, capture it via POST /nativecheckout/v2/transactions/{preauthTransactionId} (merchants) or the Payment API for ISVs.
For the endpoint URLs per environment, full request/response examples, and the payments flow diagram, see Card Present Tokenization. It is your responsibility to obtain the customer’s consent for storing their token and charging them on a recurring basis.

Comparison of the two methods

| | Method 1: Smart Checkout card tokens | Method 2: Direct backend payments | | — | — | — | | Customer present at payment? | Yes — selects saved card & enters CVV on Smart Checkout | No — charge is executed entirely from the backend | | Typical use cases | Faster repeat checkout, higher conversion for returning customers | Recurring payments, subscriptions, MIT, omnichannel charging | | Source of original transactionId | Any Viva sale (e-commerce or in-person/POS) | Any Viva sale (e-commerce or in-person/POS) | | How the token is used | Passed in cardTokens array of Create payment order | Exchanged for a one-time charge token (ctok_...), then charged via the native transactions endpoint | | Credentials | Smart Checkout credentials (OAuth2) | Merchants: Native credentials (provided by Viva.com); ISVs: ISV credentials | | Activation | Upon request via sales representative / Live Chat | Tokenization role enabled on your account; merchants must request Native credentials | | Detailed guide | Handle Card Tokens | Card Present Tokenization |

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!