Redirect Checkout

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

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

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:
  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 Redirect Checkout integration procedure from beginning to end.

sequenceDiagram participant Merchant app 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 app:Payment order Merchant app->>Viva Wallet API:Redirect customer to Viva Wallet payment page to pay the payment order Viva Wallet API-->>Merchant app:Confirm the payment of the payment order Merchant app->>Merchant app:Verify payment and set webhook

Integration flow instructions

The overall integration process is as follows:

  1. Create the payment order
  2. Redirect the customer to the Viva Wallet page 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:

post    /api/ordersCreate payment order

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,
    "email": "customer@example.com",
    "fullName": "Customer full name",
    "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,
    "email": "customer@example.com",
    "fullName": "Customer full name",
    "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;

Run in Postman

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

  • email and fullName are requested by the customer to be provided if not specified during the creation of the payment order (asking the customer to provide information that he has already provided may cause them to abandon the checkout)
  • customerTrns provides information on what the customer is being asked to pay for (it is good practice to provide a reminder / confirmation of what they are paying for)
  • 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 the Viva Wallet page to pay the payment order

Redirect the customer to the Viva Wallet checkout page 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 checkout form where the customer can enter their payment details and complete the payment:

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

Step 3: Confirm the payment of the payment order

After the customer clicks on the payment button, which appears on the Viva Wallet page that is used to pay the payment order, the customer is redirected back to your website. If the payment has been successful, the customer is redirected to the Success URL, otherwise (i.e. if the payment has been unsuccessful) they are redirected to your Failure URL.

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 parameters to the URL:

  • s (int64): The unique 12-digit ID for the payment order
  • t (uuid): The transaction ID (may not be returned for some failed transactions)
  • Lang (string): The language of the destination page in ISO 639 defined format (en-GB for English)

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.

Run in Postman

Additionally, you can get notified of a successful transaction by using the Create transaction 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: