SatLane
Skip to documentation
Browse documentation
On this page

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

  1. Your server creates an invoice with POST /v1/invoices.
  2. Your application sends the buyer to invoice.hosted_checkout_url.
  3. The buyer sends Bitcoin to the derived address in your wallet.
  4. SatLane monitors live payments and confirmations.
  5. SatLane sends a signed event to your registered store webhook endpoint.
  6. 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

  1. Register and verify your email at https://app.satlane.com.
  2. Create a store and start in Sandbox. Complete two-factor authentication to manage keys and wallet settings.
  3. Create the store’s Test API key. Keep it on your server and send the required version header when creating Test invoices.
  4. Register a public HTTPS webhook endpoint for the Test environment. Simulate events and verify signature, duplicate-event and order-reconciliation handling.
  5. 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.
  6. 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

SurfaceAuth
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 dashboardSession 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.

GETcURL2 lines
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.

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.