> For the complete documentation index, see [llms.txt](https://docs.omypayments.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.omypayments.com/api/api-endpoints/invoices.md).

# Invoices

Charge your customers in crypto. You create an invoice for an amount, we give you a payment page and an address to pay to, and you learn about the payment through polling or callbacks. This page documents the HTTP endpoints you'll call from your backend. Authentication and the error-envelope format follow the public API style.

> **Base URL**: `https://api.omypayments.com`\
> **Version**: `v2` for creating invoices, `v1` for reading them (paths below say which)\
> **Auth**: add your API key in the header: `apiKey: <yourApiKey>`\
> **Permission**: the API key must have the **invoice** permission enabled, otherwise requests are rejected with `403 Forbidden`.

**Two ways to price an invoice**

* `create-invoice` - you name the amount **in USD cents**, we convert it to crypto at the current rate when the customer picks an asset. Use this when your prices are in fiat.
* `create-invoice-by-crypto` - you name the amount **in the token's minimal units**, and that exact amount is what the customer pays. Use this when you're billing in crypto.

**Prerequisites**

* Amounts are never floating-point. USD is passed in **cents** (`"1050"` = $10.50); crypto is passed in the token's **minimal units** (an integer string, no decimal point - for a token with 6 decimals, 100 tokens = `"100000000"`). Use `crypto.decimals` from the Assets section to convert.
* At least one asset must be active on your account before you can be paid — see Assets.
* The customer may choose the asset on the payment page, or you may fix it at creation time. An invoice created without an asset stays payable until someone picks one.

**Typical flow**

1. `create-invoice` or `create-invoice-by-crypto` → you get an invoice id and a payment page link.
2. Send the customer to the payment page.
3. Track the result with `invoice-info`, the invoices list, or callbacks. Callbacks are the recommended way - no polling.

**Invoice statuses**

| Status     | Meaning                                                                   |
| ---------- | ------------------------------------------------------------------------- |
| `new`      | Invoice created, nothing received yet.                                    |
| `pending`  | A payment was detected and is awaiting confirmations.                     |
| `finished` | Paid in full and credited to your asset balance.                          |
| `rejected` | Expired or declined without being paid.                                   |
| `frozen`   | Held for a compliance check; funds are not credited until it is resolved. |
| `refunded` | The received amount was sent back to the payer.                           |

The full lifecycle, including partial and late payments, is described in Invoice Statuses.

**Fees**

Every invoice response carries a `fee` object describing what we charged you. Invoices have no network fee — the payer covers the on-chain cost of sending, so `fee.network` is always `null` for this entity.

***