Migrating from Native Checkout v1

From 14th September 2019, the PSD2 banking directive came into effect across all of Europe, changing the way payments are made. Secure Customer Authentication (SCA) requires that merchants using Native Checkout v1 integrations with Viva Wallet’s payment processing system migrate to Native Checkout v2 with 3DS support.

Care has been taken so that any changes required to ensure PSD2 compliance are limited to a minimum and allow partial re-use of existing implementations.


You need to have:

  1. Log in to the Viva Wallet banking app, demo or live.
  2. Complete our OAuth 2 token generation procedure.
  3. Create a payment source selecting Redirection/Native Checkout v2 as the integration method.

The demo environment has a base URL of https://demo-api.vivapayments.com and for the live environment it’s https://api.vivapayments.com.

Setup instructions

Follow the steps below to complete the migration process from Native Checkout v1 to v2.

Step 1: Build a custom payment form

Same as before.

Step 2: Add a reference to VivaPayments-2.0.js

Edit your HTML code and replace the existing reference https://www.vivapayments.com/web/checkout/js with https://www.vivapayments.com/web/checkout/v2/js.

Step 3: Action the cardholder authentication

Modify your call to VivaPayments.cards.setup() method to enable the cardholder authentication window (3DS):

	// access token obtained from step 1
	authToken: accessToken,
	cardHolderAuthOptions: {
	    cardHolderAuthPlaceholderId: 'threed-pane',
	    cardHolderAuthInitiated: () => {
	    cardHolderAuthFinished: () => {

cardHolderAuthPlaceholderId should contain the element ID which will hold the cardholder’s authentication window. cardHolderAuthInitiated signifies the start of a new authentication session and cardHolderAuthFinished its conclusion.

cardHolderAuthInitiated is triggered only if the card being used is 3DS enrolled.

Step 4: Request a one-time charge token

Modify call to requestToken by passing amount as a parameter:

   amount: 3600
}).done((response) => {
   console.log(`Here's your charge token ${response.chargeToken}!`);

requestToken uses a Promise to return the chargeToken’s value, so any registered callbacks to cardTokenHandler will be rendered ineffective.

Step 5: Complete the payment

Making the actual charge requires no modifications, so any existing implementations will continue to work as expected.