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:
- Updates the invoice status in our DB
- Fires the matching webhook with
livemode: false - 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.
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"
}'
| Field | Type | Required | Notes |
|---|---|---|---|
event | string | yes | One of: seen, paid, underpaid, overpaid, expired, late_paid, reverted, cancelled |
action_id | string | optional | Stable action identity, 1–128 characters, for retrying an enabled simulation without repeating it. |
amount_sats | string | optional | Override 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.