Quickstart
Start with a test invoice. Complete account security, create a store and keep its Test API key on your server. Wallet-free Sandbox requires SatLane-Version: 2026-10-05 and does not require a receiving wallet. Follow the webhook guide next if you automate fulfillment.
Overview
- Your server creates an invoice with
POST /v1/invoices. - Your application sends the buyer to
invoice.hosted_checkout_url. - The buyer sends Bitcoin to the derived address in your wallet.
- SatLane monitors live payments and confirmations.
- SatLane sends a signed event to your registered store webhook endpoint.
- Your server verifies the event, reconciles the order and queues fulfillment.
Your private keys stay in your wallet. You register an extended public key (xpub) with SatLane so it can derive invoice addresses; the registered xpub is encrypted at rest. SatLane assigns a receiving address to each Live invoice and watches the chain. Use the returned invoice ID for order reconciliation; an address is not a permanent order identifier. We never hold private keys; funds settle directly into your wallet on confirmation.
Platform billing (for integrators)
SatLane supports Starter, Basic, Pro and Custom with billing V4 enabled. Legacy installations retain Trial, Basic, Pro and Custom. The internal trial key means Starter in V4. For API integrators:
- Eligible paid Live invoices accrue usage fees against your account at the effective plan rate. Complimentary accounts waive new subscription and usage charges; existing balances remain for separate review.
- In Billing V4, Basic and Pro subscription prices are fixed in USD and quoted in Bitcoin at bill issuance. Subscriptions are billed in advance and usage in arrears. Manage bills at
/billing; this payments integration guide does not define a public plan-checkout API. - Billing V4 Starter has no trial-exhaustion counter. Unpaid bills can restrict new Live invoice creation after their due/grace period. Legacy Trial installations retain their paid-invoice trial limit. Review the account billing page for the applicable restriction.
- Test-mode invoices do not accrue platform fees.
Manage plans, usage, and Bitcoin bills in the app. Subscription entitlements apply across the account; active-store limits and domains per store follow the current catalog. Paid upgrades credit unused plan time; downgrades and cancellations take effect at period end. See pricing for the current catalog and billing explanation. This guide focuses on the payments API.
Merchant setup before integration
- Register and verify your email at
https://app.satlane.com. - Create a store and start in Sandbox. Complete two-factor authentication to manage keys and wallet settings.
- Create the store’s Test API key. Keep it on your server and send the required version header when creating Test invoices.
- Register a public HTTPS webhook endpoint for the Test environment. Simulate events and verify signature, duplicate-event and order-reconciliation handling.
- Configure checkout branding, receipts and optional SMTP credentials in that store’s settings. These settings belong to the store; they are not a single account-wide sender configuration. Custom domains and advanced checkout controls depend on the plan.
- Review the mainnet wallet and activation checklist, activate Live explicitly, create a Live key and register the Live webhook destination before accepting real payments.
Sandbox and Live data stay separate. Use the hosted checkout URL returned for each invoice, including on custom-domain stores, instead of constructing a platform URL yourself.
Authentication
| Surface | Auth |
|---|---|
Server-side API (POST /v1/invoices, etc.) | Authorization: Bearer sl_live_… or sl_test_… |
Public buyer endpoints (/pay/invoices/:id*) | None. The invoice UUID is the credential. |
| Vendor dashboard | Session cookie (dashboard only) |
API keys are issued per store from https://app.satlane.com/stores/<id>/keys. Complete the dashboard’s two-factor authentication setup and verification before managing API keys or registering a wallet. Each secret is shown once on creation. Store it in your secrets manager.
curl https://api.satlane.com/v1/invoices \
-H "Authorization: Bearer sl_test_XXX"
Use a test key (sl_test_…) while building. Switch to a live key (sl_live_…) when the store is live.
Create an invoice
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. |