Smart Checkout Integration

A guide to the integration process for Smart Checkout.

• Before you start
  • Payment method messaging
• Integration flow diagram
• Integration flow instructions
  • Step 1: Create the payment order
    • Best practices
  • Step 2: Redirect the customer to Smart Checkout to pay the payment order
    • Optional (but recommended): specify brand color
    • Optional: specify pre-selected payment method
    • Optional: Display a cancel button on Smart Checkout
  • Step 3: Confirm the payment of the payment order
  • Step 4: Verify payment
    • Webhook (Transaction Payment Created) - recommended
    • API Call (Retrieve Transaction) - alternative
• Integrate a mobile app with Smart Checkout
• Go-Live
  • Pre-Go-Live Checklist
  • Go-Live Steps
• Additional use cases
  • Recurring payments
  • Pre-authorizations
• Further Information
• Get Support

Before you start

1. Create an account with Viva, 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 activated for you by us (e.g. Apple Pay), other payment methods can only be activated by yourself (e.g. PayPal), for others you need to get in touch with us to activate them for you after a further review of your business

Payment method messaging

It is important that the customer is aware of the payment methods you offer via Smart Checkout, as this will increase conversion and average order values.

You should let your customers know about the available payment options as they browse your online store, even before they decide to buy. Informing them early on will help the purchase decision, especially when offering BNPL or financing options. Doing so will create trust and let the customer know they can pay with whatever payment method is convenient to them. This is especially helpful for your international customers, as they will know they can pay with their own local payment method, even though they are shopping from a merchant from another country.

Display payment method icons or banners throughout your online store (indicatively: footer, homepage, product display page, cart/basket page, checkout, and so on) to captivate shoppers from the start, make your customers shop with confidence, help shoppers find the answers to their most commonly asked questions, and increase conversion. Especially when offering BNPL or financing options, inform your customers about their options as early as possible.

You can potentially include icons of the offered payment methods in:

• The footer or header of your online store
• The individual product pages
• The checkout page before redirecting the customer to Smart Checkout

Consider also including an FAQ to tell your customers everything they want to know about how to buy from you and all the payment methods you offer. This way, you’ll reduce any friction in the purchase journey as well as reducing contacts to your customer service team.

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 that you require a certain amount of money from one of your customers. Think of it as a utility bill. You give Viva 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 16-digit ID also referred to as the order code.

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 banking app under the payment sources for your website / app.

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

Request example

Make the below call through a backend channel.

Note that you should use OAuth2 method for the authentication.

curl '[Environment URL]'
-H 'Authorization: Bearer [access token]'
-H 'Content-Type: application/json'
-d '{
    "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",
        "Another string"
    ],
    "cardTokens":
    [
        "ct_5d0a4e3a7e04469f82da228ca98fd661"
    ]
}'

<?php
$curl = curl_init();
curl_setopt_array($curl, array(
  CURLOPT_URL => '[Environment URL]',
  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"],
 "cardTokens": ["ct_5d0a4e3a7e04469f82da228ca98fd661"]
}',
  CURLOPT_HTTPHEADER => array(
    'Authorization: Bearer [access token]',
    'Content-Type: application/json'
  ),
));
$response = curl_exec($curl);
curl_close($curl);
echo $response;

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
}

Best practices

Step 2: Redirect the customer to Smart Checkout to pay the payment order

Redirect the customer to the Viva Smart Checkout via a browser using the below URI format. Replace the OrderCode value with the one generated in the previous step.

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

Optional (but recommended): 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:

Example

You may find below a few examples of different color codes being used:

Blue (hex code 0000ff)	Gold (hex code ffd700)	Brown (hex code a52a2a)

Optional: specify pre-selected 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:

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

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.

Optional: Display a cancel button on Smart Checkout

You have the flexibility to display a Cancel button on Smart Checkout. This option is fully configurable at the source level, granting you the control to determine whether an order code associated with a particular source should include the ‘Cancel’ button. When this option is activated, your customers will have the ability to cancel their orders directly from the Smart Checkout interface. This action results in the cancellation of the order without any payment being processed, and the customer is redirected to your specified failure URL. The query parameter for this cancellation information will be automatically appended to the failure URL.

In order to activate Cancel button on Smart Checkout, please follow this guide.

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 (such as alternative payment methods, which 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 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 16-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 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

You need to explicitly verify the payment status and not rely solely on whether your success or failure URL is called. This is particularly important if you offer asynchronous payment methods. Other factors, such as network connection issues and malicious hijacking attempts, can also necessitate verification.

Our recommended method for verification is using the ‘Transaction Payment Created’ webhook. Alternatively, you can make an API call to ‘Retrieve Transaction’ to verify the status of a specific payment. Both methods are outlined below.

Webhook (Transaction Payment Created) - recommended

You should use webhooks so that we can notify you when the payment is confirmed as successful or failed.

API Call (Retrieve Transaction) - alternative

You can make a call to the Retrieve Transaction API in order to verify the status of a specific payment.

• You should make the below call through a backend channel
• You should use the OAuth2 method for authentication

Request example

curl '[Environment URL]'
-H 'Authorization: Bearer [access token]' \
-H 'Content-Type: application/json' \

<?php
$curl = curl_init();
curl_setopt_array($curl, array(
  CURLOPT_URL => '[Environment URL]',
  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 [access token]'
  ),
));
$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",
    "cardUniqueReference": "9521B4209B611B11E080964E09640F4EB3C3AA18",
    "transactionTypeId": 5,
    "recurringSupport": false,
    "totalInstallments": 0,
    "cardCountryCode": null,
    "cardIssuingBank": null,
    "currentInstallment": 0,
    "cardTypeId": 1
}

Integrate a mobile app with Smart Checkout

In case you need to integrate a mobile app with Smart Checkout, the above steps are still applicable but you need to adopt a slightly adjusted integration approach. Keep in mind that you still need to create a payment order, and redirect the customer to Smart Checkout, and then handle the redirect back to you and verify the payment. Details on how to integrate a mobile app with Smart Checkout can be found here.

Go-Live

Pre-Go-Live Checklist

Please refer to the following checklist to ensure you have completed all necessary steps before Go-Live.

• Set up your payment methods (please check to confirm which need to be activated or deactivated for your use cases)
  • Configure digital wallets
  • Configure local payment methods
  • Configure Direct Debit & other payment methods
  • Apply an additional 'Service fee' - if so desired - to be added on top of the order amount if the customer chooses to pay with specific payment methods (for payment methods that support a service fee). Refer to parameter `paymentMethodFees` of the 'Create payment order' API call
  • Display payment method icons or banners throughout your online store to indicate the payment methods you offer, as this will increase conversion and average order values


• Handle redirections, responses and errors
  • Implement a proper redirect (not using an iframe)
  • Test your success URL and failure URL and ensure they can handle the query parameters
  • Verify the payment and retrieve transaction details
  • Log EventId and X-Viva-CorrelationId if you have an error


• Ensure webhooks are functioning correctly, especially if offering asynchronous payments
  • Make sure you’ve defined an endpoint for the Transaction Payment Created webhook
  • Make sure you only allow VivaWallet IP addresses to access your webhook endpoints
  • Make sure that you can receive and process a notification


• Use the following API parameters to improve conversion
  • customerTrns - description for the customer
  • email - customer's email
  • fullName - customer's name
  • requestLang - customer's language
  • countryCode - affects the payment methods that will be offered to the customer


• Ensure the following API parameters are used
  • preauth - if doing pre-authorizations (authorize now, capture later via app/API)
  • allowRecurring - if doing recurring payments (fixed or variable amount)
  • maxInstallments - if supporting installments (customer selects number of installments)
  • paymentNotification - if doing payment notification (Viva sends email to customer)
  • tipAmount - if supporting tip amount (included in amount paid by customer)
  • disableExactAmount - if supporting open amount (the customer can specify what they pay)
  • paymentTimeout - if you need to allow more than the default 30 minutes for your customer to pay
  • cardTokens - if you need to save the card tokens of your customers in your merchant backend
  
  
• Configure customization options
  • Define your logo, as it improves conversion
  • Define your brand color, as it improves conversion
  • Define your preselected payment method, if you prefer your customer to pay you with a specific payment method
  
  
• Check additional payment features
  • If using recurring payments, create a new payment from an initial payment
  • If using pre-authorized payments, capture the pre-authorized payment via API
  • If using card installment payments, create an additional test payment with installments
  • If using merchant-side card tokenization, make sure you handle card tokens properly
  
  
• You may use the following API parameters for reconciliation purposes
  • phone - customer's phone number
  • merchantTrns - description for you
  • tags

Go-Live Steps

Please use the following checklist to ensure you complete all necessary steps to Go-Live.

1. Register for a live Viva account
   • To do this, visit our Open your account page
   
   
2. Set up a payment source in your production account
   • Visit Create a live payment source to find out how to do this
   
   
3. Authenticate using production credentials
   • See OAuth2 authentication method for further details
   
   
4. Update base URLs to live
   • Replace demo.vivapayments.com with www.vivapayments.com in your code
   
   
5. Final live testing with a real payment card
   • Make a test purchase for a small amount using a supported card. Afterwards, you can cancel the transaction from your Viva account

Additional use cases

Recurring payments

If the payment is initiated by you (the merchant), without the involvement of the customer, you should use recurring payments, rather than one-off payments.

• Note: the first payment requires customer involvement
• Use case (merchant): charge automatically a bill or a subscription, on a regular or non-regular schedule
• Check out the following tutorial for more details: Create a recurring payment

Pre-authorizations

If the transfer of funds is to be initiated later, but you now want to ensure the customer has the required funds and in fact reserve these funds, you should use a pre-authorization, rather than a direct charge.

• Use cases (customer): make a reservation (e.g. hotel), place a pre-order, and so on
• Use cases (merchant): place a hold on the funds until the order is shipped, and so on
• Check out the following tutorial for more details: Handle pre-authorizations

Further Information

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

• Use OAuth 2.0 authentication
• 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
• Integrate with a mobile app
• Add your brand logo
• Collect payments with QR codes
• Find transaction IDs
• Set your desired payment method
• Handle payments with card installments
• Handle Card Tokens

Get Support

If you would like to integrate with Viva, or if you have any queries about our products and solutions, please see our Contact & Support page to see how we can help!