Instalment invoices

Some things are not paid for in one go. A ₦1.8m kitchen fit-out, a term's school fees, a six-week retainer, a wedding booked nine months out. The deal is agreed once and the money arrives in pieces, on terms the two parties settled between themselves.

Most gateways make you rebuild that yourself: your own schedule table, your own balance arithmetic, a fresh payment link every time, and a reconciliation job to work out which transfer belonged to which customer. ZevPay invoices carry the terms, so the invoice itself knows what is owed, what has been paid, and what the customer is allowed to pay next.

This page is the long version. If you only want the field reference, see the Invoice API.

The shape of it

One invoice. Many payments. Each payment is a real transaction that settles on its own, exactly like a standalone checkout, so nothing about your payout reconciliation changes.

Invoice INV-2026-0041          ₦1,800,000
├── Payment 1   ₦600,000   paid 3 Mar   settled 4 Mar
├── Payment 2   ₦600,000   paid 2 Apr   settled 3 Apr
└── Payment 3   ₦600,000   paid 1 May   settled 2 May

The customer opens the same link every time. They see what they have already paid, choose what to pay now, and pay it. You get a webhook per payment and a settlement per payment.

A worked example

A furniture maker takes a ₦1.8m commission. The terms are a third up front, and the customer can pay the rest however they like until delivery.

1. Create the invoice with the terms on it

curl -X POST https://api.zevpaycheckout.com/v1/checkout/invoice \
  -H "x-api-key: sk_live_your_secret_key" \
  -H "Content-Type: application/json" \
  -d '{
    "customer_name": "Adaeze Nwosu",
    "customer_email": "adaeze@example.com",
    "due_date": "2026-06-30T00:00:00Z",
    "line_items": [
      { "description": "Walnut dining set, 8 seater", "quantity": 1, "unit_price": 180000000 }
    ],
    "allow_partial_payments": true,
    "minimum_initial_payment": 60000000,
    "subsequent_payment_rule": "flexible",
    "due_date_action": "keep_collecting"
  }'

Amounts are in kobo throughout, so 180000000 is ₦1,800,000 and 60000000 is ₦600,000.

Those four fields are the whole policy:

Field	What it does
allow_partial_payments	Turns instalments on. Without it the invoice is pay-in-full.
minimum_initial_payment	The deposit. The first payment must be at least this. They may pay more.
subsequent_payment_rule	flexible lets them pay any amount afterwards. full_balance means the rest must come in one payment.
due_date_action	What happens when the due date passes. Defaults to keep_collecting.

2. Send it

curl -X POST https://api.zevpaycheckout.com/v1/checkout/invoice/{public_id}/send \
  -H "x-api-key: sk_live_your_secret_key"

The customer gets an email with a link to the invoice page.

3. The customer pays what they agreed

On an instalment invoice the page asks how much they want to pay before it offers payment methods. It is pre-filled with the full balance, because most people pay it all, and it states the rule before they type rather than rejecting them after.

If they try to pay ₦400,000 against a ₦600,000 deposit, the page tells them the first payment must be at least ₦600,000. The server enforces the same rule, so editing the request achieves nothing.

4. You get a webhook per payment

{
  "event": "invoice.payment_received",
  "data": {
    "invoice_public_id": "inv_8Kd93mQx2Lp",
    "invoice_number": "INV-2026-0041",
    "payment_id": "ipy_4Rm72nBw9Tc",
    "amount": 60000000,
    "amount_paid": 60000000,
    "amount_outstanding": 120000000,
    "is_partial": true,
    "is_fully_paid": false,
    "reference": "ZVP-CKOTX-9f2a1c",
    "paid_at": "2026-03-03T11:24:08.000Z"
  }
}

Fulfil on is_fully_paid, not on the event arriving. On an instalment invoice invoice.payment_received fires every time, and the first one is not the last one.

5. Reconcile

Each instalment is its own settled transaction. To see them:

curl https://api.zevpaycheckout.com/v1/checkout/invoice/{public_id}/payments \
  -H "x-api-key: sk_live_your_secret_key"

{
  "invoice": {
    "public_id": "inv_8Kd93mQx2Lp",
    "status": "partial",
    "total": 180000000,
    "amount_paid": 120000000,
    "amount_outstanding": 60000000,
    "collecting": true
  },
  "payments": [
    {
      "payment_id": "ipy_7Bn21kFd5Qa",
      "amount": 60000000,
      "paid_at": "2026-04-02T09:15:44.000Z",
      "payer_name": "ADAEZE NWOSU",
      "payment_method": "bank_transfer",
      "transaction": {
        "reference": "ZVP-CKOTX-3d81be",
        "gross_amount": 60000000,
        "fees": 200000,
        "net_amount": 59800000,
        "settlement_state": "paid_out",
        "settled_at": "2026-04-03T12:00:00.000Z"
      }
    }
  ]
}

Every payment carries its own reference, fee, net and settlement state. Verify a single one with GET /v1/checkout/invoice/{public_id}/payments/{payment_id}.

Choosing your terms

A deposit, then the balance in one go

The common shape for work with a delivery date. A third up front, the rest before it ships.

{
  "allow_partial_payments": true,
  "minimum_initial_payment": 60000000,
  "subsequent_payment_rule": "full_balance"
}

After the deposit the page stops offering a choice and asks for the balance.

Pay it down however you like

School fees, a retainer, anything where you care that it clears, not how.

{
  "allow_partial_payments": true,
  "subsequent_payment_rule": "flexible"
}

No minimum, any amount, as many payments as it takes.

A floor on every payment

There is deliberately no per-payment minimum beyond the first. If you need one, set minimum_initial_payment and full_balance, which gives you exactly two payments of known size. Chasing twelve ₦5,000 payments costs more in reconciliation than it collects.

Changing your mind

Terms are not frozen at creation. A customer asking to pay in instalments halfway through is a normal conversation, and re-issuing the invoice would lose its history and its link.

This works on invoices you have already sent, and on part-paid ones. What stays fixed after sending is the money itself: line items, tax and the customer. Everything about how it gets paid, including the due date, remains yours to change.

Relaxing or tightening the balance rule mid-invoice

The most common version of this: you asked for the balance in one payment, the customer comes back and says they cannot manage it, and you agree to let them pay it down.

curl -X PATCH https://api.zevpaycheckout.com/v1/checkout/invoice/{public_id} \
  -H "x-api-key: sk_live_your_secret_key" \
  -d '{ "subsequent_payment_rule": "flexible" }'

It takes effect on their next payment. On a ₦1.8m invoice with ₦600,000 already paid:

Rule	What the customer may pay next
full_balance	Exactly ₦1,200,000
flexible	Any amount up to ₦1,200,000

The reverse works too. Tighten a flexible invoice to full_balance and the next payment must clear whatever is outstanding at that moment, not the original balance.

Two things hold either way. The ceiling is always the outstanding balance, so no rule lets a customer overpay. And minimum_initial_payment cannot be changed once the first payment has landed, because a deposit rule cannot apply retroactively to money already taken.

If the invoice was created with allow_partial_payments: false, send both fields to open it up:

-d '{ "allow_partial_payments": true, "subsequent_payment_rule": "flexible" }'

Every one of these changes lands on the activity log with the fields that moved, so what was agreed and when survives the conversation.

curl -X PATCH https://api.zevpaycheckout.com/v1/checkout/invoice/{public_id} \
  -H "x-api-key: sk_live_your_secret_key" \
  -d '{ "subsequent_payment_rule": "flexible" }'

Every change is recorded on the invoice's activity log with the fields that changed, so the record of what was agreed and when survives the conversation.

Extending a due date

curl -X PATCH https://api.zevpaycheckout.com/v1/checkout/invoice/{public_id} \
  -H "x-api-key: sk_live_your_secret_key" \
  -d '{ "due_date": "2026-07-31T00:00:00Z" }'

An invoice that had already gone overdue returns to sent, or partial if part of it is paid, the moment the new date is in the future. Your customer stops seeing a past-due invoice straight away.

The old and new dates are recorded on the activity log, so the record of when the terms moved survives the conversation that moved them.

Chasing payment

curl -X POST https://api.zevpaycheckout.com/v1/checkout/invoice/{public_id}/remind \
  -H "x-api-key: sk_live_your_secret_key"

Re-sends the invoice email. On a part-paid invoice the reminder chases the outstanding balance, not the original total, so it never reads as a demand for money already paid.

Rate limited to one reminder an hour per invoice. This endpoint points at your customer's inbox, and a loop in your automation is a loop in their mailbox.

Stopping collection

Two different things, for two different situations.

Pause when you want to stop taking money but keep the invoice alive. A dispute, a delivery problem, a customer who asked you to hold. The invoice keeps its status and its history, the customer can still open the page and see everything they have paid, and you can resume without re-issuing anything.

curl -X POST https://api.zevpaycheckout.com/v1/checkout/invoice/{public_id}/pause \
  -H "x-api-key: sk_live_your_secret_key" \
  -d '{ "reason": "On hold while we agree the revised spec" }'

The reason is shown to the customer. Resume with POST /{public_id}/resume.

Cancel when the deal is off. The invoice closes and stops collecting for good. Payments already made stay visible to the customer on the same link, because money they sent you does not disappear when your paperwork does.

curl -X POST https://api.zevpaycheckout.com/v1/checkout/invoice/{public_id}/cancel \
  -H "x-api-key: sk_live_your_secret_key"

Cancelling a part-paid invoice does not refund anything. If you owe the customer money back, refund the specific payment.

What happens at the due date

By default, nothing stops. The invoice moves to overdue and keeps accepting payment, because an overdue invoice is one you still want paid. Closing it would refuse a customer paying a day late, and on an instalment invoice it would strand someone who has already paid a deposit with no way to finish.

If you need a hard stop, say so per invoice:

due_date_action	At the due date
keep_collecting	Default. Status goes overdue, payment still accepted.
pause	Collection stops. The invoice and its history stay visible. Resume any time.
cancel	The invoice closes.

Use pause for a price that expires, cancel for an event that has passed, and the default for everything else.

The activity log

Every invoice keeps an append-only record of what was done to it.

curl https://api.zevpaycheckout.com/v1/checkout/invoice/{public_id}/events \
  -H "x-api-key: sk_live_your_secret_key"

{
  "events": [
    {
      "type": "payment_received",
      "title": "Part payment received",
      "description": "600000.00 received from ADAEZE NWOSU. 1200000.00 still outstanding.",
      "actor": "customer",
      "created_at": "2026-03-03T11:24:08.000Z"
    },
    {
      "type": "policy_changed",
      "title": "Payment terms changed",
      "description": "Changed: subsequentPaymentRule",
      "actor": "api",
      "created_at": "2026-03-01T16:02:11.000Z"
    },
    {
      "type": "sent",
      "title": "Invoice sent to customer",
      "description": "Emailed to adaeze@example.com.",
      "actor": "api",
      "created_at": "2026-03-01T15:58:03.000Z"
    }
  ]
}

actor answers the question that matters when something is disputed: api means your integration did it, dashboard means a person clicked it, system means we did (a due date passing), and customer means the payer.

The same log renders on the invoice detail page in your dashboard.

Webhooks to handle

Event	When
invoice.payment_received	Every payment. Check is_fully_paid before fulfilling.
invoice.paid	The balance reached zero.
invoice.overdue	The due date passed.
invoice.paused / invoice.resumed	Collection stopped or restarted.
invoice.reminder_sent	A reminder went out.
invoice.cancelled	The invoice was closed.

Things worth knowing

Overpayment is refused, not banked. The most a customer can pay is the outstanding balance. Letting someone overpay an invoice creates a refund, not a sale.

The amount is locked once chosen. When a customer says they are paying ₦600,000, the account they are given accepts ₦600,000. They cannot underpay the instalment they just picked, which is the whole point of asking.

Each payment settles separately. Same T+1 cycle, same fee structure, same settlement destination as any other payment on that API key. An instalment invoice does not settle as a lump when it completes.

Partial payments and ZevPay ID. ZevPay ID is customer-initiated and cannot enforce an amount, so it is hidden on invoices that require an exact payment.