Native Checkout v2 3DS

Native Checkout v2 (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.


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.

Step 3: Initialize Native Checkout

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

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

Required parameters

Optional parameters

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: 1,
  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, 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 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

Sample request
curl -X POST \
  https://demo-api.vivapayments.com/nativecheckout/v2/transactions \
  -H 'Authorization: Bearer eyJhbGciOiJSUzI1NiIsImtpZCI6IkRZLTQxdTNzOWNsLTlTZkFZV3V5TXpxMlg1OCIsInR5cCI6IkpXVCIsIng1dCI6IkRZLTQxdTNzOWNsLTlTZkFZV3V5TXpxMlg1OCJ9.eyJuYmYiOjE1NzM3NDU3MTMsImV4cCI6MTU3Mzc0OTMxMywiaXNzIjoiaHR0cHM6Ly9kZW1vLWFjY291bnRzLnZpdmFwYXltZW50cy5jb20iLCJhdWQiOlsiaHR0cHM6Ly9kZW1vLWFjY291bnRzLnZpdmFwYXltZW50cy5jb20vcmVzb3VyY2VzIiwiY29yZV9hcGkiXSwiY2xpZW50X2lkIjoic2Zrc3U2OWRwMTYxMXA0OWpnMzBrYjM1N2lsZjEwMW5tcHFlcThrNDE1a2szLmFwcHMudml2YXBheW1lbnRzLmNvbSIsInVybjp2aXZhOnBheW1lbnRzOmNsaWVudF9wZXJzb25faWQiOiJBMDYwOEVBRS1EODg1LTRFN0MtODIxNy1FOUE3QkFBMzM5NUIiLCJzY29wZSI6WyJ1cm46dml2YTpwYXltZW50czpjb3JlOmFwaTphY3F1aXJpbmciLCJ1cm46dml2YTpwYXltZW50czpjb3JlOmFwaTphY3F1aXJpbmc6Y2FyZHMiLCJ1cm46dml2YTpwYXltZW50czpjb3JlOmFwaTphY3F1aXJpbmc6Y2FyZHM6dG9rZW5zIiwidXJuOnZpdmE6cGF5bWVudHM6Y29yZTphcGk6bmF0aXZlY2hlY2tvdXR2MiJdfQ.BgpfXnX99zNFrViRCrZ33ZMXakhycz1dCQ3nW9nHMtsPC6suiwm9vIEW8At9QWfYFDcqmfihkNr4UhpjjGQUfKHoCIZwOsRHEFV60IzNtuy9EoZIEc2fqi0q3a52IbfoKZDGp72cx8ak_ijukJjIpasVSHwqvT62shGyHLYoER3MG3_L9V76hIH-2QXLkg8GKsDFS6EbMf3H9hzGahhxt9A6iw08FO25dIhnQoMf079GPP1OUNmJzywXNtgrwuUUgeQ9pqXrN1PBOIqDQ0WAO074KvDx5TsW8-8kmGSr-DDkjDFx5lX5W5_hZ_zvFnL2H6-HWdycAt4vxIdqcpaY2g' \
  -H 'Content-Type: application/json' \
  -d '{
  "amount": 100,
  "preauth": false,
  "sourceCode": "4693",
  "chargeToken": "ctok_jU3RQHBl8hWG8KqMmZWIuEOzohA",
  "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"
}

Using the legacy payment API

For existing integrations using the legacy Payment API, completing a charge comprises two steps:

Step 1: Create payment order

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

Step 2: 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": 1000,
    "StatusId": "F", // Indicates a completed transaction
    "CurrencyCode": "826",
    "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 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.

Create a 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 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 eyJhbGciOiJSUzI1NiIsImtpZCI6IkRZLTQxdTNzOWNsLTlTZkFZV3V5TXpxMlg1OCIsInR5cCI6IkpXVCIsIng1dCI6IkRZLTQxdTNzOWNsLTlTZkFZV3V5TXpxMlg1OCJ9.eyJuYmYiOjE1NzM3NDI2NjYsImV4cCI6MTU3Mzc0NjI2NiwiaXNzIjoiaHR0cHM6Ly9kZW1vLWFjY291bnRzLnZpdmFwYXltZW50cy5jb20iLCJhdWQiOlsiaHR0cHM6Ly9kZW1vLWFjY291bnRzLnZpdmFwYXltZW50cy5jb20vcmVzb3VyY2VzIiwiY29yZV9hcGkiXSwiY2xpZW50X2lkIjoiODl1bzFiZHR4dWI2OGRjbDkwYm5mZGJyMDFjOWZndW11cWF4NTAxbTlpODM1LmFwcHMudml2YXBheW1lbnRzLmNvbSIsInVybjp2aXZhOnBheW1lbnRzOmNsaWVudF9wZXJzb25faWQiOiJGQkYxRTA5MC02NURFLTRDNzUtQjU4MC1EOUQ5QkM0OTRBRDIiLCJzY29wZSI6WyJ1cm46dml2YTpwYXltZW50czpjb3JlOmFwaTphY3F1aXJpbmciLCJ1cm46dml2YTpwYXltZW50czpjb3JlOmFwaTphY3F1aXJpbmc6Y2FyZHMiLCJ1cm46dml2YTpwYXltZW50czpjb3JlOmFwaTphY3F1aXJpbmc6Y2FyZHM6dG9rZW5zIiwidXJuOnZpdmE6cGF5bWVudHM6Y29yZTphcGk6bmF0aXZlY2hlY2tvdXR2MiJdfQ.UdfEi_4-IA0PjuHk2nGUO6uKM_2LBcH6nd_ZFGzwpDQElqvRNEV0i0MufhOtf35aBBj2xQ0ZLIm-cSZFFy-PKlRnZvFxJ1KOwk6aIh0HifPXF1rbQL1JSfE8rTAi-eMObbkEdTIN8WsnUUVDSqR5HVkiCATK78XedNy4zR3MqFChUleoNEMqVTTIp6mIvc97kMih_yTl7Pu9yjip4PSLZagoUrshd_8MG_ifmbe1NL8suBv6jwkW_L9IwB2M46NRxU81593PI05jQNC9e1fPmsOsB1QzsCbjtgR2zC32ufZwCvaKcmzAEWsJ4KX28Az-NZKdZNkivb908vIHSirObw' \
  -H 'Content-Type: application/json' \
  -d '{
    "Cvc": "111",
    "Amount": 1000,
    "Number": "4111111111111111",
    "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 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, 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.

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 eyJhbGciOiJSUzI1NiIsImtpZCI6IkRZLTQxdTNzOWNsLTlTZkFZV3V5TXpxMlg1OCIsInR5cCI6IkpXVCIsIng1dCI6IkRZLTQxdTNzOWNsLTlTZkFZV3V5TXpxMlg1OCJ9.eyJuYmYiOjE1NzM3NDU3MTMsImV4cCI6MTU3Mzc0OTMxMywiaXNzIjoiaHR0cHM6Ly9kZW1vLWFjY291bnRzLnZpdmFwYXltZW50cy5jb20iLCJhdWQiOlsiaHR0cHM6Ly9kZW1vLWFjY291bnRzLnZpdmFwYXltZW50cy5jb20vcmVzb3VyY2VzIiwiY29yZV9hcGkiXSwiY2xpZW50X2lkIjoic2Zrc3U2OWRwMTYxMXA0OWpnMzBrYjM1N2lsZjEwMW5tcHFlcThrNDE1a2szLmFwcHMudml2YXBheW1lbnRzLmNvbSIsInVybjp2aXZhOnBheW1lbnRzOmNsaWVudF9wZXJzb25faWQiOiJBMDYwOEVBRS1EODg1LTRFN0MtODIxNy1FOUE3QkFBMzM5NUIiLCJzY29wZSI6WyJ1cm46dml2YTpwYXltZW50czpjb3JlOmFwaTphY3F1aXJpbmciLCJ1cm46dml2YTpwYXltZW50czpjb3JlOmFwaTphY3F1aXJpbmc6Y2FyZHMiLCJ1cm46dml2YTpwYXltZW50czpjb3JlOmFwaTphY3F1aXJpbmc6Y2FyZHM6dG9rZW5zIiwidXJuOnZpdmE6cGF5bWVudHM6Y29yZTphcGk6bmF0aXZlY2hlY2tvdXR2MiJdfQ.BgpfXnX99zNFrViRCrZ33ZMXakhycz1dCQ3nW9nHMtsPC6suiwm9vIEW8At9QWfYFDcqmfihkNr4UhpjjGQUfKHoCIZwOsRHEFV60IzNtuy9EoZIEc2fqi0q3a52IbfoKZDGp72cx8ak_ijukJjIpasVSHwqvT62shGyHLYoER3MG3_L9V76hIH-2QXLkg8GKsDFS6EbMf3H9hzGahhxt9A6iw08FO25dIhnQoMf079GPP1OUNmJzywXNtgrwuUUgeQ9pqXrN1PBOIqDQ0WAO074KvDx5TsW8-8kmGSr-DDkjDFx5lX5W5_hZ_zvFnL2H6-HWdycAt4vxIdqcpaY2g' \
  -H 'Content-Type: application/json' \
  -d '{
  "amount": 100,
  "preauth": false,
  "sourceCode": "Default",
  "chargeToken": "ctok_7nfilswnqmxYoGiBg_CyFNll3bU",
  "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 eyJhbGciOiJSUzI1NiIsImtpZCI6IkRZLTQxdTNzOWNsLTlTZkFZV3V5TXpxMlg1OCIsInR5cCI6IkpXVCIsIng1dCI6IkRZLTQxdTNzOWNsLTlTZkFZV3V5TXpxMlg1OCJ9.eyJuYmYiOjE1NzM3NDU3MTMsImV4cCI6MTU3Mzc0OTMxMywiaXNzIjoiaHR0cHM6Ly9kZW1vLWFjY291bnRzLnZpdmFwYXltZW50cy5jb20iLCJhdWQiOlsiaHR0cHM6Ly9kZW1vLWFjY291bnRzLnZpdmFwYXltZW50cy5jb20vcmVzb3VyY2VzIiwiY29yZV9hcGkiXSwiY2xpZW50X2lkIjoic2Zrc3U2OWRwMTYxMXA0OWpnMzBrYjM1N2lsZjEwMW5tcHFlcThrNDE1a2szLmFwcHMudml2YXBheW1lbnRzLmNvbSIsInVybjp2aXZhOnBheW1lbnRzOmNsaWVudF9wZXJzb25faWQiOiJBMDYwOEVBRS1EODg1LTRFN0MtODIxNy1FOUE3QkFBMzM5NUIiLCJzY29wZSI6WyJ1cm46dml2YTpwYXltZW50czpjb3JlOmFwaTphY3F1aXJpbmciLCJ1cm46dml2YTpwYXltZW50czpjb3JlOmFwaTphY3F1aXJpbmc6Y2FyZHMiLCJ1cm46dml2YTpwYXltZW50czpjb3JlOmFwaTphY3F1aXJpbmc6Y2FyZHM6dG9rZW5zIiwidXJuOnZpdmE6cGF5bWVudHM6Y29yZTphcGk6bmF0aXZlY2hlY2tvdXR2MiJdfQ.BgpfXnX99zNFrViRCrZ33ZMXakhycz1dCQ3nW9nHMtsPC6suiwm9vIEW8At9QWfYFDcqmfihkNr4UhpjjGQUfKHoCIZwOsRHEFV60IzNtuy9EoZIEc2fqi0q3a52IbfoKZDGp72cx8ak_ijukJjIpasVSHwqvT62shGyHLYoER3MG3_L9V76hIH-2QXLkg8GKsDFS6EbMf3H9hzGahhxt9A6iw08FO25dIhnQoMf079GPP1OUNmJzywXNtgrwuUUgeQ9pqXrN1PBOIqDQ0WAO074KvDx5TsW8-8kmGSr-DDkjDFx5lX5W5_hZ_zvFnL2H6-HWdycAt4vxIdqcpaY2g' \
  -H 'Content-Type: application/json' \
  -d '{
    "amount": 1000,
}'
Response example
{
  "transactionId": "1549bffb-f82d-4f43-9c07-0818cdcdb2c4"
}

Check 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
}