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 }
}'
Installments
Installment Checkout
Take the first installment and open an installment plan.
POST
/
installment-plans
/
checkout
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 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. 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 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
{
"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"
}
}
}
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
- The plan is created with status
pendingandinstallment_plan.createdis sent. - When the payment succeeds, installment 1 is
paid(installment.paid), the plan becomesactive, 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 |
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 }
}'
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.