Simple Checkout

Simple Checkout is a basic method to start using Viva Wallet for payments on your website. A payment button on your page opens a popup dialog box for your customers to supply their payment details.

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:(1) Load jQuery and VivaPayments.js Merchant app->>Merchant app:(2) Merchant app:Load Simple Checkout form Merchant app->>VivaPayments.js:(3) Payment data (button click) VivaPayments.js-->>Merchant app:(4) vivaWalletToken Note right of Merchant backend:/checkout Merchant app->>Merchant backend:(5) POST form (form submission) Merchant backend->>Viva Wallet API:(6) POST vivaWalletToken to /api/transactions Note right of Merchant backend:vivaWalletToken
passed as payment
token Viva Wallet API-->>Merchant app:(7) 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. Log in to Viva Wallet, demo or live , and select the required account.
  2. Go to Settings > API Access and note your public key from the Simple Checkout section at the bottom of the page.
  3. Create a payment source selecting Native/Pay with Viva Wallet Checkout as the integration method.

Setup instructions

To use this facility we need to give you access to our Simple Checkout API. Simply raise an issue on our public GitHub to this effect. We will ask you for a bit more information about your company before granting you the necessary privileges.

Step 1: Display the 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="F3nrgfiPzz/nTH/O/LFu7q8iaBAf9VStbVfypQde9d4="
          data-vp-baseurl="https://demo.vivapayments.com"
          data-vp-lang="en"
          data-vp-amount="100"
          data-vp-sourcecode="Default"
          data-vp-description="My product"
          data-vp-disablewallet="true"
          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.

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 Your SourceCode. 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 Optional value is set, 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 the charge token submitted to your server enables you to proceed with applying the actual transaction to your customer’s credit card. This can be achieved 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 How to authenticate using basic auth.

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

<?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;
}

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 met (e.g. account has enough balance etc.) then you should receive a response containing the charge’s transactionId:

{
  "Emv": null,
  "Amount": 10,
  "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.

Step 3: 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: