Redirect Checkout

Redirect Checkout offers a straightforward method to integrate with Viva Wallet to accept payments online for your online store. It involves minimal coding on your side and offers the widest variety of payment options and overall features.

With our Redirect Checkout, 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.

Redirect Checkout offers the widest variety of overall features:

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 (optional)

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 (optional)

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 How to authenticate using 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:

  • 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)
  • 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 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 (optional)

You should try to verify the status of the payment explicitly, and not depend only on whether your success or failure URL is called. You can make a call to Retrieve transactions in order to verify the status of a payment.

Run in Postman

To get notified of a successful transaction you can use the Create transaction event webhook.

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.

Further information

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