# 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.

```bash
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.

---