Smart Checkout

Smart Checkout offers a straightforward method 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

The demo environment has a base URL of https://demo.vivapayments.com/ and for the live environment it’s https://www.vivapayments.com/.

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, 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.

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 and set webhook

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.

Replace the Base64-encoded credentials with your own, generated as described under Basic auth.

curl -L -X POST 'https://demo.vivapayments.com/api/orders' \
-H 'Content-Type: application/json' \
-H 'Authorization: Basic [Base64-encoded credentials]' \
--data-raw '{
    "amount": 200,
    "fullName": "Customer full name",
    "email": "customer@example.com",
    "customerTrns": "Short description of items/services purchased to display to your customer",
    "requestLang": "en-GB",
    "sourceCode": "1234"

}'

<?php
$curl = curl_init();
curl_setopt_array($curl, array(
  CURLOPT_URL => 'https://demo.vivapayments.com/api/orders',
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_FOLLOWLOCATION => true,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => 'POST',
  CURLOPT_POSTFIELDS =>'{
    "amount": 200,
    "fullName": "Customer full name",
    "email": "customer@example.com",
    "customerTrns": "Short description of items/services purchased to display to your customer",
    "requestLang": "en-GB",
    "sourceCode": "1234"

}',
  CURLOPT_HTTPHEADER => array(
    'Content-Type: application/json',
    'Authorization: Basic [Base64-encoded credentials]'
  ),
));
$response = curl_exec($curl);
curl_close($curl);
echo $response;

Although the fullName, email, customerTrns, and requestLang 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 to be provided to conclude 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 on what the customer is being asked to pay for (it is good practice to provide a reminder description of what they are paying for). Include also tip amount if required. The tip value, if applicable for the customer’s purchase, is already included in the amount of the payment order.
• requestLang makes sure the customer views a payment page in their language (especially important for online stores with international customers).

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 along with some additional response data.

{
    "OrderCode": 7186650102996314,
    "ErrorCode": 0,
    "ErrorText": null,
    "TimeStamp": "2020-09-16T15:21:41.0299631+03:00",
    "EventId": 0,
    "Success": true
}

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/web/checkout?ref={OrderCode}

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

Step 3: Confirm the payment of the payment order

After the customer clicks on the payment button displayed 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, meaning that it may take up to a few days to confirm whether the payment has been successful. The status of a payment is identified by the StatusId parameter in the response body. Please refer to transaction feedback parameters for further information.

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 some 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 returned by issuer Directory Servers (namely Visa, MasterCard, JCB, and American Express) indicating the outcome of authentication attempted on transactions enforced by 3DS. Example: eci=1 (Authenticated).

Step 4: Verify payment and set webhook

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

First of all, you can make a call to Retrieve transactions in order to verify the status of a specific payment:

Request example (sandbox/demo)

Make the below call through a backend channel.

Replace the Base64-encoded credentials with your own, generated as described under Basic auth.

curl -L -X POST 'https://demo.vivapayments.com/api/transactions/93290013-f352-4554-9098-a3a8fccf106b' \
-H 'Content-Type: application/json' \
-H 'Authorization: Basic [Base64-encoded credentials]'

<?php

$curl = curl_init();

curl_setopt_array($curl, array(
  CURLOPT_URL => 'https://demo.vivapayments.com/api/transactions/93290013-f352-4554-9098-a3a8fccf106b',
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_FOLLOWLOCATION => true,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => 'POST',
  CURLOPT_HTTPHEADER => array(
    'Content-Type: application/json',
    'Authorization: Basic [Base64-encoded credentials]'
  ),
));

$response = curl_exec($curl);

curl_close($curl);
echo $response;

Response example

{
    "Transactions": [
        {
            "Fee": 0.00,
            "BankId": "NET_MASTER",
            "ParentId": null,
            "Switching": false,
            "Amount": 1.00,
            "StatusId": "F",
            "ChannelId": "d84f93ff-8ad0-4d97-a7a3-f187dd667553",
            "MerchantId": "9932abc2-ce1c-4c9b-9df1-4ace4fa186cc",
            "ResellerId": null,
            "InsDate": "2021-07-27T15:04:56.013+03:00",
            "CreatedBy": null,
            "TipAmount": 0.00,
            "SourceCode": "8061",
            "TransactionId": "93290013-f352-4554-9098-a3a8fccf106b",
            "Commission": 0.39,
            "PanEntryMode": "81",
            "MerchantTrns": null,
            "CustomerTrns": "Test",
            "IsManualRefund": false,
            "TargetPersonId": null,
            "AcquirerApproved": false,
            "SourceTerminalId": 80000000,
            "RedeemedAmount": 0.00,
            "AuthorizationId": "924704",
            "TotalInstallments": 0,
            "CurrentInstallment": 0,
            "ClearanceDate": "2021-07-28T02:05:27.263+03:00",
            "ResellerSourceCode": null,
            "RetrievalReferenceNumber": "120812924704",
            "Order": {
                "OrderCode": 8199504404547085,
                "ChannelId": "d84f93ff-8ad0-4d97-a7a3-f187dd667553",
                "ResellerId": null,
                "SourceCode": "8061",
                "Tags": [],
                "RequestLang": "en-GB",
                "ResellerSourceCode": null
            },
            "Payment": {
                "Email": "test@example.com",
                "Phone": null,
                "ChannelId": "d84f93ff-8ad0-4d97-a7a3-f187dd667553",
                "FullName": "test",
                "Installments": 0,
                "RecurringSupport": false
            },
            "TransactionType": {
                "Name": "CardCharge",
                "TransactionTypeId": 5
            },
            "CreditCard": {
                "Token": "9521B4209B611B11E080964E09640F4EB3C3AA18",
                "Number": "518834XXXXXX0060",
                "CountryCode": "SG",
                "IssuingBank": "MALAYAN BANKING BERHAD",
                "CardHolderName": "test",
                "ExpirationDate": "2023-01-31T00:00:00",
                "CardType": {
                    "Name": "MasterCard",
                    "CardTypeId": 1
                }
            }
        }
    ],
    "ErrorCode": 0,
    "ErrorText": null,
    "TimeStamp": "2021-07-29T15:21:19.7773449+03:00",
    "CorrelationId": null,
    "EventId": 0,
    "Success": true
}

Set webhook

Additionally, 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 basic auth
• 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