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.
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
| 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 | Stored invoice metadata. Current delivery uses registered store webhook endpoints; this field does not override them. |
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. Public API default is the configured platform expiry (15 minutes by default). The dashboard store form uses the store expiry. |
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
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.
{
"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
| 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. Active monitoring runs through that deadline; recovery monitoring may follow. |
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. Values include awaiting_payment, payment_detected, confirming, settled, shortfall, excess, needs_review, grace_period, recovery_window, and closed. |
payment_summary | Expected, 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_urls | Optional checkout URL alternatives. Prefer hosted_checkout_url for the standard hosted flow; do not assume alternatives are always present. |
hosted_checkout_url | Ready-to-redirect hosted payment page. |