Developer

API references

Search documentation... ⌘K

SDK API

All our references

List installment plans

This endpoint returns the card installment plans available for a given amount and card token. Call it after tokenize-card and before select-payment-method when you want to offer installment plans for a card payment.

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,

token: string,

amount: string,

currency: string,

interest_bearer: string?,

}

Returns: array

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).

token string

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

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. Optional override for who bears the interest: customer or merchant. When omitted, the merchant's default setting is used. Pass the same value to select-payment-method so the customer's displayed quote matches what gets locked onto the payment session.

Response attributes

Attribute	Description
`installment_plan_id` string	The ID of the installment plan. Pass this to `select-payment-method` to confirm the customer's choice.
`name` string	Human-readable name of the installment plan.
`months` number	Number of monthly installments.
`interest_rate` string	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	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.
`monthly_amount` number	Amount the customer pays per month, in the smallest currency unit. Computed against the requested payment amount and interest bearer.
`total_amount` number	Total amount across all installments, in the smallest currency unit.
`monthly_interest_amount` number	Interest charged per month, in the smallest currency unit.
`total_interest_amount` number	Total interest charged across all installments, in the smallest currency unit.
`currency` string	The three-letter ISO currency code for the amounts.
`bank_name` string	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.

CODE SAMPLES

curl

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