Take installment payments

What you decide

• How often: daily, weekly or monthly, every 1, 2, 3 ... of them (for example every 2 weeks), and how many payments. Month ends are kept right (31 Jan, 28 Feb, 31 Mar).
• Interest: none; flat_total (a share of the amount for the whole plan, so 10% means pay back 110%); flat_per_period (that share every period on the original amount); or reducing (that share every period on what is still owed, with equal payments). Use POST /v1/installments/preview to see the dated payments and the total before you create anything.

curl -X POST https://api.identifyorg.com/v1/installments/plans \
  -H "X-IdentifyOrg-Key: io_live_sk_xxxxxxxx" -H "Content-Type: application/json" \
  -d '{
    "reference": "LOAN-2041",
    "title": "Business loan",
    "payer": { "name": "Ada Obi", "email": "ada@example.com", "phone": "08031234567" },
    "amount": 120000,
    "interest_mode": "flat_total",
    "interest_rate": 10,
    "frequency": "weekly",
    "every": 1,
    "count": 12,
    "start_date": "2026-12-01",
    "whatsapp_channel_id": "optional-approved-number-id"
  }'

{
  "id": "plan_9c1d...",
  "status": "active",
  "total_due": 132000.0,
  "interest_total": 12000.0,
  "balance": 132000.0,
  "payments": [
    { "number": 1, "due_date": "2026-12-01", "amount_due": 11000.0, "amount_paid": 0.0, "status": "upcoming" }
  ],
  "page_url": "https://identifyorg.com/plan/Hs3...",   // send this to your customer
  "duplicate": false
}

Send your own reference (your loan or member number): sending it again returns the same plan and never makes a second one.

How your customer pays

• Their page (page_url): the schedule, what is paid and what is left. They pay any amount by card, bank transfer or USSD.
• Their own account number (account_number: true): a bank transfer to it is added to their plan automatically. Live accounts need their BVN or NIN.
• Cash or a transfer to you: record it with POST /v1/installments/plans/{id}/payments (or from the dashboard).
• A saved card: see below.

Every payment, whichever way it arrives, clears the oldest unpaid payment first. A part-payment is recorded and the payment stays open until it is covered; extra money moves on to the next one:

Payment 1 is ₦10,000. Your customer pays ₦5,000, then ₦4,000, then ₦3,000:

₦5,000  ->  payment 1: paid ₦5,000, ₦5,000 left      (status: part-paid; the plan is not complete)
₦4,000  ->  payment 1: paid ₦9,000, ₦1,000 left      (still part-paid)
₦3,000  ->  payment 1: cleared (₦1,000)  and  payment 2: ₦2,000 paid   (the rest carries on)

If your customer pays more than the whole plan, the extra is shown as overpaid for you to return. Recording the same receipt twice counts once.

Automatic card payments

When your customer pays by card from their page they can tick a box agreeing to save the card. We keep only the payment provider's token for the card, encrypted, never the card number. On each due date we charge what is due; if it fails we try again on the next days (up to 4 tries per payment), tell your customer, and send you installment.debit_failed. They can remove the card on their page at any time, and so can you.

• Automatic payments use bank cards only (debit or credit): when your customer ticks the box, the payment page offers card only.
• Saved-card charging has to be switched on for our account with the card network first, so it may not be available for every card or bank yet. If a card cannot be saved, you get plan.card_not_saved and the plan carries on with links, transfers and recorded payments.
• Some banks or providers ask the card holder to confirm a repeat charge. When that happens we send your customer a confirmation link instead of failing the payment.
• Not every card can be reused. Always keep payment links and account numbers available as well.
• You are responsible for the agreement with your borrower or member, and for holding any licence your business needs to lend or collect contributions.

One link for many people

Make a link with POST /v1/installments/links (or from Take payments, then Take installment payments, in your dashboard) and share it anywhere. Each customer opens it, picks an amount and a repayment plan from the choices you set, enters their details and starts their own plan, with their own page to pay from.

• Check contacts first: turn on verify_phone and verify_email and each customer confirms a code sent to them before the plan starts. You pay for each code.
• Your own checks: POST /v1/installments/contact-checks sends a code to a phone or email for you to confirm yourself, and GET /v1/installments/people lists people already checked in your Verification Suite.
• Stay in control: daily_limit caps new plans a day, and you can turn a link off at any time with POST /v1/installments/links/{id}/active.

Our charge on each payment

Payments toward a plan have their own small charge, separate from the normal collection fee, which is unchanged for everything else. It is worked out on each payment's own amount, so a ₦5,000 plan split into two ₦2,500 payments pays the charge twice. Our standard schedule: 1% on a payment under ₦1,000; ₦200 from ₦1,000 to ₦5,000; ₦500 above ₦5,000 up to ₦10,999; ₦800 from ₦11,000 to ₦20,000; ₦1,200 above ₦20,000. You always see the current schedule under Take Payments, Fees.

• You choose who pays it, per plan, with fee_bearer: merchant (the default) keeps it out of what you receive; payer adds it on top of each payment and shows your customer a breakdown (the payment, the service charge, the total) before they pay. Their plan is credited the payment alone.
• Money you record yourself (cash) has no charge. A transfer into a person's own account number always has the charge kept from what you receive, because we cannot add to a bank transfer.
• The preview (POST /v1/installments/preview) shows the charge on every payment, and each payment shows how much of it is the amount and how much is interest.

When you can withdraw the money

Money collected through a plan (and every other payment you collect with us) shows in your balance the moment it is paid, as settling. It can be withdrawn 24 hours after it arrives, and it settles by itself: you do not need to ask. Each payment shows its state in the API (settlement.state: settling, on_hold or available) and when it becomes withdrawable (settlement.available_at). In special cases our team can put a payment on hold while it is checked, for example if the payer reports a problem or the activity needs tracing. A held payment stays visible with the reason, cannot be withdrawn even after 24 hours, and becomes withdrawable as soon as we release it. Every hold and release is recorded with who did it and when.

Reminders and events

Your customer is reminded by email (and on WhatsApp if you link an approved number with whatsapp_channel_id) the day before, on the day, and when a payment is 3 days late. You get webhooks:

installment.payment   money came in; says which payments it went to
installment.paid      one payment is now fully paid
installment.due       a payment is due today
installment.overdue   a payment is 3 days late
installment.debit_failed   the automatic card payment failed
plan.created, plan.completed, plan.card_saved, plan.card_not_saved

Use a test key to try everything with no money: a test card is saved when your customer ticks the box, and the daily run charges it. Money paid into plans settles to your balance like any other payment, less our normal collection fee.