Native Checkout v2 3DS

Native Checkout v2 (with 3DS support) provides stronger security for both merchants and cardholders. Merchants have the ability to request cardholder authentication from issuers, therefore minimizing fraud exposure. Cardholders with 3DS-enrolled cards can be certain that no transactions will be authorized without their consent. Native Checkout v2 has the added benefit that it integrates directly with your e-commerce website without customers being redirected to a Viva Wallet page for payment.

Prerequisites

  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

Integrating with Native Checkout v2 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 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 js must be included directly in your pages as shown above or it will produce errors. For demo purposes you need to change the baseURL entry in the code to https://demo-api.vivapayments.com.

Step 3: Initialize Native Checkout

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

Example in JavaScript:

VivaPayments.cards.setup({
	authToken: 'your_access_token',
	baseURL: 'https://demo-api.vivapayments.com',
	cardHolderAuthOptions: {
		cardHolderAuthPlaceholderId: 'threed-pane',
		cardHolderAuthInitiated: function() {
			alert('Cardholder authentication started!');
		},
		cardHolderAuthFinished: function() {
			alert('Cardholder authentication has finished');
		}
	}
});

Parameters

ParameterDescriptionImportance
authTokenAccess token issued by the Viva Wallet IdentityServer (OAuth2) authentication.Required
baseURLBase Viva Payments API host URL. Defaults to the live environment. For your first integration with Native Checkout, please use the demo environment.Optional
cardHolderAuthOptionsOptions for initiating a card holder authentication session (3DSecure).Optional
cardHolderAuthOptions.cardHolderAuthPlaceholderIdHTML 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 400 x 400 pixels size.Optional
cardHolderAuthOptions.cardHolderAuthInitiatedFunction that will be called when the cardholder’s authentication page is rendered.Optional
cardHolderAuthOptions.cardHolderAuthFinishedFunction that will be called when the cardholder’s authentication session has completed.Optional
installmentsHandler(maxInstallments)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.Optional

Step 4: Request a one-time charge token

By now, you should have a fully working checkout form, able to create a one-time charge token. This 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.

Example in JavaScript:

VivaPayments.cards.requestToken({
  amount: 1000, // amount is in currency's minor unit of measurement
  installments: 1,
}).done(function (responseData) {
  console.log(`Here is the charge token: ${responseData.chargeToken}`);
}).fail(function (responseData) {
  console.log('Here is the reason it failed: '  + responseData.Error.toString());
});

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, Native checkout will render the issuing bank’s authentication page to an iframe within the HTML defined in cardHolderAuthOptions.cardHolderAuthPlaceholderId. 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 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: Make the actual charge

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

post    /nativecheckout/v2/transactions

Request example
curl -X POST \
  https://demo-api.vivapayments.com/nativecheckout/v2/transactions \
  -H 'Authorization: Bearer <access token>' \
  -H 'Content-Type: application/json' \
  -d '{
  "amount": 1000,
  "preauth": false,
  "chargeToken": "<charge token>",
  "installments": 1,
  "merchantTrns": "Merchant transaction reference",
  "customerTrns": "Description that the customer sees",
  "currencyCode": 826,
  "customer": {
	  "email": "native@vivawallet.com",
	  "phone": "442037347770",
	  "fullname": "John Smith",
	  "requestLang": "en",
	  "countryCode": "GB"
   }
}'

The above call cannot be made through a browser. Use a backend channel instead.

Always pass customer’s details so that the payment is recognizable and the receipt sent will be in your customer’s language.

Response example

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 containing the charge’s transactionId:

{
  "transactionId": "1549bffb-f82d-4f43-9c07-0818cdcdb2c4"
}

Native Checkout v2 API

A custom API to request charge tokens and to perform 3DSecure cardholder authentication. For native applications – using a backend channel – the same functionality can be achieved as with Native Checkout v2 3DS. However, a browser is required for displaying the card issuer’s authentication window to the user.

Create a one-time charge token

Custom integrations must be able to make HTTP calls directly to the Native Checkout v2 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 one-time charge token with your own checkout implementation, simply make an HTTP POST request to the chargetokens endpoint as shown below:

post    /nativecheckout/v2/chargetokens

Request example

The card number 4111111111111111 can be used for demo purposes and will trigger the 3DS functionality during testing. You can use any future date as the card expiration date and any CVV.

curl -X POST \
  https://demo-api.vivapayments.com/nativecheckout/v2/chargetokens \
  -H 'Authorization: Bearer <access token>' \
  -H 'Content-Type: application/json' \
  -d '{
		"amount": 1000,
		"cvc": "111",
    "number": "4111111111111111",
    "holderName": "John Doe",
    "expirationYear": 2030,
    "expirationMonth": 10,
    "sessionRedirectUrl": "<my redirect URL>"
}'

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 3DS-enrolled).

Response example

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

When the redirectToACSForm HTML code is rendered, an authentication session is initiated: the user is redirected to their issuer’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.

Create transaction

After a successful call to chargetokens, you need to create a new transaction.

post    /nativecheckout/v2/transactions

Request example

curl -X POST \
  https://demo-api.vivapayments.com/nativecheckout/v2/transactions \
  -H 'Authorization: Bearer <access token>' \
  -H 'Content-Type: application/json' \
  -d '{
  "amount": 1000,
  "preauth": false,
  "sourceCode": "Default",
  "chargeToken": "<charge token>",
  "installments": 1,
  "merchantTrns": "Merchant transaction reference",
  "customerTrns": "Description that the customer sees",
  "currencyCode": 826,
  "customer": {
	  "email": "native@vivawallet.com",
	  "phone": "442037347770",
	  "fullname": "John Smith",
	  "requestLang": "en",
	  "countryCode": "GB"
   }
}'

Response example

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:

{
  "transactionId": "1549bffb-f82d-4f43-9c07-0818cdcdb2c4"
}

Capture a pre-auth

For cases where a pre-authorization is created instead of a charge, a separate call to the transaction endpoint will be required. Pass the amount of the pre-authorization, or a smaller amount, to create the charge:

get    /nativecheckout/v2/transactions/{preauthTransactionId}

Request example

curl -X POST \
  https://demo-api.vivapayments.com/nativecheckout/v2/transactions/b1a3067c-321b-4ec6-bc9d-1778aef2a19d \
  -H 'Authorization: Bearer <access token>' \
  -H 'Content-Type: application/json' \
  -d '{
    "amount": 300,
}'

Response example

{
  "transactionId": "1549bffb-f82d-4f43-9c07-0818cdcdb2c4"
}

Cancel transaction

This method enables you to:

To avoid an error, ensure you have enabled refunds in your Viva Wallet Account.

delete    /nativecheckout/v2/transactions/{transactionId}

Path parameters

ParameterDescriptionImportance
transactionidThe transaction's unique ID.Required
amountThe amount that will be refunded in the currency's smallest denomination (e.g amount in pounds x 100). For example, if you want to refund a payment of £100.37, you need to pass the value "10037". It should not exceed the amount of the original payment.Required
sourceCodeThe source from which the funds will be withdrawn. Each source is linked to a wallet. If no sourceCode is set then the funds will be withdrawn from the primary wallet.Optional

Request example

curl -X DELETE \
  'https://demo-api.vivapayments.com/nativecheckout/v2/transactions/<transactionId>?amount=10037&sourceCode=3452' \
  -H 'Authorization: Bearer <access token>' \
  -H 'Content-Type: application/json'

Response example

{
"transactionId": "489621e6-deb8-4069-878a-a579711f8bce",
"statusId": "F",
"errorCode": 0,
"errorText": "string",
"timeStamp": "2018-12-24T15:23:38.5157933+02:00"
}

Check for installments

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

get    /nativecheckout/v2/installments

Request example

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

Response example

{
  "maxInstallments": 3
}