# Sandbox and simulation

Deterministic sandbox bank rules and the simulation endpoints.

Staging (and local stacks) run a sandbox bank. Use a `wb_test_` key on your sandbox customer.

## Deterministic rules

- Payments settle instantly and deterministically; amounts ending in `77` stay pending.
- Account-holder verification returns a match unless the name contains `NOMATCH`, `CLOSE` or `UNAVAILABLE`.
- FX uses fixed fictional rates.

## Simulation endpoints

These exist only in sandbox environments (`403` with live keys, `404` [`feature-disabled`](/errors#feature-disabled) in production).

| Operation                                                                                | Request                                                                                                                                                  | Effect                                                                                      |
| ---------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------- |
| [`simulateSandboxIncomingPayment`](/reference/public-api#simulateSandboxIncomingPayment) | `POST /v1/sandbox/incoming-payments` `{ "balanceId", "amount", "senderName"?, "reference"? }` (`payments:write`)                                         | incoming funds from the sandbox bank: balance credited, `incoming_payment.received` webhook |
| [`simulateSandboxPaymentStatus`](/reference/public-api#simulateSandboxPaymentStatus)     | `POST /v1/sandbox/payments/{paymentId}/status` `{ "status": "processing" \| "completed" \| "rejected" \| "cancelled" \| "returned" }` (`payments:write`) | a bank status update for a payment you sent                                                 |
| [`simulateSandboxWebhookEvent`](/reference/public-api#simulateSandboxWebhookEvent)       | `POST /v1/sandbox/webhook-events` `{ "type", "objectId"?, "status"?, "amount"? }` (`webhooks:manage`)                                                    | any webhook event, delivered to your subscribed endpoints with `data.sandbox: true`         |
| [`resetSandbox`](/reference/public-api#resetSandbox)                                     | `POST /v1/sandbox/reset` (`webhooks:manage`)                                                                                                             | clears webhook delivery history and re-enables endpoints paused by failures                 |

Simulations answer `202 { "simulationId", "status": "queued" }` and are processed by the same pipeline as real bank events (seconds). They accept `Idempotency-Key`. Balances are never reset (the ledger is append-only): top up again with an incoming payment.