Simple Checkout

Simple Checkout is a straightforward method to start using Viva Wallet to accept payments on your website.

Through our Simple Checkout, you include a payment button on your page, which your customers click to open a popup dialog box to provide their payment details, and then you proceed with the payment.

Simple Checkout has 3DS support which provides stronger security for both merchants and cardholders. Merchants have the ability to request cardholder authentication from issuers, therefore minimising fraud exposure. Cardholders with 3DS-enrolled cards can be certain that no transactions will be authorised without their consent.

Simple Checkout has the added benefit that it integrates directly with your e-commerce website without customers being redirected to a Viva Wallet page for payment.

Features

Process flow diagram

The below sequence diagram outlines the Simple Checkout integration procedure from beginning to end.

sequenceDiagram participant Merchant app participant VivaPayments.js participant Merchant backend participant Viva Wallet API Merchant app->>Merchant app:Load jQuery and VivaPayments.js Merchant app->>Merchant app:Merchant app:Load Simple Checkout form Merchant app->>VivaPayments.js:Payment data (button click) VivaPayments.js-->>Merchant app:vivaWalletToken Note right of Merchant backend:/checkout Merchant app->>Merchant backend:POST form (form submission) Merchant backend->>Viva Wallet API:POST vivaWalletToken to /api/transactions Note right of Merchant backend:vivaWalletToken
passed as payment
token Viva Wallet API-->>Merchant app:TransactionId and status

Before you start

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

  1. Register for an account with Viva Wallet.
  2. Log in to Viva Wallet, demo or live , and select the required account.
  3. Go to Settings > API Access and note your public key from the Simple Checkout section at the bottom of the page.
  4. Create a payment source selecting Native/Pay with Viva Wallet Checkout as the integration method.

Integration flow instructions

The overall integration process is as follows:

  1. Display the payment button on your page, which your customers click to open a popup dialog box to provide their payment details, which in turn Viva Wallet uses to generate a token.
  2. Make the actual payment using the token provided by Viva Wallet, through a backend channel.

Step 1: Display the payment button

You need jQuery to integrate Simple Checkout. Fire up a code editor and paste the code below to see the button rendered, or edit it in JS Bin .

HTML

Replace the data-vp-publickey value shown in the HTML below with your own public key from the Viva Wallet banking app.

<html>
    <head>
        <title>Simple Checkout</title>
    </head>
    <body>
      <form id="myform" action="/checkout" method="post">
        <button type="button"
          data-vp-publickey="LtxtCxG+9ibQOVDq3mQ2kZwXuatB9Bogs6jNFaFch20="
          data-vp-baseurl="https://demo.vivapayments.com"
          data-vp-lang="en"
          data-vp-amount="100"
          data-vp-sourcecode="[4-digit code of your payment source]"
          data-vp-description="My product"
          data-vp-disablewallet="false"
          data-vp-expandcard="true">
        </button>
      </form>

      <script src="https://code.jquery.com/jquery-1.11.2.min.js"></script>
      <script src="https://demo.vivapayments.com/web/checkout/js"></script>
    </body>
</html>

A button is displayed. When the user clicks the button, the checkout form is displayed within the browser without redirection:

Simple checkout

Two payment methods are available:

After selecting the payment method (usually Pay with card) and filling in the necessary fields using one of the test cards provided, paymentForm is submitted to the URL defined in the action attribute along with vivaWalletToken, a hidden <input> field.

Simple Checkout does not create a transaction, it only creates a one-time charge token. This is an encrypted string containing data related to the payment and can only be decrypted by us when the actual transaction is applied to the user’s credit card. vivaWalletToken is a charge token, too.

The above code sample references the demo environment. To use on production, replace instances of demo.vivapayments.com with www.vivapayments.com and use the public key from your live Viva Wallet account.

Received parameters

vivaWalletToken will be submitted to your form’s action endpoint along with any other <input> fields included in the form.

Parameter Description
vivaWalletToken The charge token that will be used to charge your customer.

Configuration options

Option Description Importance
data-vp-publickey Your (demo or live) public API key, available in your merchant profile. Required
data-vp-amount The amount you wish to charge. The amount is entered in the currency's minor unit of measurement (e.g. cents instead of euros. To charge your customer 20 euros, you would enter the value '2000'). Required
data-vp-description A description of the payment, visible to your customer. Recommended
data-vp-merchantref A reference ID that will later help you easily identify the payment (e.g. a unique order code generated by your system. Recommended
data-vp-lang The interface language. Supported languages:
'en' – English, 'fr' – French, 'nl' – Dutch, 'ro' – Romanian, 'el' – Greek.
Recommended
data-vp-background-color Sets button’s background colour. Default value: #030408. Recommended
data-vp-color Sets button’s text colour. Default value: #fff. Recommended
data-vp-hover-background-color Sets button’s background colour on mouse over. Default value: #1a2242. Recommended
data-vp-hover-color Sets button’s text colour on mouse over. Default value: #fff. Recommended
data-vp-border-radius Sets button’s roundness. Default value: 10px. Recommended
data-vp-text Sets button’s text. Default value: Pay (when data-vp-lang="en"). Recommended
data-vp-sourcecode 4-digit code of your payment source. If omitted, 'Default' SourceCode is used. For Sources with logos attached to them, checkout will render the logo in the header area. See also Create a payment source. Optional
data-vp-customersurname Card holder's surname. Fills in the related form field. Optional
data-vp-customerfirstname Card holder's first name. Fills in the related form field. Optional
data-vp-customeremail Card holder's e-mail address. Fills in the related form field. Optional
data-vp-baseurl The target environment (demo / production). Use https://demo.vivapayments.com for development. If not provided, production environment is assumed. Optional
data-vp-disablewallet (true/false) Disables Wallet payment method. Optional
data-vp-expandcard (true/false) Expands credit card payment method area upon display. Optional
data-vp-preauth (true/false) Reserve money from a credit card. Capture it later on and within a merchant specific timeframe (usually 20 days). Optional
data-vp-walletonly (true/false) Disable credit card payment. Optional

Step 2: Make the charge

Having completed step 1 above, and having received the vivaWalletToken (charge token), you can now proceed with making the actual payment, and charge your customer. This can be done with a single call:

post    /api/transactions

Request example

Make the below call through a backend channel. Replace the authorization token with your own, generated as described under Basic auth.

curl -X POST \
  https://demo.vivapayments.com/api/transactions \
  -H 'Authorization: Basic ZmJmMWUwOTAtNjVkZS00Yzc1LWI1ODAtZDlkOWJjNDk0YWQyOldEdi1WKw==' \
  -H 'Content-Type: application/json' \
  -d '{
  "PaymentToken": "[vivaWalletToken]"
}'

<?php
    // retrieve vivaWalletToken from POST vars
    $vivaWalletToken = $_POST["vivaWalletToken"];

    // check if the token is defined
    if(!isset($vivaWalletToken)){
        echo ("viva wallet token is not defined");
        //and catch errors if it is not...
        return;
    }

    // define vars
    $merchantId = 'YOUR_MERCHANT_ID';
    $apiKey = 'YOUR_API_KEY';

    $url = 'https://demo.vivapayments.com/api/transactions';
    $postArgs = 'PaymentToken='.urlencode($vivaWalletToken);

    $curl = curl_init();
    curl_setopt($curl, CURLOPT_POST, true);
    curl_setopt($curl, CURLOPT_POSTFIELDS, $postArgs);
    curl_setopt($curl, CURLOPT_USERPWD, $merchantId . ":" . $apiKey);
    curl_setopt($curl, CURLOPT_URL, $url);
    curl_setopt($curl, CURLOPT_RETURNTRANSFER, true);
    $result = curl_exec($curl);
    curl_close($curl);

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

public class TransactionResult
{
    public int ErrorCode { get; set; }
    public decimal Amount { get; set; }
    public string ErrorText { get; set; }
    public Guid TransactionId { get; set; }
}

public async Task<TransactionResult> ChargeAsync(string vivaWalletToken)
{
    var cl = new RestClient("https://demo.vivapayments.com/api/") {
        Authenticator = new HttpBasicAuthenticator("your_merchant_id", "your_api_key")
    };
    var request = new RestRequest("transactions", Method.POST) {
        RequestFormat = DataFormat.Json
    };

    request.AddParameter("PaymentToken", vivaWalletToken);

    var response = await cl.ExecuteTaskAsync<TransactionResult>(request);

    return response.ResponseStatus == ResponseStatus.Completed &&
        response.StatusCode == System.Net.HttpStatusCode.OK ? response.Data : null;
}

Response example

If the cardholder’s authentication was successful and all other requirements met (e.g. account has enough balance etc.) then you should receive a response containing the charge’s transactionId:

{
  "Emv": null,
  "Amount": 100,
  "StatusId": "F",
  "CurrencyCode": "978",
  "TransactionId": "9d0f76c6-d614-49d0-b62d-956dbaa7de14",
  "ReferenceNumber": 127124,
  "AuthorizationId": "127124",
  "RetrievalReferenceNumber": "005814127124",
  "ThreeDSecureStatusId": 1,
  "ErrorCode": 0,
  "ErrorText": null,
  "TimeStamp": "2020-02-27T16:15:25.3665106+02:00",
  "CorrelationId": null,
  "EventId": 0,
  "Success": true
}

That’s it! If the call above succeeds, your customer was successfully charged. You can retrieve information about the transaction by making an HTTP call to the GetTransactions API endpoint using the TransactionId received from the previous HTTP call or with the use of webhooks.

Conclusion: Switch from demo to live (production)

After you’ve tested and are happy with your integration, don’t forget to replace demo.vivapayments.com with www.vivapayments.com in your button code and JavaScript includes.

You’ll also need to: