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:
   • Sandbox/demo account, for testing purposes
   • Production/live account, for payments in the real world.
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.

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.

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.

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:

• 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 friction 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).
• 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).

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:

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)

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:

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

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:

• t (uuid): The transaction ID (may not be returned for failed transactions). Example: t=2b4c6b5b-49ff-4e46-adc5-f53740212361.
• s (int64): The unique 12-digit ID for the payment order. Example: s=7680701046572600.
• lang (string): The language of the destination page in ISO 639 defined format. Example: lang=en-GB.
• eventId (int32): Viva Wallet Event ID code. Example: eventId=10051 (Insufficient funds).
• eci (int32): Electronic Commerce Indicator, a value indicating the outcome of authentication attempted on transactions enforced by 3DS. Example: eci=1 (Authenticated).

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

Request example

Make the below call through a backend channel.

Note that you should use OAuth2 method for the authentication.

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:

• Enable OAuth2
• Create a payment order
• Create a recurring payment
• Verify a payment
• Set webhook to confirm payment
• Issue refunds via banking app or API
• Handle pre-authorizations