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 basic 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 instalments

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    /api/orders

curl -L -X POST 'https://demo.vivapayments.com/api/orders' \
-H 'Content-Type: application/json' \
-H 'Authorization: Basic YmRmNGM2YjMtYzI2ZC00MDQ2LWI1ZGYtNWM0NDNlYzM5ZDA5Oj0jZmx0ZQ==' \
--data-raw '{
"amount": 10000,
"fullName": "Customer full name",
"email": "customer@example.com",
"maxInstallments": 12,
"customerTrns": "Short description of items/services purchased to display to your customer",
"merchantTrns": " Short description of items/services purchased by customer with installments",
"requestLang": "en-gb",
"sourceCode": "7862",
"expirationDate": "2025-12-01T08:00:00+00:00"
}'

<?php

$curl = curl_init();

curl_setopt_array($curl, array(
  CURLOPT_URL => 'https://demo.vivapayments.com/api/orders',
  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,
"fullName": "Customer Name",
"email": "someoneu@vivawallet.com",
"maxInstallments": 12,
"customerTrns": "Short description of items/services purchased to display to your customer",
"merchantTrns": "Short description of items/services purchased by customer with installments",
"requestLang": "el-GR",
"sourceCode": "8362",
"expirationDate": "2025-12-01T08:00:00+00:00"
}',
  CURLOPT_HTTPHEADER => array(
    'Content-Type: application/json',
    'Authorization: Basic YmRmNGM2YjMtYzI2ZC00MDQ2LWI1ZGYtNWM0NDNlYzM5ZDA5Oj0jZmx0ZQ=='
  ),
));

$response = curl_exec($curl);

curl_close($curl);
echo $response;

Run in Postman

Response example

{
    "OrderCode": 5177349754572606,
    "ErrorCode": 0,
    "ErrorText": null,
    "TimeStamp": "2021-11-03T17:07:57.3497545+02:00",
    "CorrelationId": null,
    "EventId": 0,
    "Success": true
}

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:

https://demo.vivapayments.com/web/checkout?ref=[OrderCode]

Payment page example

Payment Page URL

Payment Page URL

Payment Page URL

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    /api/transactions/XXX

curl -L -X GET 'https://demo.vivapayments.com/api/transactions/6986d304-d598-4666-b012-1b9903160038' \
-H 'Content-Type: application/json' \
-H 'Authorization: Basic YmRmNGM2YjMtYzI2ZC00MDQ2LWI1ZGYtNWM0NDNlYzM5ZDA5Oj0jZmx0ZQ==' \

<?php

$curl = curl_init();

curl_setopt_array($curl, array(
  CURLOPT_URL => 'https://demo.vivapayments.com/api/transactions/6986d304-d598-4666-b012-1b9903160038',
  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(
    'Content-Type: application/json',
    'Authorization: Basic YmRmNGM2YjMtYzI2ZC00MDQ2LWI1ZGYtNWM0NDNlYzM5ZDA5Oj0jZmx0ZQ=='
  ),
));

$response = curl_exec($curl);

curl_close($curl);
echo $response;

Run in Postman

Response example

{
    "Transactions": [
        {
            "Fee": 0.00,
            "BankId": "NET_MASTER",
            "ParentId": "196cf527-b1b9-4a7c-9be4-e56cd4b7e0ce",
            "Switching": false,
            "Amount": 2.00,
            "StatusId": "F",
            "ChannelId": "245a790d-c98d-4d80-ad97-a9b1efb5771e",
            "MerchantId": "bdf4c6b3-c26d-4046-b5df-5c443ec39d09",
            "ResellerId": null,
            "InsDate": "2022-03-02T00:00:00+02:00",
            "CreatedBy": null,
            "TipAmount": 0.00,
            "SourceCode": "8362",
            "TransactionId": "6986d304-d598-4666-b012-1b9903160038",
            "Commission": 0.30,
            "PanEntryMode": "81",
            "MerchantTrns": "Short description of items/services purchased by customer with installments",
            "CustomerTrns": "Carpet Cleaning Services",
            "IsManualRefund": false,
            "TargetPersonId": null,
            "AcquirerApproved": false,
            "SourceTerminalId": 80000000,
            "RedeemedAmount": 0.00,
            "AuthorizationId": "980316",
            TotalInstallments: 5,
            CurrentInstallment: 5,
            "ClearanceDate": null,
            "ResellerSourceCode": null,
            "RetrievalReferenceNumber": "130715980316",
            "Order": {
                "OrderCode": 5626499313972609,
                "ChannelId": "95d02b56-bace-4608-ad1b-c1a8da705e52",
                "ResellerId": null,
                "SourceCode": "8362",
                "Tags": [],
                "RequestLang": "el-GR",
                "ResellerSourceCode": null
            },
            "Payment": {
                "Email": "someone@vivawallet.com",
                "Phone": null,
                "ChannelId": "245a790d-c98d-4d80-ad97-a9b1efb5771e",
                "FullName": "George Mitsiou",
                "Installments": 5,
                "RecurringSupport": false
            },
            "TransactionType": {
                "Name": "CardCharge",
                "TransactionTypeId": 5
            },
            "CreditCard": {
                "Token": "5984325974181FFDE001404E14C6B88CF3613891",
                "Number": "523929XXXXXX0101",
                "CountryCode": "US",
                "IssuingBank": "BANK OF AMERICA N.A.",
                "CardHolderName": "George Mitsiou",
                "ExpirationDate": "2026-12-31T00:00:00",
                "CardType": {
                    "Name": "MasterCard",
                    "CardTypeId": 1
                }
            }
        }
    ],
    "ErrorCode": 0,
    "ErrorText": null,
    "TimeStamp": "2021-11-04T14:03:19.953722+02:00",
    "CorrelationId": null,
    "EventId": 0,
    "Success": true
}