> ## Documentation Index
> Fetch the complete documentation index at: https://docs.khaime.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Installment Checkout

> Take the first installment and open an installment plan.

# Installment Checkout

## Intro

Starts checkout for the first installment of a product sold in installments. When the customer pays, an installment plan is opened and their card is saved for the rest.

## Context

This is the installment version of [Create Payment Session](/api-reference/payments/create-session). The same checkout is available by adding `"installment": { "enabled": true }` to `POST /payments/sessions`, `POST /payments/intents` or `POST /sdk/initialize` — those endpoints then return this response. See [Installments](/payments/installments) for the whole flow.

## Hows

`POST /installment-plans/checkout`

### Request body

| Field                 | Type    | Required | Description                                                                                |
| --------------------- | ------- | -------- | ------------------------------------------------------------------------------------------ |
| `product_id`          | integer | Yes      | A product with an installment template.                                                    |
| `customer.email`      | string  | Yes      | The customer's email.                                                                      |
| `customer.full_name`  | string  | No       | Or `first_name` and `last_name`.                                                           |
| `customer.phone`      | string  | No       |                                                                                            |
| `payment_gateway`     | string  | No       | `stripe`, `paystack` or `flutterwave`. Defaults to the gateway for the product's currency. |
| `installment.enabled` | boolean | Yes      | Must be `true`.                                                                            |

### Response

```json theme={null}
{
  "status": true,
  "message": "Installment checkout created",
  "data": {
    "installment_position": 1,
    "payment": {
      "gateway": "stripe",
      "client_secret": "pi_3Q..._secret_...",
      "payment_intent_id": "pi_3Q...",
      "publishable_key": "pk_live_...",
      "stripe_account_id": null,
      "access_code": null,
      "payment_url": null,
      "reference": null,
      "amount": 4000,
      "currency": "usd"
    }
  }
}
```

Complete the payment in the browser: for Stripe, confirm with Stripe.js using `client_secret` (and `stripe_account_id` when present — the payment is then on the business's own Stripe account); 3-D Secure is handled there. For Paystack and Flutterwave, redirect the customer to `payment_url`.

### What happens next

1. The plan is created with status `pending` and `installment_plan.created` is sent.
2. When the payment succeeds, installment 1 is `paid` (`installment.paid`), the plan becomes `active`, the card is saved, and the other installments get due dates, monthly from that day.

### Errors

| Status | `error_code`              | Cause                                                           |
| ------ | ------------------------- | --------------------------------------------------------------- |
| 400    | `INSTALLMENT_NOT_ALLOWED` | The product isn't sold in installments                          |
| 404    | `PRODUCT_NOT_FOUND`       | Not your product, or not in your key's environment              |
| 422    | `VALIDATION_FAILED`       | Missing `product_id`, `customer.email` or `installment.enabled` |

<RequestExample>
  ```bash cURL theme={null}
  curl -X POST https://api.khaime.com/api/v1/installment-plans/checkout \
    -H "X-API-Key: pk_sandbox_your_key" \
    -H "Content-Type: application/json" \
    -d '{
      "product_id": 3046,
      "customer": { "email": "ada@example.com", "full_name": "Ada Lovelace" },
      "installment": { "enabled": true }
    }'
  ```
</RequestExample>

## Whys

The first installment is a real checkout rather than a card-only setup step so the customer pays something at the moment they commit, and so routing, currency conversion, fees and 3-D Secure all behave exactly as they do for any other purchase.

## Why nots

* The amount charged is the first installment only; there is no way to prepay several installments in one checkout.
* It doesn't take a coupon or custom amount — the product's price and template decide the amounts.