Create an invoice

POSTcURL

curl -X POST https://api.satlane.com/v1/invoices \
  -H "Authorization: Bearer sl_test_XXX" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: order-123-attempt-1" \
  -d '{
    "amount": 49.99,
    "currency": "USD",
    "order_ref": "ORD-12345",
    "callback_url": "https://yourshop.com/webhooks/satlane",
    "success_url": "https://yourshop.com/orders/ORD-12345/thanks",
    "buyer_email": "buyer@example.com",
    "expires_in_minutes": 15,
    "metadata": { "cart_id": "abc123" }
  }'

Always send an Idempotency-Key on create. We cache the response for 24 hours per key so retries after a network blip return the same invoice instead of creating duplicates.

Request fields

Field	Type	Required	Notes
`amount`	number	one of	Fiat amount. We lock a BTC/USD rate and convert to sats.
`currency`	string	one of	Must be `"USD"` today.
`amount_sats`	string	one of	Skip fiat conversion; charge exact sats (digits only).
`order_ref`	string	optional	Your internal order ID. Max 255 chars.
`callback_url`	string	optional	Per-invoice webhook URL (overrides store-level endpoints).
`success_url`	string	optional	Hosted checkout redirects here after payment.
`buyer_email`	string	optional	Buyer email for receipts / support.
`expires_in_minutes`	int	optional	5–120. Default comes from store settings.
`metadata`	object	optional	Free-form `string → string` map (values max 255 chars). Echoed on webhooks.

Provide either (amount + currency) or amount_sats, not both.

Response

JSON

{
  "invoice": {
    "id": "22872e14-4216-4c78-8fe1-088ea649f3c2",
    "store_id": "…",
    "vendor_id": "…",
    "status": "pending",
    "environment": "test",
    "address": "tb1q…",
    "amount_sats": "150234",
    "amount_btc": "0.00150234",
    "amount_fiat": 49.99,
    "fiat_currency": "USD",
    "btc_usd_rate": 33280.45,
    "rate_locked_at": "2026-05-16T11:15:00.000Z",
    "amount_tolerance_sats": "375",
    "amount_paid_sats": "0",
    "expires_at": "2026-05-16T11:30:00.000Z",
    "late_payment_grace_minutes": 60,
    "late_payment_deadline_at": "2026-05-16T12:30:00.000Z",
    "conf_threshold": 1,
    "fee_sats": "1502",
    "payment_uri": "bitcoin:tb1q…?amount=0.00150234&label=…",
    "hosted_checkout_url": "https://pay.satlane.com/i/22872e14-…",
    "payment_phase": "awaiting_payment",
    "order_ref": "ORD-12345",
    "created_at": "2026-05-16T11:15:00.000Z",
    "paid_at": null
  }
}

Response fields worth understanding

Field	What it means
`amount_sats`	Invoice amount in satoshis. Vendor-facing source of truth.
`amount_paid_sats`	Running total of sats received on-chain so far (non-reverted). Remaining = `amount_sats - amount_paid_sats`.
`amount_tolerance_sats`	Slack on the expected amount. Payments within `[amount_sats − tolerance, amount_sats + tolerance]` count as exact. Defaults come from platform setting `payment_tolerance_bp` (default 25 bp = 0.25%), clamped to `[10, 1000]` sats.
`btc_usd_rate`	BTC/USD rate locked at creation. Later price moves do not change what the buyer owes.
`late_payment_deadline_at`	ISO timestamp past which payments are no longer auto-credited. We keep watching until then.
`conf_threshold`	Confirmations required before status flips to `paid`. Defaults: 1 below $100 invoice value, 2 at $100+.
`fee_sats`	Platform take-rate on this invoice, accrued to your vendor account when a live invoice is paid. Visible in dashboard billing.
`payment_phase`	Buyer-facing lifecycle dimension computed at read time (not persisted). Useful for custom UIs.
`hosted_checkout_url`	Ready-to-redirect hosted payment page.