Get installment information

POST https://{domainname}/client/v1/{customerId}/installments/getInstallmentsInfo

Installments

Using the Installment Service API you can ask us to provide you with information related to the available installment options, based on the country, amount and optionally payment productId and bin number.

Request

Using this endpoint you can retrieve the latest Installment Programs. Optionally you can filter the returned sets on a bin and/or a paymentProductId. The Installment Programs are always returned in an array.

PayloadGetInstallmentRequest

Property	Type	Required	Details
Properties Expand all properties Hide deprecated properties
amountOfMoney	object	no	read close
close Description Object containing amount and ISO currency code attributes SDK Object type AmountOfMoney
amount	integer (12)	yes	read close
close Description Amount in cents and always having 2 decimals
currencyCode	string (3)	yes	read close
close Description Three-letter ISO currency code representing the currency for the amount
bin	string (19)	no	read close
close Description The first digits of the card number from left to right with a minimum of 6 digits
countryCode	string (2)	no	read close
close Description ISO 3166-1 alpha-2 country code
paymentProductId	integer (5)	no	read close
close Description Payment product identifier Please see payment products for a full overview of possible values.

Request example

SDK: JavaScript

This service allows you to retrieve information and details regarding the installment plans, providers and options.

```
N/A
```

Responses

Please find below the possible responses for this API endpoint

Response 200 - OKInstallmentOptionsResponse

An HTTP 200 response is returned with the details of the installments plan(s) and option(s)

Property	Type	Required	Details
Properties Expand all properties Hide deprecated properties
installmentOptions	array of object	no	read close
close Description Array containing installment options their details and characteristics
items	object	no	read close
close Description Object containing the available intallment options SDK Object type InstallmentOptions
displayHints	object	no	read close
close Description Object containing information for the client on how best to display the installment options SDK Object type InstallmentDisplayHints
displayOrder	integer	no	read close
close Description Determines the order in which the installment options should be shown (sorted ascending). In countries like Turkey there are multiple loyalty programs that offer installments
label	string	no	read close
close Description Name of the installment option
logo	string	no	read close
close Description Partial URL that you can reference for the image of this installment provider. You can use our server-side resize functionality by appending '?size={{width}}x{{height}}' to the full URL, where width and height are specified in pixels. The resized image will always keep its correct aspect ratio.
id	string	no	read close
close Description The ID of the installment option in our system
installmentPlans	array of object	no	read close
close Description Object containing information about installment plans
items	object	no	read close
close Description Object containing information about the installment option SDK Object type Installments
amountOfMoneyPerInstallment	object	no	read close
close Description The amount that will be paid per installment. The total amount of amountOfMoneyPerInstallment x numberOfInstallments can not be higher than the total amount of this transaction, although we will not validate that. For the payment product IDs BC Card (paymentProductId 8590), Hana Card (paymentProductId 8591), Hyundai Card (paymentProductId 8592), KB Card (paymentProductId 8593), Lotte Card (paymentProductId 8594), NH Card (paymentProductId 8595), Samsung Card (paymentProductId 8596) and Shinhan Card (paymentProductId 8597), this property is not used as the value is decided by the issuer. SDK Object type AmountOfMoney
amount	integer (12)	yes	read close
close Description Amount in cents and always having 2 decimals
currencyCode	string (3)	yes	read close
close Description Three-letter ISO currency code representing the currency for the amount
amountOfMoneyTotal	object	no	read close
close Description Object containing the total amount and ISO currency code attributes SDK Object type AmountOfMoney
amount	integer (12)	yes	read close
close Description Amount in cents and always having 2 decimals
currencyCode	string (3)	yes	read close
close Description Three-letter ISO currency code representing the currency for the amount
frequencyOfInstallments	string	no	read close
close Description The frequency in which the installments will be collected from the customer. The possible values are: daily weekly monthly (default) quarterly For the payment product IDs BC Card (paymentProductId 8590), Hana Card (paymentProductId 8591), Hyundai Card (paymentProductId 8592), KB Card (paymentProductId 8593), Lotte Card (paymentProductId 8594), NH Card (paymentProductId 8595), Samsung Card (paymentProductId 8596) and Shinhan Card (paymentProductId 8597), only the value monthly is valid.
installmentPlanCode	integer	no	read close
close Description The code for the installment plan. The possible values are: 43 No-interest, 3 month Installmentplan 46No-interest, 6 month Installmentplan 49No-interest, 9 month Installmentplan 52No-interest, 12 month Installmentplan
interestRate	string	no	read close
close Description The interest rate paid for installments expressed in percentage. So for example 5.75 means 5.75% For the payment product IDs BC Card (paymentProductId 8590), Hana Card (paymentProductId 8591), Hyundai Card (paymentProductId 8592), KB Card (paymentProductId 8593), Lotte Card (paymentProductId 8594), NH Card (paymentProductId 8595), Samsung Card (paymentProductId 8596) and Shinhan Card (paymentProductId 8597), this property is not used as the value is decided by the issuer.
numberOfInstallments	integer (5)	no depends no yes no	read close
close Description The number of installments in which this transaction will be paid, which can be used for card payments at supported acquirers, or with specific payment products. Only used with some acquirers. In case you send in the details of this object, only the payment products (or combination of card products and acquirers) that support installments will be shown on the MyCheckout hosted payment pages. If this property is not provided the customer will not see details on the installment plan in a HostedCheckout. For the payment product IDs BC Card (paymentProductId 8590), Hana Card (paymentProductId 8591), Hyundai Card (paymentProductId 8592), KB Card (paymentProductId 8593), Lotte Card (paymentProductId 8594), NH Card (paymentProductId 8595), Samsung Card (paymentProductId 8596) and Shinhan Card (paymentProductId 8597), there is a maximum of 12 installments. Depends on: Required by the GlobalCollect platform.

Response example

SDK: JavaScript

This scenario you will probably use the most

{
    "installmentOptions" : [
        {
            "displayHints" : {
                "label" : "Maxime",
                "displayOrder" : 1,
                "logo" : "https://assets.pay1.checkout.worldline-solutions.com/somefilename.png"
            },
            "id" : "Maxime",
            "installmentPlans" : [
                {
                    "numberOfInstallments" : 1,
                    "installmentPlanCode" : 0,
                    "interestRate" : "0.000000",
                    "amountOfMoneyTotal" : {
                        "amount" : 10000,
                        "currencyCode" : "EUR"
                    }
                },
                {
                    "numberOfInstallments" : 2,
                    "installmentPlanCode" : 2,
                    "interestRate" : "4.000000",
                    "frequencyOfInstallments" : "monthly",
                    "amountOfMoneyPerInstallment" : {
                        "amount" : 5200,
                        "currencyCode" : "EUR"
                    },
                    "amountOfMoneyTotal" : {
                        "amount" : 10400,
                        "currencyCode" : "EUR"
                    }
                },
                {
                    "numberOfInstallments" : 4,
                    "installmentPlanCode" : 4,
                    "interestRate" : "4.000000",
                    "frequencyOfInstallments" : "monthly",
                    "amountOfMoneyPerInstallment" : {
                        "amount" : 2600,
                        "currencyCode" : "EUR"
                    },
                    "amountOfMoneyTotal" : {
                        "amount" : 10400,
                        "currencyCode" : "EUR"
                    }
                }
            ]
        },
        {
            "displayHints" : {
                "label" : "Bonus",
                "displayOrder" : 2,
                "logo" : "https://assets.pay1.checkout.worldline-solutions.com/somefilename.png"
            },
            "id" : "Bonus",
            "installmentPlans" : [
                {
                    "numberOfInstallments" : 1,
                    "installmentPlanCode" : 0,
                    "interestRate" : "0.000000",
                    "amountOfMoneyTotal" : {
                        "amount" : 10000,
                        "currencyCode" : "EUR"
                    }
                },
                {
                    "numberOfInstallments" : 2,
                    "installmentPlanCode" : 2,
                    "interestRate" : "4.000000",
                    "frequencyOfInstallments" : "monthly",
                    "amountOfMoneyPerInstallment" : {
                        "amount" : 5200,
                        "currencyCode" : "EUR"
                    },
                    "amountOfMoneyTotal" : {
                        "amount" : 10400,
                        "currencyCode" : "EUR"
                    }
                },
                {
                    "numberOfInstallments" : 4,
                    "installmentPlanCode" : 4,
                    "interestRate" : "4.000000",
                    "frequencyOfInstallments" : "monthly",
                    "amountOfMoneyPerInstallment" : {
                        "amount" : 2600,
                        "currencyCode" : "EUR"
                    },
                    "amountOfMoneyTotal" : {
                        "amount" : 10400,
                        "currencyCode" : "EUR"
                    }
                }
            ]
        }
    ]
}

Response 400 - Bad requestErrorResponse

There was an error in the request, or the country you submitted does not allow installments or the filters you submitted result in no installment options

Property	Type	Required	Details
Properties Expand all properties Hide deprecated properties
errorId	string	yes	read close
close Description Unique reference, for debugging purposes, of this error response
errors	array of object	yes	read close
close Description List of one or more errors
items	object	no	read close
close SDK Object type APIError
category	string	no	read close
close Description Category the error belongs to. The category should give an indication of the type of error you are dealing with. Possible values: CONNECT\_PLATFORM\_ERROR - indicating that a functional error has occurred in the Connect platform. PAYMENT\_PLATFORM\_ERROR - indicating that a functional error has occurred in the Payment platform. IO\_ERROR - indicating that a technical error has occurred within the Connect platform or between Connect and any of the payment platforms or third party systems.
code	string	yes	read close
close Description Error code
httpStatusCode	integer	no	read close
close Description HTTP status code for this error that can be used to determine the type of error
id	string	no	read close
close Description ID of the error. This is a short human-readable message that briefly describes the error.
message	string	no	read close
close Description Human-readable error message that is not meant to be relayed to customer as it might tip off people who are trying to commit fraud
propertyName	string	no	read close
close Description Returned only if the error relates to a value that was missing or incorrect. Contains a location path to the value as a JSonata query. Some common examples: a.b selects the value of property b of root property a, a[1] selects the first element of the array in root property a, a[b='some value'] selects all elements of the array in root property a that have a property b with value 'some value'.
requestId	string	no	read close
close Description ID of the request that can be used for debugging purposes

Response example

SDK: JavaScript

This scenario you will probably use the most

{
    "errorId" : "15eabcd5-30b3-479b-ae03-67bb351c07e6-00000092",
    "errors" : [
        {
            "code" : "20000000",
            "propertyName" : "bankAccountBban.accountNumber",
            "message" : "PARAMETER_NOT_FOUND_IN_REQUEST"
        }
    ]
}

Get installment information

Installments

Request

PayloadGetInstallmentRequest

Description

Description

Description

Description

Description

Description

Request example

Responses

Response 200 - OKInstallmentOptionsResponse

Description

Description

Description

Description

Description

Description

Description

Description

Description

Description

Description

Description

Description

Description

Description

Description

Description

Description

Description

Depends on:

Response example

Response 400 - Bad requestErrorResponse

Description

Description

Description

Description

Description

Description

Description

Description

Description

Response example