List installment plans

API references

Search documentation... ⌘K

SDK API

All our references

This endpoint returns the card installment plans available for a given amount and card. Identify the card with either a bin (the leading digits of the card number) or a token from tokenize-card.

Eligibility depends on the card's BIN (issuing bank), the requested amount, the merchant's installment configuration, and per-plan constraints (minimum amount, maximum amount, minimum monthly amount). If no plans are eligible the endpoint returns an empty array; the client should hide the installment step and proceed to select-payment-method without an installment_plan_id.

The amounts returned (monthly_amount, total_amount, interest_amount) are computed against the amount you pass to this endpoint. Pass the same amount to select-payment-method to keep the customer's quote consistent.

Endpoint signature

POST https://api.reservepay.com/sdk/list-installment-plans HTTP/1.1

Content-Type: application/json

Accept: application/json

{

merchant_id: string,

installation_id: string,

bin: string?,

token: string?,

amount: string,

currency: string,

interest_bearer: string?,

}

Returns: array<object.installment_plan>

New to Reservepay? Read our guide on how to call endpoints to get started.

Request arguments

merchant_id string

Required. Your merchant ID that uniquely identifies your account.

installation_id string

Required. The installation ID for this platform (e.g. your iOS app, Android app, website, or terminal).

bin string

Optional. The leading digits of the card number, used to identify the issuing bank. Must be 6 to 8 digits.

Required unless you pass token. Passing both is an error.

token string

Optional. The card token obtained from tokenize-card. The token must not have been used in a prior payment session.

Required unless you pass bin. Passing both is an error.

amount string

Required. The payment amount in the smallest currency unit (e.g. satang). Must be a positive integer.

currency string

Required. The three-letter ISO currency code (e.g. THB). Must match the funding currency configured for your provider.

interest_bearer string

Optional. Who bears the interest: customer or merchant. When omitted, the merchant's configured default is used; if the merchant has no default configured this argument is required. Pass the same value to select-payment-method so the customer's displayed quote matches what gets locked onto the payment session.

Allowed values:

customer
merchant

Installment plan attributes

Attribute	Description
`installment_plan_id` string	Always present. The ID of the installment plan. Pass this to `select-payment-method` to confirm the customer's choice.
`name` string	Always present. Human-readable name of the installment plan.
`months` number	Always present. Number of monthly installments.
`interest_rate` string	Always present. The monthly interest rate as a decimal percentage string (e.g. `0.80` means 0.80% per month). Zero means interest-free.
`interest_bearer` string	Always present. Who bears the interest. When `merchant`, the customer pays only the original amount split across months. When `customer`, the customer pays the original amount plus interest. Possible values: `merchant` `customer`
`monthly_amount` number	Always present. Amount the customer pays per month, in the smallest currency unit. Computed against the requested payment amount and interest bearer.
`total_amount` number	Always present. Total amount across all installments, in the smallest currency unit.
`monthly_interest_amount` number	Always present. Interest charged per month, in the smallest currency unit.
`total_interest_amount` number	Always present. Total interest charged across all installments, in the smallest currency unit.
`currency` string	Always present. The three-letter ISO currency code for the amounts.
`bank_name` string	Always present. The name of the bank or provider offering this installment plan.

Errors specific to this endpoint


          NOT_FOUND

This error occurs when we cannot find the merchant account, installation, or card token with the IDs provided. Double check that you are using the correct IDs.


          TOKEN_ALREADY_USED

This token has already been used to create a payment session. Each token can only be used once. Request a new token from tokenize-card.

Errors common to all endpoints


          UNHANDLED_ERROR

This error occurs when the server encounters an unexpected internal error that it cannot handle gracefully. This typically happens due to bugs, infrastructure issues, or edge cases that weren't anticipated during development.


          INVALID_ARGUMENTS

This error occurs when the request contains invalid or missing parameters. Common cases include missing required fields, or values that don't match the expected format or type.


          BAD_VERSION

This error occurs when making requests to an API version that is either deprecated or not yet released. This commonly happens when using an outdated SDK or when the API version specified in the request URL is incorrect.

Open in Markdown

CODE SAMPLES

curl

curl "https://api.reservepay.com/sdk/list-installment-plans" \
  -X POST
  -H "Content-Type: application/json" \
  -H "Accept: application/json" \
  -d '{
        "merchant_id": "123456789012",
        "installation_id": "ins_xhBi6ypq9G",
        "token": "IC3949UCOE6U93",
        "amount": 100000,
        "currency": "THB",
      }'

Learn how to run these code samples in your terminal by reading our guide.