## List installment plans

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

```http
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>

## 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

### `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.