☰

Navigation:

Handle payments with card installments

How to handle payments with card installments.

Overview

Applicable only when integrating with our Smart Checkout solution.

Card installments are not available with recurring payments or pre-authorizations

With card installment payments you can allow your customer to pay the total purchase in small portions throughout a fixed period, as long as the following criteria are met:

• You registered your Viva account in Greece
• The customer’s card supports installments

To start with, you should set the maxInstallments parameter in Create Payment Order API call greater than 1 and up to 36. Following on from that, the customer needs to select the number of card installments he desires and then complete the payment successfully.

Please note: If offering installments, the value provided by the merchant is not the number of installments the customer will select, and it is not mandatory for the customer to select installments at all. The process is as follows:

  1. The merchant indicates the maximum number of installments they wish to offer to the customer
  2. It is then up to the customer whether they pay with or without installments
  3. If the customer decides to pay with installments, they are able to select the number of installments (up to the maximum specified by the merchant)

The below examples use OAuth2 auth for authentication. They also use the demo environment url, so make sure to replace with the production environment url when you go live.

Step 1: Create payment order with card installments

Although the amount is the only required parameter, we recommend that you also provide email (the customer’s e-mail address), fullName (the customer’s full name), customerTrns (a friendly description to display to the customer, such as a short description of items/services purchased or the customer order code), and requestLang (the language in which the payment form is displayed) parameters as they will encourage high conversion rates.

If not provided, email and fullName will be requested from the customer; customerTrns will appear empty to the customer and requestLang will use the default value.

The below example creates a payment order for a maximum of 12 card installments; the customer may select to pay with any number of card installments up to 12, e.g. the customer may choose to pay in 4 card installments.

Please note: the merchant also has the option to force a specific number of installments on a payment order by using the forceMaxInstallments parameter and setting it to true. When used, please note that the following conditions apply:

  1. It is mandatory for the customer to pay with installments and with the specific number indicated
  2. Only cards supporting installments can be used for the payment
  3. The value set within the maxInstallments parameter dictates the number of installments that will be forced to the customer. It should be >0, otherwise the call will return an error

Request example

post    /checkout/v2/orders

Run in Postman

Environment URL
Production https://api.vivapayments.com/checkout/v2/orders
Demo https://demo-api.vivapayments.com/checkout/v2/orders 
curl '[Environment URL]'
-H 'Authorization: Bearer [access token]'
-H 'Content-Type: application/json'
-d {
  "amount": 1000,
  "customerTrns": "Short description of items/services purchased to display to your customer",
  "customer": {
  "email": "gemitsio@hotmail.com",
  "fullName": "George",
  "phone": "00306944900640",
  "requestLang": "string"
  },
  "paymentTimeout": 0,
  "maxInstallments": 12,
  "forceMaxInstallments": false,
  "sourceCode": "",
  "merchantTrns": "Short description of items/services purchased by customer with card installments"
}'

<?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": 1000,
  "customerTrns": "Short description of items/services purchased to display to your customer",
"customer": {
"email": "gemitsio@hotmail.com",
"fullName": "George",
"phone": "00306944900640",
"requestLang": "string"
},
  "paymentTimeout": 0,
  "maxInstallments": 12,
  "forceMaxInstallments": false,
  "sourceCode": "",
  "merchantTrns": "Short description of items/services purchased by customer with card installments"
}',
  CURLOPT_HTTPHEADER => array(
    'Authorization: Bearer [access token]',
    'Content-Type: application/json'
  ),
));

$response = curl_exec($curl);

curl_close($curl);
echo $response;

Response example

{
    "orderCode": 4822010381672607
}

Step 2: Redirect customer to smart checkout

The customer needs to fill his card details in the Smart Checkout and to select the desired number of card installments out of the of total available number of card installments; for example, you my have indicated that the customer may pay with up to 12 card installments but the customer may choose to pay with 4 card installments. Then, the customer needs to successfully complete the payment.

Redirect the customer to the below URL replacing [OrderCode] with the order code from Step 1:

Environment URL
Production https://www.vivapayments.com/web/checkout?ref={OrderCode}&color={ColorCode}
Demo https://demo.vivapayments.com/web/checkout?ref={OrderCode}&color={ColorCode}

Payment page example

Smart Checkout with installments toggle

Smart Checkout with installments dropdown

Step 3: Confirm the payment

After the customer clicks on the payment button, 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.

The redirection uses the HTTP GET method and appends the following query string parameters to the redirect Success / Failure URL:

View payments with card installments

In your self-care account

Payment Page URL

Payment Page URL

Through API

You have the option to preview a payment with card installments using the Retrieve Transaction API Call.

The parameter totalInstallments includes the total selected number of card installments by customer and the parameter currentInstallment concerns the current number of card installments.

Request example

get    /checkout/v2/transactions/{transactionId}

Run in Postman

Environment URL
Production https://api.vivapayments.com/checkout/v2/transactions/{TransactionId}
Demo https://demo-api.vivapayments.com/checkout/v2/transactions/{TransactionId} 
curl '[Environment URL]'
-H 'Authorization: Bearer [access token]'

<?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",
    "transactionTypeId": 5,
    "recurringSupport": false,
    "totalInstallments": 0,
    "cardCountryCode": null,
    "cardIssuingBank": null,
    "currentInstallment": 0,
    "cardTypeId": 1
}

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!