This site requires javascript to be enabled.

  • Search AI-powered
    Search results are AI-generated and are not guaranteed to be accurate, complete, or up-to-date. They are not a substitute for legal or professional advice. Refer to our terms of use for more details.
    Search AI-powered

Results for

xxx

Get installment information

POST https://{domainname}/v1/{merchantId}/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

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.

Properties
Property Type Required Details
close

Description

Object containing amount and ISO currency code attributes
  • SDK Object type
    AmountOfMoney
close

Description

Amount in cents and always having 2 decimals
close

Description

Three-letter ISO currency code representing the currency for the amount
close

Description

The first digits of the card number from left to right with a minimum of 6 digits
close

Description

ISO 3166-1 alpha-2 country code
close

Description

Payment product identifier
Please see payment products for a full overview of possible values.

Request example

SDK: JSON

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

  • {
    "amountOfMoney" : {
        "currencyCode" : "EUR",
        "amount" : 123
    },
    "countryCode" : "NL",
    "paymentProductId" : 123,
    "bin" : "123455"
}

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)

Properties
Property Type Required Details
close

Description

Array containing installment options their details and characteristics
close

Description

Object containing the available intallment options
  • SDK Object type
    InstallmentOptions
close

Description

Object containing information for the client on how best to display the installment options
  • SDK Object type
    InstallmentDisplayHints
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
close

Description

Name of the installment option
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.
close

Description

The ID of the installment option in our system
close

Description

Object containing information about installment plans
close

Description

Object containing information about the installment option
  • SDK Object type
    Installments
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
close

Description

Amount in cents and always having 2 decimals
close

Description

Three-letter ISO currency code representing the currency for the amount
close

Description

Object containing the total amount and ISO currency code attributes
  • SDK Object type
    AmountOfMoney
close

Description

Amount in cents and always having 2 decimals
close

Description

Three-letter ISO currency code representing the currency for the amount
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.
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
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.
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.

Response example

SDK: JSON

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

Properties
Property Type Required Details
close

Description

Unique reference, for debugging purposes, of this error response
close

Description

List of one or more errors
close

Description

Contains detailed information on one single error.
  • SDK Object type
    APIError
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.
close

Description

Error code
close

Description

HTTP status code for this error that can be used to determine the type of error
close

Description

ID of the error. This is a short human-readable message that briefly describes the error.
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
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'.
close

Description

ID of the request that can be used for debugging purposes

Response example

SDK: JSON

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"
        }
    ]
}