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
77stay pending. - Account-holder verification returns a match unless the name contains
NOMATCH,CLOSEorUNAVAILABLE. - FX uses fixed fictional rates.
Simulation endpoints
These exist only in sandbox environments (403 with live keys, 404 feature-disabled in production).
| Operation | Request | Effect |
|---|---|---|
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 | POST /v1/sandbox/payments/{paymentId}/status { "status": "processing" | "completed" | "rejected" | "cancelled" | "returned" } (payments:write) | a bank status update for a payment you sent |
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 | 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.