Skip to main content

​
Intro

The customer pays the first installment at checkout. That payment opens an installment plan and saves their card. The remaining installments are collected later.
The API says installment. “Split” means marketplace commission, never paying in parts.

​
Context

  • Installments are set per product, as an installment template (installment_plan).
  • The first installment goes through normal checkout, so Gateway Routing and Multicurrency apply.
  • Each installment is its own payment: own transaction, wallet credit, payment.succeeded, refundable on its own.
  • Amounts are integers in the smallest currency unit and add up exactly to the total.

​
Hows

​
1. Set the template

Via Marketplace Products:
  • At least 2 installments, positions 1, 2, 3 … with no gaps.
  • One type for all: percentage (adds up to 100) or amount (minor units).
  • { "enabled": false } turns it off.
Or in the dashboard: Allow split payments on the product form.

​
2. Preview the schedule

GET /products/3046/installment-quote: see Installment Quote.

​
3. Take the first installment

Also works:
  • "installment": { "enabled": true } on POST /payments/sessions, POST /payments/intents and POST /sdk/initialize.
  • is_split: true, payment_split_position: 1 on Create Product Payment Intent.
Complete the returned payment in the browser (Stripe.js with client_secret, or redirect to payment_url). Once paid, the plan is active, the card is saved and the next installments are due monthly.

​
4. Collect the rest

Automatic collection charges on the due date and retries after 1, 3 and 7 days. The third failure sets the plan to past_due; the last one marks the installment failed. Customers get an email 3 days before each charge and after each failure. An installment is never charged twice. Paying one that is already paid returns INSTALLMENT_ALREADY_PAID.

​
5. Track the plan

  • List and get plans.
  • Webhooks: installment_plan.created, .past_due, .completed, .cancelled; installment.paid, .failed, .due_soon.
  • Every installment also fires payment.succeeded with payment_type: "installment" and installment: { plan_id, position, total_installments }.

​
Cancel and refund

  • Cancel a plan: unpaid installments are cancelled; paid ones stay.
  • Refund one installment with Refunds and installment: { plan_id, position }.

​
Scope

Endpoints see only your business’s plans (plus active sub-merchants for a marketplace operator), in the key’s environment. Anything else returns 404 INSTALLMENT_PLAN_NOT_FOUND.

​
Error codes

​
Whys

  • Per-product templates give every buyer the same terms, matching the quote.
  • The first installment reuses checkout, so routing, currency, fees and 3-D Secure work without extra integration.
  • Each installment is a normal payment for accounting and refunds; the plan links them.

​
Why nots

  • Schedule is monthly from the first payment; intervals aren’t configurable.
  • A template can’t mix percentage and amount.
  • Changing a template doesn’t change existing plans.
  • Each installment must be above the gateway minimum (e.g. $0.50 Stripe, ₦50 Paystack).
  • Storefront installments: one non-physical product per checkout.
  • POST /payment/intent and POST /payments/charge don’t support installments: they have no catalog product. Use Installment Checkout.
  • Cancelling doesn’t refund paid installments.
  • Defaulting doesn’t revoke access automatically.