Native

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.

Before you start

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

  1. Complete our OAuth 2 token generation procedure.
  2. Create a payment source selecting Redirection/Native Checkout v2 as the integration method.
  3. Make a note of your time-limited access token.

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 within your page using the following script tag:

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

The Native Checkout v2 JS must be included directly in your pages. When testing 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 using JavaScript 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 shown for 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).

Working example in HTML

In the below code, replace [access token] with your own token. For further information on how to generate this, see Step 2: Request access token on our Authentication page.

You need jQuery to integrate Native Checkout v2. Fire up a code editor and paste the code below to see the payment form, or edit it in JS Bin.

<!DOCTYPE html>
<html>

<head>
    <meta charset="utf-8" />
    <title>Native 3DS test</title>
    <script src="https://code.jquery.com/jquery-1.12.4.min.js"
        integrity="sha256-ZosEbRLbNQzLpnKIkEdrPv7lOy9C27hHQ+Xp8a4MxAQ=" crossorigin="anonymous"></script>
    <script type="text/javascript" src="https://demo.vivapayments.com/web/checkout/v2/js"></script>
</head>

<body>

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

        <div class="form-row">
            <label>
                <span>Card Number</span>
                <input type="text" size="20" name="txtCardNumber" autocomplete="off" data-vp="cardnumber"
                    value="4111111111111111" />
            </label>
        </div>
        <div class="form-row">
            <label>
                <span>CVV</span>
                <input type="text" name="txtCVV" size="4" autocomplete="off" data-vp="cvv" value="111" />
            </label>
        </div>
        <div class="form-row">
            <label>
                <span>Expiration (MM/YYYY)</span>
                <input type="text" size="2" name="txtMonth" autocomplete="off" data-vp="month" value="1" />
            </label>
            <span> / </span>
            <input type="text" size="04" name="txtYear" autocomplete="off" data-vp="year" value="2025" />
        </div>
        <button type="button" id="submit" (click)="submit($event)">Submit Payment</button>
    </form>
    <div id="threed-pane" style="height: 450px;width:500px">
    </div>

    <script type="text/javascript">
        $(document).ready(function () {
            const baseUrl = 'https://demo-api.vivapayments.com';
            VivaPayments.cards.setup({
                baseURL: baseUrl,
                authToken: '[access token]',
                cardHolderAuthOptions: {
                    cardHolderAuthPlaceholderId: 'threed-pane',
                    cardHolderAuthInitiated: function () {
                        $('#threed-pane').show();
                    },
                    cardHolderAuthFinished: function () {
                        $('#threed-pane').hide();
                    }
                },
                installmentsHandler: function (response) {
                    if (!response.Error) {
                        if (response.MaxInstallments == 0)
                            return;
                        $('#drpInstallments').show();
                        for (i = 1; i <= response.MaxInstallments; i++) {
                            $('#drpInstallments').append($("<option>").val(i).text(i));
                        }
                    }
                    else {
                        alert(response.Error);
                    }
                }
            });

            $('#submit').on('click', function (evt) {
                evt.preventDefault();
                VivaPayments.cards.requestToken({
                    amount: 3600
                }).done(function (data) {
                    console.log(data);
                    alert(data.chargeToken);
                });
            });

        });
    </script>
</body>
</html>

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

Tip: The below call cannot be made through a browser. Use a backend channel instead.

curl -X POST \
  https://demo-api.vivapayments.com/nativecheckout/v2/transactions \
  -H 'Authorization: Bearer <access token>' \
  -H 'Content-Type: application/json' \
  -d '{
 "amount": 1000,
 "tipAmount": 0,
 "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"
   }
}'

<?php

    $url = 'https://demo-api.vivapayments.com/nativecheckout/v2/transactions';

    $headerArgs = array(
        "Authorization: Bearer ".ACCESS_TOKEN,
        "Content-Type: application/json",
        "Content-Type: text/plain"
    );

    $postArgs = array(
        'amount' => AMOUNT,
        'chargeToken' => CHARGE_TOKEN,
        'installments' => 1,
        'preauth' => false,
        'merchantTrns' => "Merchant transaction reference",
        'customerTrns' => "Description that the customer sees",
        'currencyCode' => CURRENCY_CODE,
        'customer' => array(
            'email' => CUSTOMER_EMAIL,
            'phone' => CUSTOMER_PHONE,
            'fullname' => CUSTOMER_NAME,
            'requestLang' => 'en',
            'countryCode' => 'GB'
        )
    );

    $curl = curl_init();
    curl_setopt($curl, CURLOPT_URL, $url);
    curl_setopt($curl, CURLOPT_RETURNTRANSFER, TRUE);
    curl_setopt($curl, CURLOPT_ENCODING, "");
    curl_setopt($curl, CURLOPT_MAXREDIRS, 10);
    curl_setopt($curl, CURLOPT_TIMEOUT, 0);
    curl_setopt($curl, CURLOPT_FOLLOWLOCATION, TRUE);
    curl_setopt($curl, CURLOPT_HTTP_VERSION, CURL_HTTP_VERSION_1_1);
    curl_setopt($curl, CURLOPT_CUSTOMREQUEST, "POST");
    curl_setopt($curl, CURLOPT_POSTFIELDS, $postArgs);
    curl_setopt($curl, CURLOPT_HTTPHEADER, $headerArgs);

    $result = curl_exec($curl);
    curl_close($curl);


    // to debug the call you can uncomment the following lines to check response from the API
    // and get transactionId if success
    // $result = json_decode($result);
    // print_r($result);

currencyCode is an ISO 4217 code. It should be set to the same currency as your Viva Wallet account. In the example above, the currency is GBP. If registered your account in a Eurozone country, it would be EUR with a code of 978.

requestLang and countryCode should be set appropriately for the customer’s language and country.

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