> ## 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. # Installments > Sell a product in installments: the customer pays part now and the rest later. ## Intro An installment purchase splits one product's price into parts paid over time. The customer pays the first installment at checkout; that payment opens an **installment plan** and saves their card, and the remaining installments are collected later — by you through the API, by the customer through a pay link, or automatically by Khaime on each due date. The word is **installment** everywhere in the API. In the Partner API, "split" means marketplace commission (how one sale is divided between an operator and a sub-merchant), never paying in parts. ## Context Installments are set per product, like a price: a product carries an installment template (`installment_plan`) and every installment purchase of it follows that template. The first installment goes through the same checkout as any other payment ([Create Payment Session](/api-reference/payments/create-session) or the dedicated [Installment Checkout](/api-reference/installments/checkout)), so [Gateway Routing](/payments/gateway-routing) and [Multicurrency](/payments/multicurrency) apply unchanged. Each paid installment is its own payment: it has its own transaction (visible with [Get Transaction](/api-reference/payments/get-transaction)), credits the wallet, and can be refunded on its own. On top of that, the plan has its own lifecycle and [webhook events](/webhooks/events). All amounts are integers in the smallest currency unit. Installment amounts are always whole units that add up exactly to the total charged. ## Hows ### 1. Give the product an installment template Set `installment_plan` when you create or update a product with the [Marketplace Products](/api-reference/marketplace/products) endpoints: ```bash theme={null} curl -X PATCH https://api.khaime.com/api/v1/marketplace/products/3046 \ -H "X-API-Key: pk_sandbox_your_key" \ -H "Content-Type: application/json" \ -d '{ "installment_plan": { "enabled": true, "installments": [ { "position": 1, "label": "Deposit", "type": "percentage", "amount": 40 }, { "position": 2, "label": "Second payment", "type": "percentage", "amount": 30 }, { "position": 3, "label": "Final payment", "type": "percentage", "amount": 30 } ] } }' ``` | Rule | Detail | | ------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------- | | At least two installments | A single part is just a normal purchase. | | Positions run 1, 2, 3 … | No gaps or repeats. Position 1 is paid at checkout. | | One `type` for all installments | `percentage` (a percent of the price) or `amount` (a fixed part of the price, in minor units). | | Percentages add up to 100 | With `amount`, the parts are scaled to the total actually charged — after currency conversion or discounts — so they always add up. | Send `{ "enabled": false }` to stop selling the product in installments. Product reads return `installment_plan` (or `null`). ### 2. Preview the schedule ```bash theme={null} GET /products/3046/installment-quote ``` Returns each installment's amount and when it would fall due if the plan started today — see [Installment Quote](/api-reference/installments/quote). ### 3. Take the first installment ```bash 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 } }' ``` `"installment": { "enabled": true }` also works on `POST /payments/sessions`, `POST /payments/intents` and `POST /sdk/initialize`. The response is a `payment` to complete in the browser: confirm Stripe with Stripe.js and the `client_secret` (3-D Secure is handled there), or redirect to `payment_url` for Paystack and Flutterwave. When the checkout is recorded the plan is created (`installment_plan.created`, status `pending`); when the customer pays, the first installment is `paid`, the plan becomes `active`, the card is saved and the remaining installments get their due dates — monthly from that day. ### 4. Collect the rest Choose per plan: | How | When to use it | | ----------------------------------------------------------- | ----------------------------------------------------------------------------------------------- | | [Charge an installment](/api-reference/installments/charge) | You decide when to collect. Off session, to the saved card. Requires an `Idempotency-Key`. | | [Pay link](/api-reference/installments/pay-link) | The customer pays themselves — e.g. after a decline, or when their bank needs 3-D Secure. | | Automatic collection | The business turns it on for the plan in the Khaime dashboard. Khaime charges on each due date. | **Automatic collection** charges each installment on its due date and retries a failed charge after 1, 3 and 7 days. The third failure moves the plan to `past_due`; if the last retry fails too, the installment is marked `failed` and automatic collection stops for it (you can still charge it or send a pay link). Customers are emailed 3 days before each automatic charge and after each failed one. ### 5. Follow the plan * [List](/api-reference/installments/list) and [get](/api-reference/installments/get) plans for their status, amounts paid and due, and each installment's status and due date. * Listen for the [installment webhooks](/webhooks/events): `installment_plan.created`, `.past_due`, `.completed`, `.cancelled` and `installment.paid`, `.failed`, `.due_soon`. * `installment.paid` fires for every installment, however it was paid, with the `payment_id` of its transaction. * Installments paid through checkout or a pay link also fire `payment.succeeded`, with `payment_type: "installment"` and `installment: { plan_id, position, total_installments }`. Installments charged off session (the charge endpoint or automatic collection) are reported by `installment.paid` only. ### Cancel and refund * [Cancel a plan](/api-reference/installments/cancel) to stop collecting: unpaid installments are cancelled, paid ones are untouched. * Refund one installment with [Refunds](/payments/refunds) and `installment: { plan_id, position }` instead of a transaction ID. Only that installment's money is returned, and the customer keeps access to the product while other installments remain paid. ### Scope and environments Every installment endpoint is scoped to your API key: plans of your business and, for a marketplace operator, its active sub-merchants — and only plans in the key's environment. A sandbox key never sees or charges a live plan. Anything outside that scope answers `404 INSTALLMENT_PLAN_NOT_FOUND`. ### Error codes | `error_code` | HTTP | Meaning | | -------------------------------------- | ---- | -------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `INSTALLMENT_PLAN_NOT_FOUND` | 404 | No such plan for this key's business and environment | | `INSTALLMENT_NOT_FOUND` | 404 | The plan has no installment at that position | | `INSTALLMENT_ALREADY_PAID` | 409 | The installment is already paid | | `INSTALLMENT_PAYMENT_METHOD_MISSING` | 400 | The plan has no saved card; use a pay link | | `INSTALLMENT_NOT_ALLOWED` | 400 | The product isn't sold in installments, the plan is closed (completed, cancelled, defaulted), the installment isn't paid (refunds), or the template is invalid | | `INSTALLMENT_IDEMPOTENCY_KEY_REQUIRED` | 400 | A charge request without an `Idempotency-Key` header | | `IDEMPOTENCY_CONFLICT` | 409 | The `Idempotency-Key` was used for a different request, or that request is still running | | `PAYMENT_CARD_DECLINED` | 402 | The saved card was declined | ## Whys Installments are a product setting rather than a per-checkout option so that every buyer of a product gets the same terms and the schedule a customer saw in the quote is the schedule they get. The first installment reuses normal checkout — instead of a separate "create plan" call — so it inherits gateway routing, currency conversion, fees and 3-D Secure without a second integration path, and saving the card happens as part of a payment the customer is already making. Later installments are recorded as their own payments (own transaction, wallet credit, `payment.succeeded`, refundable on their own) because that is what they are to accounting, reporting and refunds; the plan is the thread that ties them together. Charges need an `Idempotency-Key` because a network retry on a money-moving call must never charge twice; Khaime additionally refuses to charge an installment that is already paid, whatever the key. ## Why nots * The schedule is monthly from the first payment; custom intervals and start dates are not configurable yet. * A template can't mix `percentage` and `amount` installments. * Changing a product's template doesn't change existing plans — each plan keeps the amounts it was opened with. * `POST /payments/charge` (product-agnostic charges) doesn't support installments — installments need a product with a template. * Cancelling a plan doesn't refund paid installments; refund them separately. * A customer who defaults keeps their access unless the business revokes it; there is no automatic access revocation on default yet.