Invoices

Create an invoice

Create an invoice for an amount in your settlement currency. Redirect the customer to its hosted checkout URL, or pass pay_with to select a coin up front and drive an embedded checkout yourself.

POST/api/invoicesinvoices:write

Body parameters

Property	Type	Description
amountrequired	string	Invoice amount in your settlement currency, as a decimal string. Must be greater than 0.
durationrequired	enum	How long the invoice stays payable: `15m`, `30m`, `1h`, `6h`, or `24h`.
supported_wallets	string[]	Coin ids the payer may choose (1–50, distinct). Required unless `all_supported_wallets` is true. Discover ids via GET /api/wallets.
all_supported_wallets	boolean	Accept every supported coin. When true, omit supported_wallets.
pay_with	string \| null	A `wallet_network_id` within the invoice's supported coins. When set, the coin is selected as the invoice is created, so the response's `active_payment` already carries the deposit address and quote, a one-request create-and-get-address flow for embedded checkout. Must be an active network (≤50 chars); otherwise 422. Omit it for a multi-coin invoice the payer chooses from later.
reference	string	Your order id (≤255). Recommended for reconciliation.
metadata	object	Flat string map: up to 20 keys, values ≤255 chars.
success_url	string	Where the customer returns after paying (≤255).
cancel_url	string	Where the customer returns if they abandon checkout (≤255).

Request

Send a JSON body with your API key. Include an Idempotency-Key header so network retries never create duplicate invoices.

Response

Returns the Invoice object, including the checkout_url to redirect your customer to. When you send pay_with, active_payment is already populated with the deposit address and expected_value.

With an Idempotency-Key, a repeated request returns the original invoice instead of creating a new one. Create-and-select stays idempotent too.

curl https://test-api.coinfat.com/api/invoices \
  -H "Authorization: Bearer 42|nX9...secret" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: 5f0c7e2a-1c3d-4a9b-8e7f-2b6a1d0c9e88" \
  -d '{
    "amount": "49.99",
    "duration": "1h",
    "supported_wallets": ["btc", "usdt"],
    "reference": "ORDER-10231",
    "metadata": { "order_id": "10231" },
    "success_url": "https://shop.example.com/orders/10231/success",
    "cancel_url": "https://shop.example.com/orders/10231/cancel"
  }'

200 OK

{
  "ulid": "01JZ8Q5F2H7T9K1M3N5P7R9S1U",
  "checkout_url": "https://test.coinfat.com/checkout/01JZ8Q5F2H7T9K1M3N5P7R9S1U",
  "status": "pending",
  "currency": {
    "code": "USD",
    "name": "US Dollar",
    "is_default": true,
    "is_active": true,
    "is_base": false,
    "exchange_rate": 1,
    "exchange_type": "auto"
  },
  "amount": { "amount": "49.99", "currency": "USD", "scale": 2 },
  "supported_wallets": [
    { "id": "btc", "name": "Bitcoin", "symbol": "BTC", "scale": 8 },
    { "id": "usdt", "name": "Tether", "symbol": "USDT", "scale": 6 }
  ],
  "active_payment": null,
  "reference": "ORDER-10231",
  "description": null,
  "customer_email": null,
  "customer_name": null,
  "metadata": { "order_id": "10231" },
  "success_url": "https://shop.example.com/orders/10231/success",
  "cancel_url": "https://shop.example.com/orders/10231/cancel",
  "expires_at": "2026-07-07T15:00:00.000000Z",
  "completed_at": null,
  "canceled_at": null,
  "created_at": "2026-07-07T14:00:00.000000Z",
  "updated_at": "2026-07-07T14:00:00.000000Z"
}