SatLane
Skip to documentation
Browse documentation
On this page

Sandbox and simulator

For a Test invoice, exercise supported lifecycle scenarios without waiting on the chain. On the enabled wallet-free installation no receiving wallet or real Bitcoin is involved. Scenarios follow valid state transitions; not every event is valid from every status.

Dashboard Simulator

On a Test invoice detail page, simulation controls offer supported scenarios (with amount inputs where relevant). Accepted actions:

  1. Updates the invoice status in our DB
  2. Fires the matching webhook with livemode: false
  3. Pushes the new status over SSE/WebSocket to open checkout pages

API: POST /v1/invoices/:id/simulate

Test invoices only. Auth: a matching API key or the authorized vendor session. Use a stable action_id when retrying the same simulation action on an enabled installation.

POSTcURL7 lines
curl -X POST https://api.satlane.com/v1/invoices/22872e14-4216-4c78-8fe1-088ea649f3c2/simulate \
  -H "Authorization: Bearer sl_test_XXX" \
  -H "Content-Type: application/json" \
  -d '{
    "event": "paid",
    "amount_sats": "150234"
  }'
FieldTypeRequiredNotes
eventstringyesOne of: seen, paid, underpaid, overpaid, expired, late_paid, reverted, cancelled
action_idstringoptionalStable action identity, 1–128 characters, for retrying an enabled simulation without repeating it.
amount_satsstringoptionalOverride simulated payment amount. Defaults: full amount for paid/seen, ~60% for underpaid, ~150% for overpaid. Ignored for expired / cancelled / reverted.

Response: { "invoice": { … } } with the updated public invoice.

Simulations never bump unbilledFeeSats. Legacy alias: POST /v1/invoices/:id/simulate_paid (same as event: "paid").

Before accepting real payments, verify your webhook handling, configure and review the mainnet wallet, confirm chain and account eligibility, explicitly activate the store in Live and use a Live API key. Workspace switching alone never activates new payments. Live payment monitoring also depends on the configured chain services being available and synchronized.