Invoices

The Invoice object

An invoice represents a single payment request in your settlement currency, with a hosted checkout URL and a lifecycle you track by webhook or polling.

Attributes

Shared types — money: amount, currency (code string), and scale; coin: amount and wallet (the coin id); datetime: an ISO-8601 string.

Property	Type	Description
ulid	string	The invoice id. Use it to retrieve the invoice.
checkout_url	string (uri)	Hosted checkout URL. Redirect your customer here to pay.
status	enum	`pending`, `completed`, `expired`, or `canceled`.
currency	Currency	Your settlement currency: the currency the amount is priced in.
amount	money	The invoice amount: an object with amount, currency (the code string), and scale.
supported_wallets	Wallet[]	The coins you allowed for this invoice.
active_payment	Payment \| null	The payer's selected-coin payment once chosen. A redirect integration can ignore it.
reference	string \| null	Your order reference, echoed back for reconciliation.
description	string \| null	Your invoice description.
customer_email	string \| null	The customer's email.
customer_name	string \| null	The customer's name.
metadata	object \| null	Your flat string map, echoed back.
success_url	string \| null	Where the customer returns after paying.
cancel_url	string \| null	Where the customer returns if they abandon checkout.
expires_at	datetime	When the pending invoice expires.
completed_at	datetime \| null	Set when the invoice is paid in full.
canceled_at	datetime \| null	Set when the invoice is canceled.
created_at	datetime	When the invoice was created.
updated_at	datetime	When the invoice last changed.

API-key responses do not include the policy object (dashboard-only capability hints). Authorization is enforced server-side and surfaced through HTTP status codes. Never depend on policy in an integration.

The Payment object

active_payment holds the payer's selected-coin payment once they pick a coin at checkout. A redirect integration can ignore it and rely on webhooks for the final status.

Property	Type	Description
ulid	string	The payment id.
status	enum	Lifecycle status of the selected-coin payment.
wallet	Wallet	The coin the customer chose to pay in.
wallet_network	WalletNetwork	The network the payment is made on.
address	string \| null	The pay-to address shown at checkout.
deposit_uri	string \| null	A chain-correct, wallet-scannable payment URI pre-filled with the address and expected amount, the content to encode in a QR. `null` until a coin is selected; a bare address on chains without a URI standard.
qr_code_url	string (uri) \| null	A ready-made QR image URL that already encodes `deposit_uri`. `null` when `deposit_uri` is. A backend-hosted convenience. Prefer generating your own QR from `deposit_uri`.
expected_value	coin	The coin amount the customer must send.
received_value	coin	The coin amount received so far.
overpaid	boolean	Whether more than expected was received.
overpaid_value	coin	The amount received above the expected value.
detected_at	datetime \| null	When the payment was first detected on-chain.
rate_expires_at	datetime	When the locked exchange rate expires.
fee_value	coin	The network fee applied to the payment.

Example

Invoice

{
  "ulid": "01JZ8Q5F2H7T9K1M3N5P7R9S1U",
  "checkout_url": "https://coinfat.com/checkout/01JZ8Q5F2H7T9K1M3N5P7R9S1U",
  "status": "completed",
  "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 }
  ],
  "active_payment": {
    "ulid": "01JZ8QN0P2R4T6V8X0Z2B4D6F8",
    "status": "completed",
    "wallet": { "id": "btc", "name": "Bitcoin", "symbol": "BTC", "scale": 8 },
    "wallet_network": { "id": "bitcoin", "name": "Bitcoin" },
    "address": "bc1qxy2kgdygjrsqtzq2n0yrf2493p83kkfjhx0wlh",
    "deposit_uri": "bitcoin:bc1qxy2kgdygjrsqtzq2n0yrf2493p83kkfjhx0wlh?amount=0.00075",
    "qr_code_url": "https://api.qrserver.com/v1/create-qr-code/?data=bitcoin%3Abc1qxy2kgdygjrsqtzq2n0yrf2493p83kkfjhx0wlh%3Famount%3D0.00075",
    "expected_value": { "amount": "0.00075", "wallet": "btc" },
    "received_value": { "amount": "0.00075", "wallet": "btc" },
    "overpaid": false,
    "overpaid_value": { "amount": "0", "wallet": "btc" },
    "detected_at": "2026-07-07T14:20:00.000000Z",
    "rate_expires_at": "2026-07-07T14:30:00.000000Z",
    "fee_value": { "amount": "0.00001", "wallet": "btc" }
  },
  "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": "2026-07-07T14:20:05.000000Z",
  "canceled_at": null,
  "created_at": "2026-07-07T14:00:00.000000Z",
  "updated_at": "2026-07-07T14:20:05.000000Z"
}