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"
Installments
Charge Installment
Charge an installment to the customer’s saved card.
POST
/
installment-plans
/
{plan_id}
/
installments
/
{position}
/
charge
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"
Charge Installment
Intro
Charges one installment to the card saved by the first installment, off session. Requires anIdempotency-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 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
{
"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 |
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"
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.