Smart Checkout Integration

A guide to the integration process for Smart Checkout.

Before you start

  1. Create an account with Viva Wallet, if you do not already have one:
  2. Log in to your demo account or live account
  3. Create a payment source in order to provide details such as your domain name for your online store, your company logo, your success (thank you) page, and so on.
    Make a note of the source code, i.e. the 4-digit code of the payment source, you just created, as you will need it later on. It is important to provide your company logo, as this will be presented to the customer on Smart Checkout, and it will help the customer understand who this payment is for
  4. Determine which payment methods you want to offer to your customers. Some of these payment methods are automatically enabled for you by us (e.g. Apple Pay), other payment methods can only be enabled by yourself (e.g. PayPal), for others you need to get in touch with us to enable them for you after a further review of your business

Integration flow diagram

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

sequenceDiagram participant Merchant frontend participant Merchant backend participant Viva Wallet API Merchant backend->>Viva Wallet API:Create the payment order Viva Wallet API-->>Merchant backend:Payment order created Merchant backend-->>Merchant frontend:Payment order Merchant frontend->>Viva Wallet API:Redirect customer to Smart Checkout to pay the payment order Viva Wallet API-->>Merchant frontend:Confirm the payment of the payment order Merchant backend->>Merchant backend:Verify payment

Integration flow instructions

The overall integration process is as follows:

  1. Create the payment order
  2. Redirect the customer to Smart Checkout to pay the payment order
  3. Confirm the payment of the payment order
  4. Verify payment

Step 1: Create the payment order

You need to create a payment order every time you want to tell Viva Wallet that you require a certain amount of money from one of your customers. Think of it as a utility bill. You give Viva Wallet an order to issue a bill on your behalf. The bill is then sent to your customer and they have to pay a specific amount. Each Payment Order has a unique 12-digit ID also referred to as the order code.

Keep in mind that you need to define the sourceCode parameter when creating the payment order, i.e. the 4-digit code of the payment source you have created (please refer to the Before you start section above). The payment sources you have created can be found in your Viva Wallet banking app under the payment sources for your website / app.

Find out more about the Create payment order API call and its parameters.

You can create a payment order by using the below method through a backend channel.

Request example

Make the below call through a backend channel.

Note that you should use OAuth2 method for the authentication.

post    /checkout/v2/orders

Run in Postman

Environment URL
Production https://api.vivapayments.com/checkout/v2/orders
Demo https://demo-api.vivapayments.com/checkout/v2/orders
curl '[Environment URL]'
-H 'Authorization: Bearer [access token]'
-H 'Content-Type: application/json'
-d '{
    "amount": 1000,
    "customerTrns": "Short description of purchased items/services to display to your customer",
    "customer":
    {
        "email": "johdoe@vivawallet.com",
        "fullName": "John Doe",
        "phone": "+30999999999",
        "countryCode": "GB",
        "requestLang": "en-GB"
    },
    "paymentTimeout": 300,
    "preauth": false,
    "allowRecurring": false,
    "maxInstallments": 12,
    "paymentNotification": true,
    "tipAmount": 100,
    "disableExactAmount": false,
    "disableCash": true,
    "disableWallet": true,
    "sourceCode": "1234",
    "merchantTrns": "Short description of items/services purchased by customer",
    "tags":
    [
        "tags for grouping and filtering the transactions",
        "this tag can be searched on VivaWallet sales dashboard",
        "Sample tag 1",
        "Sample tag 2",
        "Another string"
    ],
    "cardTokens":
    [
        "ct_5d0a4e3a7e04469f82da228ca98fd661"
    ]
}'
<?php
$curl = curl_init();
curl_setopt_array($curl, array(
  CURLOPT_URL => '[Environment URL]',
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => '',
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 0,
  CURLOPT_FOLLOWLOCATION => true,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => 'POST',
  CURLOPT_POSTFIELDS =>'{
 "amount": 1,
 "customerTrns": "string",
 "customer": {"email": "","fullName": "","phone": "","countryCode": "","requestLang": ""},
 "paymentTimeout": 0,
 "preauth": true,
 "allowRecurring": true,
 "maxInstallments": 0,
 "paymentNotification": true,
 "tipAmount": 1,
 "disableExactAmount": true,
 "disableCash": false,
 "disableWallet": false,
 "sourceCode": "Default",
 "merchantTrns": "string",
 "tags": ["string"],
 "cardTokens": ["ct_5d0a4e3a7e04469f82da228ca98fd661"]
}',
  CURLOPT_HTTPHEADER => array(
    'Authorization: Bearer [access token]',
    'Content-Type: application/json'
  ),
));
$response = curl_exec($curl);
curl_close($curl);
echo $response;
Response example

If authentication is successful and the parameter values provided for the creation of the payment order are valid, an order code is returned in the response.

{
    "orderCode": 1272214778972604
}
Best practices

Although the fullName, email, customerTrns, requestLang and countryCode parameters are optional, it is highly recommended to provide them as they will encourage high conversion rates:

  • fullName and email are requested by the customer in order to proceed with the payment, if not specified during the creation of the payment order (asking the customer to provide information that he has already provided creates frustration and may cause them to abandon the checkout process)
  • customerTrns provides information about what the customer is being asked to pay for (it is good practice to provide a reminder description of what they are paying for). Please note: you can also copy and paste emojis into this field if desired 😃
  • requestLang indicates the language that the payment page will appear in (make sure the customer views the payment page in their language, which is especially important for online stores with international customers)
  • countryCode indicates the country of the customer, which affects the payment methods that will be offered to the customer; keep in mind that certain payment methods are available only to customers that live in specific countries (make sure the customer is offered payment methods that they are familiar with and tend to use)

Step 2: Redirect the customer to Smart Checkout to pay the payment order

Redirect the customer to the Viva Wallet Smart Checkout via a browser using the below URI format. Replace the OrderCode value with the one generated in the previous step.

You should store and pass OrderCodes in string format, rather than integer format, in order to avoid exceeding JavaScript’s MAX_SAFE_INTEGER value of 9,007,199,254,740,991. Otherwise, you may run into ‘OrderCode not found’ and similar errors

Environment URL
Production https://www.vivapayments.com/web/checkout?ref={OrderCode}
Demo https://demo.vivapayments.com/web/checkout?ref={OrderCode}

We strongly recommend that you perform a proper redirect, and you do not use an iframe. Using an iframe will disable certain features, it will also result in a poor user experience, and thus overall reduce significantly your conversion rates. Customers are accustomed to being redirected to a payment page to conclude their purchase online.

Features that will not be available by using an iframe: paying with Apple Pay, saving cards or using saved cards, paying with certain payment methods (that require a redirection of their own such as Klarna, BLIK, EPS, P24, PayU & IRIS), remembering customer preferences (previously used payment methods, previously selected language, etc), dynamically showing payment methods most likely to convert, paying with Viva Wallet, and more.

The customer experience will also be poor due to the risk of: poor screen layouts, content spilling over several screens and content being inaccessible due to poor positioning. Note also that some browsers do not properly support iframes, including the one within the Facebook mobile app, so your customers may be unable to even view your payment page.

Below is the Smart Checkout form where the customer can enter their payment details and complete the payment:

If your payment order contains either allowRecurring = true or preauth = true, only payment methods which support these features will be displayed to your customers

Smart Checkout

To simulate a successful payment in the demo environment, use one of our test cards to mimic a payment of 30¢/30p or more.

You have the option to specify your desired brand color to apply on Smart Checkout. This means that the overall styling (look & feel) of Smart Checkout will be adjusted to make use of your own brand color, rather than the default color.

You simply append the query parameter color to the URL as shown here:

Environment URL
Production https://www.vivapayments.com/web/checkout?ref={OrderCode}&color={ColorCode}
Demo https://demo.vivapayments.com/web/checkout?ref={OrderCode}&color={ColorCode}

The color code can be any Hex color code but without the ## character. So for example, blue is 0000ff, gold is ffd700, brown is a52a2a and so on. Once you decide which brand color you want to use, please carry out some testing to ensure the brand color looks correct on Smart Checkout (the use of white - ffffff - would not look good, for example)

If the color parameter value is null, invalid or missing, then the default value (06abc1) will apply

Example

You may find below a few examples of different color codes being used:

Blue (hex code 0000ff) Gold (hex code ffd700) Brown (hex code a52a2a)
Blue Colored Smart Checkout Gold Colored Smart Checkout Brown Colored Smart Checkout
Optional: specify pre-selected payment method

You have the option to specify your desired preselected payment method. This means that you can specify the payment method that will be already selected for your customer (in essence your preferred payment method). The customer will be presented a particular method to pay with, while still having the option to pay with any other payment method.

You simply append the query parameter paymentMethod to the URL as shown here:

Environment URL
Production https://www.vivapayments.com/web/checkout?ref={OrderCode}&color={ColorCode}&paymentMethod={MethodId}
Demo https://demo.vivapayments.com/web/checkout?ref={OrderCode}&color={ColorCode}&paymentMethod={MethodId}

You may find below all the possible values for the paymentMethod parameter:

MethodId Payment Method
0 (default) Credit Card
2 SEPA Direct Debit
3 Cash (Viva Spot)
4 e-banking (ΔΙΑΣ)
8 Viva Wallet
10 iDEAL
11 P24
12 BLIK
13 PayU
14 MULTIBANCO
15 giropay
16 Sofort
17 EPS
18 WeChat Pay
19 BitPay
23 PayPal
24 Trustly
26 Klarna
27 Bancontact QR
28 Payconiq
29 IRIS
30 Pay By Bank
34 tbi bank
35 Pay on Delivery
Example

You may find below an example with PayPal as the preselected payment method. The customer will be redirected to Smart Checkout which will present PayPal as preselected payment method, while still being able to pay with any other payment method he desires.

Environment URL
Production https://www.vivapayments.com/web/checkout?ref={OrderCode}&paymentMethod=23
Demo https://demo.vivapayments.com/web/checkout?ref={OrderCode}&paymentMethod=23

If the paymentMethod parameter value is null, invalid or missing, then the default value (Credit Card) will apply

Smart Checkout with PayPal preselected

Step 3: Confirm the payment of the payment order

After the customer makes the payment on Smart Checkout, the customer is redirected back to your website. If the payment has been successful or is pending, the customer is redirected to the Success URL, otherwise (i.e. if the payment has been unsuccessful) they are redirected to your Failure URL.

Please note that a payment may have a status of pending in case the customer used an asynchronous payment method (such as alternative payment methods, which are asynchronous in principle), meaning that it may take up to several days to confirm whether the payment has been successful. You need to use webhooks so that we inform you when the payment is confirmed as successful or failed.

Keep in mind that the Success URL and Failure URL are both specified within the payment source you have created (please refer to the Before you start section above); these can be found in your Viva Wallet banking app under the payment sources for your website / app.

The redirection uses the HTTP GET method and appends the following query string parameters to the redirect Success / Failure URL:

Step 4: Verify payment

We strongly recommend that you verify the status of the payment explicitly, and not depend only on whether your success or failure URL is called, especially if you offer asynchronous payment methods (such as alternative payment methods, which are asynchronous in principle), but also due to several various other reasons (network connection issues, malicious hijacking attempts, etc).

Our recommended method of verification is to use the ‘Transaction Payment Created’ webhook. The use of a webhook is mandatory if you offer asynchronous payment methods (such as alternative payment methods that are asynchronous in principle).

Alternatively, you can make an API call to ‘Retrieve transactions’ in order to verify the status of a specific payment. Both methods are outlined below.

This method is mandatory if you offer alternative payment methods (such as alternative payment methods that are asynchronous in principle). Note that asynchronous payment methods may take up to several days to confirm whether the payment has been successful, although in the typical case the payment is confirmed almost immediately. Until the payment is confirmed as successful or failed, the payment will be indicated as pending. You need to use webhooks so that we inform you when the payment is confirmed as successful or failed.

Please see our ‘Transaction Payment Created’ documentation for further details.

API Call (Retrieve Transaction) - alternative

You can make a call to Retrieve transactions in order to verify the status of a specific payment.

Please see our ‘Receive Transaction’ API documentation for further details.

get    /checkout/v2/transactions/{transactionId}

Run in Postman

Request example

Environment URL
Production https://api.vivapayments.com/checkout/v2/transactions/{transactionId}
Demo https://demo-api.vivapayments.com/checkout/v2/transactions/{transactionId}
curl '[Environment URL]'
-H 'Authorization: Bearer [access token]' \
-H 'Content-Type: application/json' \

<?php
$curl = curl_init();
curl_setopt_array($curl, array(
  CURLOPT_URL => '[Environment URL]',
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => '',
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 0,
  CURLOPT_FOLLOWLOCATION => true,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => 'GET',
  CURLOPT_HTTPHEADER => array(
    'Authorization: Bearer [access token]'
  ),
));
$response = curl_exec($curl);
curl_close($curl);
echo $response;

Response example

{
    "email": "someone@example.com",
    "amount": 30.00,
    "orderCode": 6962462482972601,
    "statusId": "F",
    "fullName": "George Seferis",
    "insDate": "2021-12-06T14:32:10.32+02:00",
    "cardNumber": "523929XXXXXX0168",
    "currencyCode": "978",
    "customerTrns": "Short description of items/services purchased to display to your customer",
    "merchantTrns": "Short description of items/services purchased by customer",
    "cardUniqueReference": "9521B4209B611B11E080964E09640F4EB3C3AA18",
    "transactionTypeId": 5,
    "recurringSupport": false,
    "totalInstallments": 0,
    "cardCountryCode": null,
    "cardIssuingBank": null,
    "currentInstallment": 0,
    "cardTypeId": 1
}

Integrate a mobile app with Smart Checkout

In case you need to integrate a mobile app with Smart Checkout, the above steps are still applicable but you need to adopt a slightly adjusted integration approach. Keep in mind that you still need to create a payment order, and redirect the customer to Smart Checkout, and then handle the redirect back to you and verify the payment. Details on how to integrate a mobile app with Smart Checkout can be found here.

Go-Live

Pre-Go-Live Checklist

Please refer to the following checklist to ensure you have completed all necessary steps before Go-Live.

Go-Live Steps

Please use the following checklist to ensure you complete all necessary steps to Go-Live.

  1. Register for a live Viva Wallet account
  2. Set up a payment source in your production account
  3. Authenticate using production credentials
    • See OAuth2 authentication method for further details

  4. Update base URLs to live
    • Replace demo.vivapayments.com with www.vivapayments.com in your code

  5. Final live testing with a real payment card
    • Make a test purchase for a small amount using a supported card. Afterwards, you can cancel the transaction from your Viva Wallet account

Additional use cases

Recurring payments

If the payment is initiated by you (the merchant), without the involvement of the customer, you should use recurring payments, rather than one-off payments.

Pre-authorizations

If the transfer of funds is to be initiated later, but you now want to ensure the customer has the required funds and in fact reserve these funds, you should use a pre-authorization, rather than a direct charge.

Further Information

Check out the following tutorials for more details about some of the above topics:

Get Support

If you would like to integrate with Viva Wallet, or if you have any queries about our products and solutions, please see our Get Support page to see how we can help!