Invoices

An invoice is the core object in Muamla. It represents an amount to collect and provides a hosted page (url) where the customer pays from their bank wallet. All amounts are integers in the smallest MRU unit (1 MRU = 100).

Create an invoice

POST /v1/invoices with your secret key (HTTP Basic — key as the username, empty password). The endpoint accepts form-encoded or JSON bodies. Only amount and description are required.

bash

curl https://app.muamla.org/v1/invoices \
  -u sk_test_your_key: \
  -d "amount=500000" \
  -d "description=Order #1024" \
  -d "currency=MRU" \
  -d "callback_url=https://example.com/webhooks/muamla" \
  -d "success_url=https://example.com/thanks" \
  -d "expired_at=2026-07-01T00:00:00Z"

Request fields

Field	Type	Required	Description
`amount`	integer	Yes	Smallest MRU unit, ≥ 100 (e.g. 500000 = 5,000 MRU).
`description`	string	Yes	Shown to the customer on the hosted page.
`currency`	string	No	Defaults to `MRU` (the only supported currency today).
`callback_url`	uri	No	Receives signed webhook events for this invoice. See Webhooks.
`success_url`	uri	No	Where the customer is sent after a successful payment.
`back_url`	uri	No	Where the customer is sent if they go back / cancel.
`expired_at`	timestamp	No	ISO-8601. Payment is blocked after this time.
`metadata`	object	No	Custom key/value pairs echoed back on the invoice (JSON bodies only).
`given_id`	string	No	Idempotency — set the invoice id yourself. Sending the same `given_id` again returns the existing invoice instead of creating a duplicate.

Response (201 Created)

json

{
  "id": "inv_8x2K9aFqR3mB7nZ1",
  "status": "initiated",
  "amount": 500000,
  "currency": "MRU",
  "amount_format": "5,000 MRU",
  "description": "Order #1024",
  "reference": "MR-KSIEYR",
  "url": "https://app.muamla.org/pay/inv_8x2K9aFqR3mB7nZ1",
  "metadata": {},
  "expired_at": "2026-07-01T00:00:00.000Z",
  "created_at": "2026-06-29T19:00:00.000Z",
  "updated_at": "2026-06-29T19:00:00.000Z"
}

url — the hosted checkout page. Redirect the customer here, or share it as a payment link.
reference — the payment reference the customer uses inside their wallet.

Retrieve an invoice

bash

curl https://app.muamla.org/v1/invoices/inv_8x2K9aFqR3mB7nZ1 \
  -u sk_test_your_key:

Returns the same invoice object. Use this to poll status if you aren't using webhooks.

List invoices

bash

curl https://app.muamla.org/v1/invoices -u sk_test_your_key:

json

{ "data": [ { "id": "inv_…", "status": "verified", "amount": 500000, "…": "…" } ] }

Invoice statuses

Status	Meaning
`initiated`	Created, awaiting payment.
`verified`	The transfer was confirmed with the bank — safe to fulfil.
`failed`	Verification failed (wrong reference, no matching transfer).
`expired`	Passed its `expired_at` before being paid.
`canceled`	Canceled by the merchant.
`refunded`	A verified payment was refunded (planned).

Next: see Payment & verification for how the customer pays and how an invoice becomes verified.