# Invoices Invoices is Kwik Nkap's billing product. From the dashboard you create an itemized bill for a named customer, publish it, send a PDF over Email or WhatsApp, and let the customer settle it by MTN or Orange Mobile Money on a hosted pay page that needs no login. Payment is collected through the same Mobile Money pipeline that backs core Payments, and the invoice reconciles itself as money arrives. :::note Invoices can be created **either** in the dashboard ([app.kwiknkap.com](https://app.kwiknkap.com)) **or** through the public API with your `kn_sk_test_` / `kn_sk_live_` key — see [Invoices in the API reference](/en/api/invoices). The API covers create, retrieve, list, publish, send, cancel, and fetching the PDF. Two things to know when you integrate. Sending needs the separate `invoices:send` scope, because it puts your brand in front of a recipient you choose. And every response carries `checkout_url`, the page the customer pays on — store that rather than building the URL yourself. The Mobile Money collection an invoice triggers is the same primitive documented in [Payments & Collections](/en/payments/overview). ::: ## What an invoice is An invoice is a structured bill addressed to one customer. It carries: - Customer details: name, email, phone number. - One or more line items, each with a name, unit price, and quantity. - An optional discount, applied as a percentage. - A due date and free-form notes. The customer never needs a Kwik Nkap account. They open a public pay link, review the itemized breakdown and the amount due, and pay the remaining balance with Mobile Money. An invoice can be settled in one payment or across several partial payments until it is fully paid. ## The invoice lifecycle An invoice moves through five stages. B[Publish reserves stock UNPAID] B --> C[Send Email or WhatsApp] C --> D[Customer pays by Mobile Money] D --> E[PARTIAL balance still owed] D --> F[PAID reconciled] E --> D `} /> | Stage | What happens | | --- | --- | | Draft | You create the invoice and edit its items, customer, discount, due date, and notes. | | Publish | Totals are locked in, the invoice becomes payable, and matching inventory stock is reserved. | | Send | A PDF copy is generated and delivered over Email and/or WhatsApp (optional). | | Pay | The customer opens the public pay link and pays the remaining amount by Mobile Money. | | Reconcile | When the collection settles, the invoice is credited and marked `PARTIAL` or `PAID`, and reserved inventory is confirmed and deducted. | A new invoice created with no line items is saved as a `DRAFT`. If it already has items at creation time, it is saved as `UNPAID` and its items are synced into your business inventory catalog. ## Line items, discounts, and totals Each line item has a name, a price, and a quantity. The subtotal is the sum of every line item. An optional discount percentage is applied on top, and the result is the total amount due. You can edit a draft freely: add items, remove items, or replace the entire item set along with the customer, discount, notes, and due date. Totals recompute on every change. :::caution A `PAID` invoice cannot be edited. Lock down the items and totals before the invoice is fully settled. ::: ## Publishing and inventory reservation Publishing finalizes an invoice. It is allowed only from `DRAFT`, requires at least one line item, and every item must have a positive price. On publish: - The status moves from `DRAFT` to `UNPAID`. - `totalAmount` and `remainingAmount` are finalized. - Matching inventory stock is reserved for 7 days. The reservation holds stock for the items on the invoice so it cannot be double-sold while the customer is paying. When the invoice is paid, the reservation is confirmed and the stock is deducted. If the invoice is never paid, the reservation expires. ## Sending over Email and WhatsApp Sending an invoice generates a PDF and delivers it to the customer over `EMAIL`, `WHATSAPP`, or `BOTH`. Publishing can forward the invoice in the same step, or you can send it separately afterwards. :::info WhatsApp delivery goes through your own connected WhatsApp session when available, with a fallback to the system session. ::: Sending is optional. You can also just share the public pay link directly. The dashboard shows the link with copy and open controls for any invoice that is not a draft, not paid, and not cancelled. ## The public pay link and customer pay page Every published invoice has a hosted pay page at `payment-portal /invoices/{invoiceId}`. The customer opens it with no authentication and sees: - Your merchant information. - The line items, subtotal, and discount. - Any amount already paid. - The Kwik Nkap service fee. - The amount due. To pay, the customer picks MTN or Orange, enters their phone number, and confirms payment of the remaining amount. A Mobile Money prompt arrives on their handset, and they approve the debit with their PIN. ## Payment and settlement When the customer confirms, a collection is initiated against your business. Money moves from the customer's MTN or Orange Mobile Money wallet, and an `InvoicePayment` row records the attempt as `PENDING`. A Kwik Nkap service fee is shown to the payer on top of the amount due and is calculated on the pay page. ### Partial vs complete payment Each payment attempt is classified: - `COMPLETE` if it clears the full remaining balance. - `PARTIAL` if it pays only part of the remaining balance. This is what lets an invoice be settled across several payments. Different attempts draw down the same `remainingAmount` until it reaches zero. When the collection settles, an idempotent `OnPaymentCompleted` step runs: - Marks the `InvoicePayment` as `SUCCESS` or `FAILED`. - Increments `paidAmount` and recomputes `remainingAmount`. - Sets the invoice to `PARTIAL` (balance still owed) or `PAID` (fully settled). - Confirms and deducts the reserved inventory. A failed collection leaves the invoice unpaid. Net collected funds accrue to your Kwik Nkap business balance through the standard collection settlement path, the same as core Payments. ## Invoice statuses | Status | Meaning | | --- | --- | | `DRAFT` | Created without items, still editable, not yet payable. | | `UNPAID` | Published (or created with items), payable, nothing collected yet. | | `PARTIAL` | At least one payment has cleared, but a balance is still owed. | | `PAID` | Fully settled. No further editing or payment. | | `PAST_DUE` | Unpaid or partial past its due date. | | `CANCELLED` | Voided by the merchant; no longer payable. | :::note A daily UTC cron sweeps invoices that are still unpaid or partial past their due date into `PAST_DUE`. This transition is automatic. ::: ## PDF receipts When an invoice is sent, Kwik Nkap generates a PDF of the itemized bill and delivers it to the customer over Email or WhatsApp. The PDF is also downloadable from the invoice detail view in the dashboard, so you can keep a record or re-send it at any time. ## Cancelling and deleting You can cancel an invoice to void it, which moves it to `CANCELLED` and removes it from the payable set. Drafts and invoices that have never collected can be deleted outright. A `PAID` invoice is locked and retained as a settled record. ## Where this lives Invoices is a dashboard product. Create and manage invoices at [app.kwiknkap.com](https://app.kwiknkap.com). The customer pay page is hosted on the public payment portal and needs no login. If you want to collect Mobile Money payments programmatically today, use the public Payments API documented in [Payments & Collections](/en/payments/overview). For hosted, no-code billing of a single amount rather than an itemized bill, see [Payment links](/en/products/payment-links).