☰

Navigation:

Payment with instalments

Applicable only when integrating with our Smart Checkout solution.

Instalments are not available with recurring payments or pre-authorizations. Also, instalments applies only to credit cards.

With instalment 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 instalments.

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 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:

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 instalments; the customer may select to pay with any number of instalments up to 12, e.g. the customer may choose to pay in 4 instalments.

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 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 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 instalments out of the of total available number of installments; for example, you my have indicated that the customer may pay with up to 12 installments but the customer may choose to pay with 4 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 instalments toggle

Smart Checkout with instalments 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 installments

SelfCare

Payment Page URL

Payment Page URL

Through API

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

The parameter totalInstallments includes the total selected number of installments by customer and the parameter currentInstallment concerns the current number of 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.