Simple Checkout

Simple Checkout is a simple way 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 complete:

Simple Checkout

Once the payment is made, they can close the dialog box and return to your website.

Our aim is to provide users with a streamlined, mobile-ready payment experience that is constantly improving. Simple Checkout allows quick integration in as little as a single line of client-side code. As new features are released, we’ll automatically roll them out to your existing integration, so that you’ll always be using our latest technology without needing to change a thing.

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.

Features

This checkout solution uses an iframe which may cause problems in some browsers, including the one within the Facebook mobile app. You should test first using the sandbox. If you run into any issues, use Redirect Checkout instead.

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

Setup instructions

Follow the steps below to complete setup of Simple Checkout.

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>
    <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="1000"
          data-vp-description="My product">
        </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>

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

Two payment methods are available:

Depending on the payment method selected and whether the merchant is enrolled in the Viva Payments Cardholder Authentication Service (3DSecure), the user may be redirected to their bank’s page to authenticate (e.g. enter a password or SMS code).

After selecting the payment method and filling in the necessary fields, paymentForm is submitted to the URL defined in the action attribute along with vivaWalletToken, a hidden <input> field.

The code above does not create charges – 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

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

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:

{
  "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:

  • Update your data-vp-publickey attribute with your production key.
  • Find your production Merchant ID and API Key and replace the demo versions (marked as your_merchant_id and your_api_key in the above code sample).