SatLane
Skip to documentation
Browse documentation
On this page

Invoices

The following request uses illustrative order values. Response IDs, addresses, rates and timestamps below are examples, not current market rates or reusable payment destinations.

POSTcURL14 lines
curl -X POST https://api.satlane.com/v1/invoices \
  -H "SatLane-Version: 2026-10-05" \
  -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",
    "success_url": "https://yourshop.com/orders/ORD-12345/thanks",
    "buyer_email": "buyer@example.com",
    "expires_in_minutes": 15,
    "metadata": { "cart_id": "abc123" }
  }'

This creation example targets an installation with wallet-free Sandbox enabled. Use your deployment origin and confirmed contract for another installation. A webhook endpoint is optional for manual checkout; configure one for the matching environment before testing automated fulfillment.

Always send an Idempotency-Key on API creation. Successful responses are retained for 24-hour replay. Enabled creation stores the invoice and idempotency result atomically under a scoped reservation; reuse the same key and body after an uncertain result. A conflicting body is rejected. Legacy installations only provide the older response-cache behavior, so use sequential retries. Neither API replay nor invoice creation removes the need for order-level reconciliation and webhook deduplication. The session-authenticated dashboard form does not expose this API-key idempotency contract.

Request fields

FieldTypeRequiredNotes
amountnumberone ofFiat amount. We lock a BTC/USD rate and convert to sats.
currencystringone ofMust be "USD" today.
amount_satsstringone ofSkip fiat conversion; charge exact sats (digits only).
order_refstringoptionalYour internal order ID. Max 255 chars.
callback_urlstringoptionalStored invoice metadata. Current delivery uses registered store webhook endpoints; this field does not override them.
success_urlstringoptionalHosted checkout redirects here after payment.
buyer_emailstringoptionalBuyer email for receipts / support.
expires_in_minutesintoptional5–120. Public API default is the configured platform expiry (15 minutes by default). The dashboard store form uses the store expiry.
metadataobjectoptionalFree-form string → string map (values max 255 chars). Echoed on webhooks.

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

Response

Illustrative enabled Sandbox response. Nullable destinations must stay null in your models and UI. Live responses contain a mainnet destination; legacy responses may contain a Test destination.

JSON35 lines
{
  "invoice": {
    "id": "22872e14-4216-4c78-8fe1-088ea649f3c2",
    "store_id": "…",
    "vendor_id": "…",
    "status": "pending",
    "environment": "test",
    "address": null,
    "payment_destination": {
      "kind": "simulated",
      "network": null,
      "address": null,
      "payment_uri": null
    },
    "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": "0",
    "payment_uri": null,
    "hosted_checkout_url": "https://pay.satlane.com/i/22872e14-4216-4c78-8fe1-088ea649f3c2",
    "payment_phase": "awaiting_payment",
    "order_ref": "ORD-12345",
    "created_at": "2026-05-16T11:15:00.000Z",
    "paid_at": null
  }
}

Response fields worth understanding

FieldWhat it means
amount_satsInvoice amount in satoshis. Vendor-facing source of truth.
amount_paid_satsRunning total of sats received on-chain so far (non-reverted). Remaining = amount_sats - amount_paid_sats.
amount_tolerance_satsSlack 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_rateBTC/USD rate locked at creation. Later price moves do not change what the buyer owes.
late_payment_deadline_atISO timestamp past which payments are no longer auto-credited. Active monitoring runs through that deadline; recovery monitoring may follow.
conf_thresholdConfirmations required before status flips to paid. Defaults: 1 below $100 invoice value, 2 at $100+.
fee_satsPlatform take-rate on this invoice, accrued to your vendor account when a live invoice is paid. Visible in dashboard billing.
payment_phaseBuyer-facing lifecycle dimension computed at read time. Values include awaiting_payment, payment_detected, confirming, settled, shortfall, excess, needs_review, grace_period, recovery_window, and closed.
payment_summaryExpected, received and remaining sats, latest-payment confirmations, latest transaction ID and grace deadline. Received totals are not confirmed coverage. Treat sats values as strings.
checkout_urlsOptional checkout URL alternatives. Prefer hosted_checkout_url for the standard hosted flow; do not assume alternatives are always present.
hosted_checkout_urlReady-to-redirect hosted payment page.