Handle payments with card installments

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

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.

On this page:

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.

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

SelfCare

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 have any questions about our solutions, or questions about how to integrate with our solutions, please refer to our Get Support page.