---
title: Invoices
description: Send a bill the customer pays later from any MoMo channel, and see it in the ledger when it's paid.
---

An invoice is a bill for a set amount that a customer pays in their own time, from any MoMo channel, before it expires. Use it for school fees, utility bills and anything that isn't paid on the spot.

:::note
MTN enables invoices per merchant contract. If yours doesn't include them, creating one fails with a `NOT_ALLOWED` reason.
:::

## Create one

```bash
curl -X POST https://api.razpay.razonetix.com/v1/invoices \
  -H "Authorization: Bearer $RAZPAY_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "external_reference": "fees-term2-0042",
    "provider": "momo",
    "amount": 1500.00,
    "currency": "SZL",
    "phone_number": "76123456",
    "description": "Term 2 school fees",
    "validity_seconds": 1209600
  }'
```

`validity_seconds` is how long it can be paid (here, two weeks). The response includes MTN's `payment_reference` once MTN assigns it; share it with the customer if they pay through a channel that asks for one.

## When it's paid

The invoice becomes `paid` and RazPay writes a **collection** to the ledger with the invoice's `external_reference`, so invoice income shows up with your other payments. You get `invoice.paid`, carrying both the invoice and that transaction.

Because the paid invoice takes that reference in the ledger, an invoice's `external_reference` can't already be used by a transaction.

## Cancel one

Cancel an open invoice with [`DELETE /invoices/{reference}`](/docs/api/cancel-invoice), or from **Invoices** in the dashboard. RazPay checks it with MTN first, so one that was paid a moment ago is recorded as paid, not cancelled.

## Statuses

| Status | Meaning |
| --- | --- |
| `pending` | Open; waiting to be paid. |
| `paid` | Paid. The collection is in the ledger. |
| `failed` | MTN failed it. See `failure_reason`. |
| `cancelled` | You cancelled it. |
| `expired` | Not paid before it expired. |

MTN notifies RazPay when an invoice changes, and RazPay re-checks open invoices every few minutes as a backup.