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
integer
required
A product with an installment template.
object
required
string
stripe, paystack or flutterwave. Defaults to the gateway for the product’s currency.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",
"checkout_url": "https://pay.khaime.com/checkout?data=eyJpbnRlbnRfaWQiOi...",
"installment": {
"plan_id": 812,
"position": 1,
"total_installments": 3,
"amount": 4000,
"total_amount": 10000,
"currency": "USD",
"schedule": [
{ "position": 1, "label": "Deposit", "amount": 4000, "status": "due", "due_date": null, "due_in_months": 0 },
{ "position": 2, "label": "Second payment", "amount": 3000, "status": "upcoming", "due_date": null, "due_in_months": 1 },
{ "position": 3, "label": "Final payment", "amount": 3000, "status": "upcoming", "due_date": null, "due_in_months": 2 }
]
}
}
}
}
checkout_url for Khaime’s hosted checkout, or confirm client_secret yourself.
installment is the schedule the hosted checkout shows: amounts in minor units of the charged currency, adding up to total_amount.
Or 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
- 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.