Smart Checkout

Smart Checkout is a turn-key solution for merchants to integrate with Viva Wallet to accept payments online for your online store. It involves minimal effort on your side and offers the widest variety of payment options and overall features.

Smart Checkout is a hosted payment page, so when your customer is ready to make the payment, you direct them to a payment page hosted by Viva Wallet, where the customer provides their payment details and makes the payment. When they complete the payment, they are redirected back to a success (thank you) page of your choice.

For hints and tips on Smart Checkout usage, see How to use Smart Checkout.

For information about the user functionality of Smart Checkout see the Functional overview page.

On this page:

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 frontend->>Merchant frontend: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.

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

post    /checkout/v2/orders

Run in Postman

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.

Request example (sandbox/demo)

Make the below call through a backend channel.

Note that you should use OAuth2 method for the authentication.

curl --location --request POST 'https://demo-api.vivapayments.com/checkout/v2/orders' \
--header 'Authorization: Bearer eyJhbGciOiJSUzI1NiIsImtpZCI6IjBEOEZCOEQ2RURFQ0Y1Qzk3RUY1MjdDMDYxNkJCMjMzM0FCNjVGOUZSUzI1NiIsInR5cCI6ImF0K2p3dCIsIng1dCI6IkRZLTQxdTNzOWNsLTlTZkFZV3V5TXpxMlg1OCJ9.eyJuYmYiOjE2MzkwNDIwMjcsImV4cCI6MTYzOTA0NTYyNywiaXNzI' \
--header 'Content-Type: application/json' \
--data-raw '{
    "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",
        "Anoteher string"
    ]
}'
<?php
$curl = curl_init();
curl_setopt_array($curl, array(
  CURLOPT_URL => 'https://demo-api.vivapayments.com/checkout/v2/orders',
  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"]
}',
  CURLOPT_HTTPHEADER => array(
    'Authorization: Bearer eyJhbGciOiJSUzI1NiIsImtpZCI6IjBEOEZCOEQ2RURFQ0Y1Qzk3RUY1MjdDMDYxNkJCMjMzM0FCNjVGOUZSUzI1NiIsInR5cCI6ImF0K2p3dCIsIng1dCI6IkRZLTQxdTNzOWNsLTlTZkFZV3V5TXpxMlg1OCJ9.eyJuYmYiOjE2MzkwNDIwMjcsImV4cCI6MTYzOTA0NTYyNywiaXNzIjoiaHR0cHM6Ly',
    'Content-Type: application/json'
  ),
));
$response = curl_exec($curl);
curl_close($curl);
echo $response;

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:

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
}

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.

https://demo.vivapayments.com/web2?ref={OrderCode}

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

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.

Optional feature: specify brand color

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:

https://demo.vivapayments.com/web2?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 make a few tests, making sure that the brand color looks nice on Smart Checkout, e.g. the use of white ffffff will not look nice on Smart Checkout.

If the color parameter value is null or is not valid or is missing, then the default value 06abc1 will apply.

Example

You may find below a few examples.

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 feature: specify preselected 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:

https://demo.vivapayments.com/web2?ref={OrderCode}&paymentMethod={MethodId}

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

MethodId Payment Method
0 (default) Credit Card
23 PayPal
4 e-banking (ΔΙΑΣ)
3 Cash (Viva Spot)
19 BitPay
17 EPS
15 giropay
10 iDEAL
14 MULTIBANCO
11 P24
13 PayU
16 Sofort
18 WeChat Pay

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

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.

https://demo.vivapayments.com/web2?ref={OrderCode}&paymentMethod=23

Smart checkout with PayPal preselected payment method

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 (note that alternative payment methods 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 alternative payment methods that are asynchronous in principle, but also due to several various other reasons (network connection issues, malicious hijacking attempts, etc).

You can make a call to Retrieve transactions in order to verify the status of a specific payment, or alternatively you can get notified of a successful payment by using the ‘Transaction Payment Created’ webhook (the use a webhooks is mandatory in case you offer alternative payment methods).

Retrieve transaction

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

get    /checkout/v2/transactions/{transactionId}{Id}

Request example

Make the below call through a backend channel.

Note that you should use OAuth2 method for the authentication.

Run in Postman

curl --location --request GET 'https://demo-api.vivapayments.com/checkout/v2/transactions/c90d4902-6245-449f-b2b0-51d99cd09cfe' \
--header 'Authorization: Bearer eyJhbGciOiJSUzI1NiIsImtpZCI6IjBEOEZCOEQ2RURFQ0Y1Qzk3RUY1MjdDMDYxNkJCMjMzM0FCNjVGOUZSUzI1NiIsInR5cCI6ImF0K2p3dCIsIng1dCI6IkRZLTQxdTNzOWNsLTlTZkFZV3V5TXpxMlg1OCJ9.eyJ' \
--data-raw ''

<?php
$curl = curl_init();
curl_setopt_array($curl, array(
  CURLOPT_URL => 'https://demo-api.vivapayments.com/checkout/v2/transactions/c90d4902-6245-449f-b2b0-51d99cd09cfe',
  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 eyJhbGciOiJSUzI1NiIsImtpZCI6IjBEOEZCOEQ2RURFQ0Y1Qzk3RUY1MjdDMDYxNkJCMjMzM0FCDfijp3F6qVPlpUiX5Jj_Eg6VLZV28N5rKVub_bJx4os1tWZJRkSmwCs-NSZwyntq2L4sKCfPelelwLTC61CUEYwZ4Okgi6Dz1-2nkMm0vTJN9snwsKyyrEd3nX3rbnTzZJ5EI28fgBRt14wO-zKWrVmW6Dfh6X6Ups5qUpclHyL9jzLdnC5I8QSjYkxw'
  ),
));
$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",
    "transactionTypeId": 5,
    "recurringSupport": false,
    "totalInstallments": 0,
    "cardCountryCode": null,
    "cardIssuingBank": null,
    "currentInstallment": 0,
    "cardTypeId": 1
}

Webhook

You can get notified of a successful transaction by using the Transaction Payment Created webhook.

This is a mandatory step if you offer alternative payment methods. Note that alternative payment methods are asynchronous in principle, meaning that it 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.

Conclusion: Switch from sandbox/demo to production/live

When you are happy with your integration with Viva Wallet, see our go-live steps to find out how to launch to live.

Implementation guidance

Further information

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