# Invoices

Create an invoice with a hosted payment page, share the link, track payments and cancel, step by step.

## What the invoice API does

An invoice is a request for a fixed amount from a named customer, with a due date and a hosted payment page. The customer pays on the page at payment_link, or by dialling payment_code on USSD, and the money settles into your wallet. The invoices you create through the API are the same invoices you see in the Moolre dashboard.

The API does not send the email, PDF or SMS that the dashboard sends when you create an invoice. You give the customer the payment_link yourself, by whatever channel you use: your own email, a WhatsApp or SMS message, or a screen in your app.

| Step | Endpoint | Result |
| --- | --- | --- |
| Create | Create invoice | invoiceid, payment_link, payment_code |
| Share | Your own channel (SMS, WhatsApp, email) | The customer receives the link |
| Track | Invoice status or List invoices | status: pending, partially_paid, overdue, paid, cancelled |
| Cancel | Cancel invoice | An unpaid invoice stops accepting payment |

## Before you start



- [ ] The private key (a public key is refused), and a wallet that has a collection service (INV09 otherwise).
- [ ] A unique reference per invoice, saved with your own record. It makes creation safe to retry.
- [ ] A customer name and phone number (9 to 15 digits).
- [ ] A due date: today or later, within 2 years.

## Step by step: create and share an invoice



1. Decide the amount. Send either a single amount, or 1 to 50 items of description, quantity and unit amount. Add tax as a percentage if needed: the total is the subtotal times (1 + tax / 100), rounded to the cent.
2. Send Create invoice with accountnumber, currency, invoice_name, customer, the amount or items, due_date and your reference. Add an Idempotency-Key equal to the reference.
3. Read the reply. INV01 is a new invoice; INV02 (with data.replayed true) means the same reference and body already created it. Store invoiceid and payment_link.
4. Send the customer the payment_link (and the payment_code for USSD) in your own message.
5. Wait for the customer to pay, then check the invoice with Invoice status (by invoiceid or reference).

```curl
curl https://api.moolre.com/open/invoice/create \
  -H "Content-Type: application/json" \
  -H "X-API-USER: $MOOLRE_USER" \
  -H "X-API-KEY: $MOOLRE_KEY" \
  -H "Idempotency-Key: INV-1001" \
  -d '{
    "accountnumber": "1000000000001",
    "currency": "GHS",
    "invoice_name": "Term 1 fees",
    "customer": {
      "name": "Ama Mensah",
      "phone": "0240000001"
    },
    "items": [
      {
        "description": "Tuition",
        "quantity": 1,
        "amount": "450.00"
      }
    ],
    "due_date": "2026-12-31",
    "reference": "INV-1001",
    "narration": "Term 1 school fees"
  }'
```

```json
{
  "status": 1,
  "code": "INV01",
  "message": "Invoice created.",
  "data": {
    "invoiceid": "5-1",
    "status": "pending",
    "reference": "INV-1001",
    "invoice_name": "Term 1 fees",
    "currency": "GHS",
    "total": "450.00",
    "amount_paid": "0.00",
    "tax": "0",
    "items": [
      {
        "amount": "450.00",
        "quantity": "1",
        "description": "Tuition"
      }
    ],
    "customer": {
      "name": "Ama Mensah",
      "phone": "0240000001",
      "email": ""
    },
    "due_date": "2026-12-31T23:59:59Z",
    "payment_link": "https://invoice.moolre.com/5-1",
    "payment_code": "*203*0621#",
    "created": "2026-11-15T09:00:00Z"
  },
  "go": null,
  "meta": {
    "requestid": "req_c68f4c66115c26725c796242",
    "notices": []
  }
}
```

- [Create invoice (API reference)](https://docs.moolre.com/api/invoices)

## Invoice states



| status | Meaning | What to do |
| --- | --- | --- |
| pending | Created, unpaid | Wait; remind the customer before the due date |
| partially_paid | A payment smaller than the total has arrived | Check amount_paid against total and ask for the rest |
| overdue | The due date has passed and the invoice is unpaid or part paid. It can still be paid | Chase the customer, or cancel it |
| paid | Fully paid | Mark the bill settled and issue your receipt |
| cancelled | Cancelled: the hosted link no longer works | Create a new invoice with a new reference if needed |

> **Invoice webhooks:** When an invoice created through the API becomes fully paid, Moolre sends one invoice.paid webhook. Part payments send no event, so poll Invoice status (or List invoices with a status filter) to see partially_paid. Dashboard-created invoices do not send the event, and invoice.expired is not sent yet. The sandbox can fire invoice.paid on demand with the trigger endpoint.

## Step by step: handle the invoice.paid webhook

invoice.paid is sent once per invoice, to the wallet callback URL, after the payment has been committed. It is signed like every Moolre webhook (X-Moolre-Signature, X-Moolre-Event: invoice.paid, X-Moolre-Event-Id, which stays the same for the invoice) and retried on the standard schedule.

1. Verify the X-Moolre-Signature header on the raw body, then check the event_id against the events you have already processed.
2. Read data.invoiceid and data.reference. Find your own bill by reference.
3. Check data.status is paid and compare data.amount_paid with data.total and with your bill.
4. Mark the bill paid once (a conditional update from unpaid to paid) and issue the receipt. data.payment_reference is the reference of the collection that paid it, and data.paid_at is the time (ISO 8601, UTC).
5. Answer 2xx quickly. Keep the polling job below as a safety net for part payments and missed events.

```json
{
  "status": 1,
  "code": "INV20",
  "message": "Invoice paid",
  "data": {
    "invoiceid": "5-1",
    "status": "paid",
    "reference": "INV-1001",
    "invoice_name": "Term 1 fees",
    "currency": "GHS",
    "total": "450.00",
    "amount_paid": "450.00",
    "payment_reference": "a1b2c3d4-e5f6-4711-8899-aabbccddeeff",
    "customer": {
      "name": "Ama Mensah",
      "phone": "0240000001",
      "email": ""
    },
    "payment_link": "https://invoice.moolre.com/5-1",
    "payment_code": "*203*0621#",
    "metadata": null,
    "accountnumber": "1000000000001",
    "paid_at": "2026-11-15T10:21:00Z"
  },
  "go": null,
  "event_id": "evt_0123456789abcdef01234567",
  "event": "invoice.paid",
  "created": "2026-11-15T10:21:01Z",
  "meta": {
    "notices": []
  }
}
```

> **Not every payment sends an event:** Part payments, dashboard-created invoices and expiry send nothing. That is why the polling job stays: it finds partially_paid and overdue invoices that no webhook announces.

- [Webhooks and callbacks](https://docs.moolre.com/guides/webhooks-and-callbacks)

## Step by step: find out who has paid



1. Run a job every few minutes that calls List invoices with status pending, partially_paid and overdue (this also catches anything a webhook missed).
2. For each invoice that now reads paid, mark your own record paid (once) and issue the receipt.
3. For an invoice that reads partially_paid, store amount_paid and ask for the balance.
4. Page through long lists with limit (1 to 100) and starting_after (send next_cursor from the previous page) until has_more is false.

```curl
curl https://api.moolre.com/open/invoice/list \
  -H "Content-Type: application/json" \
  -H "X-API-USER: $MOOLRE_USER" \
  -H "X-API-KEY: $MOOLRE_KEY" \
  -d '{
    "accountnumber": "1000000000001",
    "status": "pending",
    "limit": 50
  }'
```

```json
{
  "status": 1,
  "code": "INV14",
  "message": "Invoices found.",
  "data": {
    "invoices": [
      {
        "invoiceid": "5-1",
        "status": "pending",
        "reference": "INV-1001",
        "invoice_name": "Term 1 fees",
        "currency": "GHS",
        "total": "450.00",
        "amount_paid": "0.00",
        "tax": "0",
        "items": [
          {
            "amount": "450.00",
            "quantity": "1",
            "description": "Tuition"
          }
        ],
        "customer": {
          "name": "Ama Mensah",
          "phone": "0240000001",
          "email": ""
        },
        "due_date": "2026-12-31T23:59:59Z",
        "payment_link": "https://invoice.moolre.com/5-1",
        "payment_code": "*203*0621#",
        "created": "2026-11-15T09:00:00Z"
      }
    ],
    "has_more": false,
    "next_cursor": null
  },
  "go": null,
  "meta": {
    "requestid": "req_c68f4c66115c26725c796242",
    "notices": []
  }
}
```

## Step by step: cancel an invoice



1. Call Cancel invoice with the invoiceid. INV17 means it is cancelled (also when it was already cancelled).
2. If the reply is INV18, the invoice is paid or has payments and cannot be cancelled. The reply carries the invoice so you can see how much was paid.

> **Cancelling does not return money:** A cancelled invoice stops accepting new payments. Money already paid stays in your wallet. If you need to give a customer money back, send them a payout with Initiate Transfer and keep your own record linking it to the invoice.

## Common errors and fixes



| Code | Meaning | Fix |
| --- | --- | --- |
| INV03 | A field is missing or invalid (accountnumber, invoice_name, narration, metadata, status filter, invoiceid) | Read error.fields |
| INV04 | Customer invalid | Send name (required, at most 100 characters), phone (9 to 15 digits) and optional email |
| INV05 | Amount, items or tax invalid | Send either amount or items, and tax from 0 to 100 |
| INV06 | due_date missing, malformed, in the past or too far | Send YYYY-MM-DD or YYYY-MM-DD HH:MM:SS (UTC), up to 2 years ahead |
| INV07 | reference reused for a different invoice | Use a new reference, or resend the original body to get the original invoice |
| INV08, INV09 | Currency does not match the wallet, or no collection service on the wallet | Send the wallet currency; create a collection service in the app |
| INV12 | Invoice not found | Check invoiceid or reference |
| INV13 | A public key was used | Use the private key |
| INV18 | The invoice has payments and cannot be cancelled | Leave it, or handle the refund yourself outside the invoice |

## Checklist



- [ ] Every invoice has your own unique reference and an Idempotency-Key.
- [ ] You send the payment_link yourself and store the invoiceid.
- [ ] The invoice.paid webhook is verified and deduped, and a polling job handles partial payments and missed events.
- [ ] You cancel invoices you no longer want paid.
- [ ] You reconcile paid invoices with the account statement.

- [Fee collection with invoices (playbook)](https://docs.moolre.com/use-cases/fee-collection)
- [Statements and pagination](https://docs.moolre.com/guides/statements)
