For the complete documentation index, see llms.txt. This page is also available as Markdown.

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.


Last updated