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

# Charge Installment

> Charge an installment to the customer's saved card.

# Charge Installment

## Intro

Charges one installment to the card saved by the first installment, off session. Requires an `Idempotency-Key` header.

## Context

Use this when you decide when to collect. The customer isn't present, so if their bank asks for 3-D Secure or the card is declined, send a [pay link](/api-reference/installments/pay-link) instead. A plan on automatic collection is charged by Khaime on its due dates; you can still charge an installment early with this endpoint.

## Hows

`POST /installment-plans/{plan_id}/installments/{position}/charge`

### Headers

| Header            | Required | Description                                                                   |
| ----------------- | -------- | ----------------------------------------------------------------------------- |
| `Idempotency-Key` | Yes      | Up to 255 characters, unique per charge you intend to make — a UUID is ideal. |

### Idempotency

* Retrying with the same key returns the first response — same status, same body — with `Idempotent-Replayed: true`, and never charges again.
* The same key for a different installment, or while the first request is still running, answers `409 IDEMPOTENCY_CONFLICT`.
* Responses are kept for 24 hours. Server errors (5xx) aren't kept, so a retry with the same key runs again.
* An installment that's already paid is never charged twice, whatever the key: a new key answers `409 INSTALLMENT_ALREADY_PAID`.

### Response

```json theme={null}
{
  "status": true,
  "message": "Installment charged",
  "data": {
    "installment_plan": { "id": 812, "status": "active", "amount_paid": 7000, "amount_due": 3000, "installments": ["..."] },
    "payment": { "gateway": "stripe", "reference": "ch_3Q...", "amount": 3000, "currency": "usd" }
  }
}
```

`installment.paid` is sent for the installment, and `installment_plan.completed` if it was the last one.

### Errors

| Status | `error_code`                           | Cause                                                  |
| ------ | -------------------------------------- | ------------------------------------------------------ |
| 400    | `INSTALLMENT_IDEMPOTENCY_KEY_REQUIRED` | No `Idempotency-Key` header                            |
| 400    | `INSTALLMENT_PAYMENT_METHOD_MISSING`   | The plan has no saved card                             |
| 400    | `INSTALLMENT_NOT_ALLOWED`              | The plan is completed, cancelled or defaulted          |
| 402    | `PAYMENT_CARD_DECLINED`                | The card was declined                                  |
| 404    | `INSTALLMENT_PLAN_NOT_FOUND`           | No such plan for your key                              |
| 404    | `INSTALLMENT_NOT_FOUND`                | No installment at that position                        |
| 409    | `INSTALLMENT_ALREADY_PAID`             | Already paid                                           |
| 409    | `IDEMPOTENCY_CONFLICT`                 | Key reused for a different request, or still in flight |

<RequestExample>
  ```bash cURL theme={null}
  curl -X POST https://api.khaime.com/api/v1/installment-plans/812/installments/2/charge \
    -H "X-API-Key: pk_sandbox_your_key" \
    -H "Idempotency-Key: 7f3c1b9e-812-2"
  ```
</RequestExample>

## Whys

A charge moves money, and a timeout doesn't tell you whether it happened. The idempotency key makes retrying safe: the retry either replays the result or waits for the first attempt, and never charges a second time.

## Why nots

* It can't charge a different amount than the installment's, or several installments at once — call it once per position.
* A declined card isn't retried by this endpoint; retry later with a new key, or send a pay link.