Native Checkout v2.0 3DS (beta)

Native Checkout v2.0 (with 3DS support) provides stronger security for both merchants and cardholders. Merchants not only have the ability to request cardholder authentication from issuers, therefore minimizing fraud exposure, but can also choose to skip the authentication process when specific business needs may apply. Cardholders with 3DS-enrolled cards can be certain that no transactions will be authorized without their consent.

Before you begin:

  1. Log in to the Viva Wallet banking app, demo or live .
  2. Request bearer token
  3. Accept and store the bearer token
  4. Create a payment source

Integrating with Native Checkout v2.0 now consists of the following steps:

Step 1: Build a custom payment form

The following is an example of a typical payment HTML form that you can easily build with an HTML editor. Decorate your form with data-vp attributes.

<form action="" method="POST" id="payment-form">
	<div class="form-row">
	<label>
		<span>Cardholder Name</span>
		<input type="text" data-vp="cardholder" size="20" name="txtCardHolder" autocomplete="off"/>
	</label>
	</div>

	<div class="form-row">
	<label>
		<span>Card Number</span>
		<input type="text" data-vp="cardnumber" size="20" name="txtCardNumber" autocomplete="off"/>
	</label>
	</div>

	<div class="form-row">
	<label>
		<span>CVV</span>
		<input type="text" data-vp="cvv" name="txtCVV" size="4" autocomplete="off"/>
	</label>
	</div>

	<div class="form-row">
	<label>
		<span>Expiration (MM/YYYY)</span>
		<input type="text" data-vp="month" size="2" name="txtMonth" autocomplete="off"/>
	</label>
	<span> / </span>
	<input type="text" data-vp="year" size="4" name="txtYear" autocomplete="off"/>
	</div>

	<div class="form-row">
		<label>
			<span>Installments</span>
			<select id="js-installments" name="drpInstallments" style="display:none"></select>
		</label>
	</div>

	<input type="button" id="submit" value="Submit Payment" />
</form>

Step 2: Add a reference to VivaPayments.js

Native Checkout v2.0 functionality is provided by the VivaPayments JS library. jQuery Core v1.10.x is required. Add a reference to your page using the following script tag:

<script type="text/javascript" src="https://www.vivapayments.com/web/checkout/v2/js"></script>

Native Checkout v2.0 js must be included directly in your pages as shown above or it will produce errors.

Step 3: Initialize Native Checkout

Initialize Native Checkout v2.0 by calling the setup() method:

VivaPayments.cards.setup({
	authToken: 'your_access_token',
	cardHolderAuthOptions: {
		cardHolderAuthPlaceholderId: 'threed-secure-pane',
		cardHolderAuthInitiated: function() {
			alert('Cardholder authentication started!');
		},
		cardHolderAuthFinished: function() {
			alert('Cardholder authentication has finished');
		}
	}
});

Required parameters

  • authToken – the access token issued by the Viva Wallet identity server.

Optional parameters

  • baseURL – the base Viva Payments API host URL. Defaults to the production environment. For your first integration with Native Checkout, please use the demo environment.
  • cardHolderAuthOptions – options for initiating a card holder authentication session (3DSecure).
  • cardHolderAuthOptions.cardHolderAuthPlaceholderId – the HTML element Id which will act as a placeholder when rendering the cardholder’s authentication page. We recommend you use a popup window as a placeholder of at least 400x400 pixels size.
  • cardHolderAuthOptions.cardHolderAuthInitiated – a function that will be called when the cardholder’s authentication page is rendered.
  • cardHolderAuthOptions.cardHolderAuthFinished – a function that will be called when the cardholder’s authentication session has completed.
  • installmentsHandler(maxInstallments) – a callback function triggered everytime a card supports installments. Indicates the maximum number of installments that a client may select. Note that installments support is limited to credit cards issued by Greek banks only.

Step 4: Request a charge token

By now, you should have a fully working checkout form, able to create charge tokens. A charge token contains all the necessary cardholder information (including the 3D Secure authentication outcome) to complete a payment. To request a charge token, simply call the requestToken method as indicated below:

VivaPayments.cards.requestToken({
  amount: 1321, // amount is in currency's minor unit of measurement
  installments: 10,
  authenticateCardholder: true
}).done(function (responseData) {
  console.log(`Here is the charge token: ${responseData.chargeToken}`);
});

The installments number parameter should be passed manually, since the number of installments selected by the cardholder is not available in the context of Native Checkout.

If the card is 3DS-enrolled then Native checkout will render the issuing bank’s authentication page to an iframe, within the HTML defined in cardHolderAuthOptions.cardHolderAuthPlaceholderId. Use the authenticateCardholder property to disable cardholder authentication process (defaults to true). The authentication process is completely transparent and once concluded, the Promise object created from the call to requestToken will be resolved and provide the charge token as an argument. Client implementations who make calls directly to the Native Checkout v2.0 API will need to render and display the issuing bank’s authentication HTML window themselves using the value from redirectToACSForm field. Furthermore, custom implementations will need to provide a sessionRedirectUrl (see below).

Step 5: Create a payment order

After a successful call to requestToken, a payment order must be created first. Create an order by making a POST request to api/orders as shown on the Create order page.

Step 6: Complete the charge

Now that you have acquired both the charge token and the orderCode from the previous call, a charge, which will transfer the order’s amount, from the card to your wallet can be created:

POST api/transactions

{
  "creditCard": {
      "token": "ctok_DgZ4Ov2NwcQzxExzZ0CleGBWeiA"
    },
    "orderCode": "5205998270072608"
}

If the cardholder’s authentication was successful and all other requirements meet (e.g. account has enough balance etc) then you should receive a response similar to the one below:

{
    "Emv": "910A1FEE5D2612BF809E3030",
    "Amount": 10,
    "StatusId": "F", // Indicates a completed transaction
    "CurrencyCode": "978",
    "TransactionId": "e1b5c876-9da0-4320-8960-23d1e72c8147",
    "ReferenceNumber": 84460,
    "AuthorizationId": "084460",
    "RetrievalReferenceNumber": "912612084460",
    "ErrorCode": 0,
    "ErrorText": null,
    "TimeStamp": "2019-05-06T15:00:07.2821239+03:00",
    "CorrelationId": null,
    "EventId": 0,
    "Success": true
}

3DSecure via the Native Checkout v2.0 API

In the background, Native Checkout uses the Viva Payments Acquiring API to request charge tokens and to perform 3DSecure cardholder authentication. For native applications – not using a browser – the same functionality can be achieved by making API calls directly to the Viva Payments Acquiring API endpoints. A browser though, is required for displaying the card issuer’s authentication window to the user.

Creating a charge token

Custom integrations must be able to make HTTP calls directly to the Native Checkout v2.0 API from the user’s environment. Cardholder details, such as card numbers or the card’s verification value (CVV) must not be transmitted to any endpoint other than those provided by Viva Wallet, in order to ensure that your implementation remains compliant with PCI-DSS standards.

To retrieve a charge token with your own checkout implementation, simply make an HTTP POST request to the chargetoken endpoint as shown below:

POST /nativecheckout/v2/chargetokens

Request parameters

{
    "Cvc": "111",
    "Amount": 1000,
    "Number": "4016000000040000012",
    "Holdername": "John Doe",
    "ExpirationYear": 2030,
    "ExpirationMonth": 10,
    "SessionRedirectUrl": "my_own_url_endpoint"
}

If your request was successful, a JSON response containing the charge token and the HTML code necessary to perform cardholder authentication, is returned (assuming the card is 3D Secure enrolled).

Response parameters

{
    "chargeToken": "ctok_8HilSiRzf-6SMEWiL2uRC3XwVlA",
    "redirectToACSForm": "<html><head></head><body>Hey there! Don't
      forget to render me!</body></html>"
}

When the redirectToACSForm HTML code is rendered, the authenticaton session is initiated; the user is redirected to his/her issuing bank’s page to authenticate before continuing with the transaction.

After completing the authentication session, the user is redirected to the URL defined in the sessionRedirectUrl parameter. The redirection signals the end of the authentication session. The final charge to the user’s card is applied when the charge token is submitted.

Checking for installments

Pass the number as an HTTP header to retrieve the maximum number of installments allowed to a card:

GET /nativecheckout/v2/installments

Request parameters

// Card number as a header
"cardNumber" : "4111111111111111"

Response parameters

{
  "maxInstallments": 3
}