# simulations

Sandbox simulations (SC-38, P-89): every asynchronous outcome on demand — incoming payments and debits, payment status, returns and recalls, inbound recalls, exchange settlement, FX rate moves, direct-debit outcomes, card events, KYC outcomes, integrator events, statements, scheduled runs and provider outages. Backed by the sandbox bank, and by the Banking Circle and Integrated Finance sandboxes where they offer a simulation.

## GET /simulations

operationId: `listSimulations`
Summary: Available simulations and sandbox rules
API key scopes: `balances:read`
Parameters: `X-Tenant-Id` (header, required), `X-Request-Id` (header)
Responses: 200 `SimulationCatalogue`, 401 `Problem`, 403 `Problem`, 429 `Problem`, default `Problem`

**Sandbox only:** `404 feature-disabled` wherever the sandbox is off (always in production). Callers: a `wb_test_` API key of the customer, or a member session of a developer sandbox workspace (`403` for live keys and other sessions). Every simulation answers `202 SimulationResult`; `queued` outcomes arrive through the normal pipeline (ledger, notifications, integrator webhooks) within seconds. Rules: docs/SANDBOX.md.

**API key scope:** `balances:read`.

## POST /simulations/cards/{cardId}/transactions

operationId: `simulateCardTransaction`
Summary: Simulate a card transaction event
API key scopes: `payments:write`
Parameters: `cardId` (path, required), `X-Tenant-Id` (header, required), `X-Request-Id` (header), `Idempotency-Key` (header)
Request body: `SimCardTransaction`
Responses: 202 `SimulationResult`, 400 `Problem`, 401 `Problem`, 403 `Problem`, 404 `Problem`, 409 `Problem`, 422 `Problem`, 429 `Problem`, default `Problem`

A neutral card event (`cards/transaction`) as the card processor would send it: authorisation (hold), settlement, reversal, refund or decline.

**Sandbox only:** `404 feature-disabled` wherever the sandbox is off (always in production). Callers: a `wb_test_` API key of the customer, or a member session of a developer sandbox workspace (`403` for live keys and other sessions). Every simulation answers `202 SimulationResult`; `queued` outcomes arrive through the normal pipeline (ledger, notifications, integrator webhooks) within seconds. Rules: docs/SANDBOX.md.

**API key scope:** `payments:write`.

## POST /simulations/direct-debits/collections/{collectionId}/status

operationId: `simulateCollectionStatus`
Summary: Simulate a direct-debit collection outcome
API key scopes: `payments:write`
Parameters: `collectionId` (path, required), `X-Tenant-Id` (header, required), `X-Request-Id` (header), `Idempotency-Key` (header)
Request body: `SimCollectionStatus`
Responses: 202 `SimulationResult`, 400 `Problem`, 401 `Problem`, 403 `Problem`, 404 `Problem`, 409 `Problem`, 422 `Problem`, 429 `Problem`, default `Problem`

**Sandbox only:** `404 feature-disabled` wherever the sandbox is off (always in production). Callers: a `wb_test_` API key of the customer, or a member session of a developer sandbox workspace (`403` for live keys and other sessions). Every simulation answers `202 SimulationResult`; `queued` outcomes arrive through the normal pipeline (ledger, notifications, integrator webhooks) within seconds. Rules: docs/SANDBOX.md.

**API key scope:** `payments:write`.

## POST /simulations/exchanges/{exchangeId}/status

operationId: `simulateExchangeStatus`
Summary: Simulate the settlement of an exchange
API key scopes: `exchanges:write`
Parameters: `exchangeId` (path, required), `X-Tenant-Id` (header, required), `X-Request-Id` (header), `Idempotency-Key` (header)
Request body: `SimExchangeStatus`
Responses: 202 `SimulationResult`, 400 `Problem`, 401 `Problem`, 403 `Problem`, 404 `Problem`, 409 `Problem`, 422 `Problem`, 429 `Problem`, default `Problem`

Applies to an exchange still `processing` at the sandbox bank.

**Sandbox only:** `404 feature-disabled` wherever the sandbox is off (always in production). Callers: a `wb_test_` API key of the customer, or a member session of a developer sandbox workspace (`403` for live keys and other sessions). Every simulation answers `202 SimulationResult`; `queued` outcomes arrive through the normal pipeline (ledger, notifications, integrator webhooks) within seconds. Rules: docs/SANDBOX.md.

**API key scope:** `exchanges:write`.

## POST /simulations/fx-rates

operationId: `simulateFxRateMove`
Summary: Move a sandbox FX rate
API key scopes: `exchanges:write`
Parameters: `X-Tenant-Id` (header, required), `X-Request-Id` (header), `Idempotency-Key` (header)
Request body: `SimFxRate`
Responses: 202 `SimulationResult`, 400 `Problem`, 401 `Problem`, 403 `Problem`, 409 `Problem`, 422 `Problem`, 429 `Problem`, default `Problem`

Stored on the operator's sandbox connection (`rateShiftsBps`): every quote of the pair moves (the inverse pair the other way). `applied`; `details.rate` is the new rate.

**Sandbox only:** `404 feature-disabled` wherever the sandbox is off (always in production). Callers: a `wb_test_` API key of the customer, or a member session of a developer sandbox workspace (`403` for live keys and other sessions). Every simulation answers `202 SimulationResult`; `queued` outcomes arrive through the normal pipeline (ledger, notifications, integrator webhooks) within seconds. Rules: docs/SANDBOX.md.

**API key scope:** `exchanges:write`.

## POST /simulations/incoming-debits

operationId: `simulateIncomingDebit`
Summary: Simulate a direct debit taken from a balance
API key scopes: `payments:write`
Parameters: `X-Tenant-Id` (header, required), `X-Request-Id` (header), `Idempotency-Key` (header)
Request body: `SimIncomingDebit`
Responses: 202 `SimulationResult`, 400 `Problem`, 401 `Problem`, 403 `Problem`, 409 `Problem`, 422 `Problem`, 429 `Problem`, default `Problem`

Banking Circle sandbox only (`POST /api/v1/payments/simulations/debits`); `409` on other connections.

**Sandbox only:** `404 feature-disabled` wherever the sandbox is off (always in production). Callers: a `wb_test_` API key of the customer, or a member session of a developer sandbox workspace (`403` for live keys and other sessions). Every simulation answers `202 SimulationResult`; `queued` outcomes arrive through the normal pipeline (ledger, notifications, integrator webhooks) within seconds. Rules: docs/SANDBOX.md.

**API key scope:** `payments:write`.

## POST /simulations/incoming-payments

operationId: `simulateIncomingPayment`
Summary: Simulate an incoming payment
API key scopes: `payments:write`
Parameters: `X-Tenant-Id` (header, required), `X-Request-Id` (header), `Idempotency-Key` (header)
Request body: `SimIncomingPayment`
Responses: 202 `SimulationResult`, 400 `Problem`, 401 `Problem`, 403 `Problem`, 409 `Problem`, 422 `Problem`, 429 `Problem`, default `Problem`

Sandbox bank: an `account.credited` event through the webhook pipeline (`queued`). Banking Circle sandbox: `POST /api/v1/payments/simulations/credits` on the balance account (`submitted`; the `IncomingPaymentProcessed` notification follows). Integrated Finance sandbox: a provisioned account credit on the balance IBAN (inferred until IF-33).

**Sandbox only:** `404 feature-disabled` wherever the sandbox is off (always in production). Callers: a `wb_test_` API key of the customer, or a member session of a developer sandbox workspace (`403` for live keys and other sessions). Every simulation answers `202 SimulationResult`; `queued` outcomes arrive through the normal pipeline (ledger, notifications, integrator webhooks) within seconds. Rules: docs/SANDBOX.md.

**API key scope:** `payments:write`.

## POST /simulations/incoming-payments/{incomingPaymentId}/recall

operationId: `simulateIncomingRecall`
Summary: Simulate an inbound recall request
API key scopes: `payments:write`
Parameters: `incomingPaymentId` (path, required), `X-Tenant-Id` (header, required), `X-Request-Id` (header), `Idempotency-Key` (header)
Request body: `SimIncomingRecall`
Responses: 202 `SimulationResult`, 400 `Problem`, 401 `Problem`, 403 `Problem`, 404 `Problem`, 409 `Problem`, 422 `Problem`, 429 `Problem`, default `Problem`

Opens a partner compliance case (`inbound_recall`, provider `sandbox`) in the operator's queue (`applied`).

**Sandbox only:** `404 feature-disabled` wherever the sandbox is off (always in production). Callers: a `wb_test_` API key of the customer, or a member session of a developer sandbox workspace (`403` for live keys and other sessions). Every simulation answers `202 SimulationResult`; `queued` outcomes arrive through the normal pipeline (ledger, notifications, integrator webhooks) within seconds. Rules: docs/SANDBOX.md.

**API key scope:** `payments:write`.

## POST /simulations/kyc

operationId: `simulateKycOutcome`
Summary: Simulate a KYC review outcome
API key scopes: `payments:write`
Parameters: `X-Tenant-Id` (header, required), `X-Request-Id` (header), `Idempotency-Key` (header)
Request body: `SimKycOutcome`
Responses: 202 `SimulationResult`, 400 `Problem`, 401 `Problem`, 403 `Problem`, 409 `Problem`, 422 `Problem`, 429 `Problem`, default `Problem`

Applied as the KYC provider's `applicantReviewed` webhook: `approved` (GREEN), `rejected` (RED FINAL), `retry` (RED RETRY).

**Sandbox only:** `404 feature-disabled` wherever the sandbox is off (always in production). Callers: a `wb_test_` API key of the customer, or a member session of a developer sandbox workspace (`403` for live keys and other sessions). Every simulation answers `202 SimulationResult`; `queued` outcomes arrive through the normal pipeline (ledger, notifications, integrator webhooks) within seconds. Rules: docs/SANDBOX.md.

**API key scope:** `payments:write`.

## POST /simulations/payments/{paymentId}/recall

operationId: `simulatePaymentRecall`
Summary: Simulate the outcome of a payment recall
API key scopes: `payments:write`
Parameters: `paymentId` (path, required), `X-Tenant-Id` (header, required), `X-Request-Id` (header), `Idempotency-Key` (header)
Request body: `SimPaymentRecall`
Responses: 202 `SimulationResult`, 400 `Problem`, 401 `Problem`, 403 `Problem`, 404 `Problem`, 409 `Problem`, 422 `Problem`, 429 `Problem`, default `Problem`

`accepted`: the funds come back (a return with the recall reason); `rejected`: recorded on the provider event log, nothing moves.

**Sandbox only:** `404 feature-disabled` wherever the sandbox is off (always in production). Callers: a `wb_test_` API key of the customer, or a member session of a developer sandbox workspace (`403` for live keys and other sessions). Every simulation answers `202 SimulationResult`; `queued` outcomes arrive through the normal pipeline (ledger, notifications, integrator webhooks) within seconds. Rules: docs/SANDBOX.md.

**API key scope:** `payments:write`.

## POST /simulations/payments/{paymentId}/return

operationId: `simulatePaymentReturn`
Summary: Simulate the return of a payment
API key scopes: `payments:write`
Parameters: `paymentId` (path, required), `X-Tenant-Id` (header, required), `X-Request-Id` (header), `Idempotency-Key` (header)
Request body: `SimPaymentReturn`
Responses: 202 `SimulationResult`, 400 `Problem`, 401 `Problem`, 403 `Problem`, 404 `Problem`, 409 `Problem`, 422 `Problem`, 429 `Problem`, default `Problem`

**Sandbox only:** `404 feature-disabled` wherever the sandbox is off (always in production). Callers: a `wb_test_` API key of the customer, or a member session of a developer sandbox workspace (`403` for live keys and other sessions). Every simulation answers `202 SimulationResult`; `queued` outcomes arrive through the normal pipeline (ledger, notifications, integrator webhooks) within seconds. Rules: docs/SANDBOX.md.

**API key scope:** `payments:write`.

## POST /simulations/payments/{paymentId}/status

operationId: `simulatePaymentStatus`
Summary: Simulate the provider status of a payment
API key scopes: `payments:write`
Parameters: `paymentId` (path, required), `X-Tenant-Id` (header, required), `X-Request-Id` (header), `Idempotency-Key` (header)
Request body: `SimPaymentStatus`
Responses: 202 `SimulationResult`, 400 `Problem`, 401 `Problem`, 403 `Problem`, 404 `Problem`, 409 `Problem`, 422 `Problem`, 429 `Problem`, default `Problem`

A payment sent through the sandbox bank (`409` before it is sent or on a partner connection). The worker applies the stated status without asking the sandbox bank.

**Sandbox only:** `404 feature-disabled` wherever the sandbox is off (always in production). Callers: a `wb_test_` API key of the customer, or a member session of a developer sandbox workspace (`403` for live keys and other sessions). Every simulation answers `202 SimulationResult`; `queued` outcomes arrive through the normal pipeline (ledger, notifications, integrator webhooks) within seconds. Rules: docs/SANDBOX.md.

**API key scope:** `payments:write`.

## POST /simulations/provider-outage

operationId: `simulateProviderOutage`
Summary: Simulate a sandbox bank outage
API key scopes: `payments:write`
Parameters: `X-Tenant-Id` (header, required), `X-Request-Id` (header), `Idempotency-Key` (header)
Request body: `SimOutage`
Responses: 202 `SimulationResult`, 400 `Problem`, 401 `Problem`, 403 `Problem`, 409 `Problem`, 422 `Problem`, 429 `Problem`, default `Problem`

Bank calls fail with a retryable provider error until the time given (`applied`): rehearse retries and backoff.

**Sandbox only:** `404 feature-disabled` wherever the sandbox is off (always in production). Callers: a `wb_test_` API key of the customer, or a member session of a developer sandbox workspace (`403` for live keys and other sessions). Every simulation answers `202 SimulationResult`; `queued` outcomes arrive through the normal pipeline (ledger, notifications, integrator webhooks) within seconds. Rules: docs/SANDBOX.md.

**API key scope:** `payments:write`.

## POST /simulations/scheduled-payments/{scheduledPaymentId}/run-now

operationId: `simulateScheduledRun`
Summary: Run a scheduled payment now
API key scopes: `payments:write`
Parameters: `scheduledPaymentId` (path, required), `X-Tenant-Id` (header, required), `X-Request-Id` (header), `Idempotency-Key` (header)
Responses: 202 `SimulationResult`, 401 `Problem`, 403 `Problem`, 404 `Problem`, 409 `Problem`, 429 `Problem`, default `Problem`

An active schedule with a next occurrence is made due now and handed to the worker (`409` otherwise).

**Sandbox only:** `404 feature-disabled` wherever the sandbox is off (always in production). Callers: a `wb_test_` API key of the customer, or a member session of a developer sandbox workspace (`403` for live keys and other sessions). Every simulation answers `202 SimulationResult`; `queued` outcomes arrive through the normal pipeline (ledger, notifications, integrator webhooks) within seconds. Rules: docs/SANDBOX.md.

**API key scope:** `payments:write`.

## POST /simulations/statements

operationId: `simulateStatement`
Summary: Simulate a statement becoming available
API key scopes: `webhooks:manage`
Parameters: `X-Tenant-Id` (header, required), `X-Request-Id` (header), `Idempotency-Key` (header)
Request body: `SimStatement`
Responses: 202 `SimulationResult`, 400 `Problem`, 401 `Problem`, 403 `Problem`, 409 `Problem`, 422 `Problem`, 429 `Problem`, default `Problem`

A `statement.available` integrator event for the balance.

**Sandbox only:** `404 feature-disabled` wherever the sandbox is off (always in production). Callers: a `wb_test_` API key of the customer, or a member session of a developer sandbox workspace (`403` for live keys and other sessions). Every simulation answers `202 SimulationResult`; `queued` outcomes arrive through the normal pipeline (ledger, notifications, integrator webhooks) within seconds. Rules: docs/SANDBOX.md.

**API key scope:** `webhooks:manage`.

## POST /simulations/webhook-events

operationId: `simulateWebhookEvent`
Summary: Send an integrator event to your endpoints
API key scopes: `webhooks:manage`
Parameters: `X-Tenant-Id` (header, required), `X-Request-Id` (header), `Idempotency-Key` (header)
Request body: `SimWebhookEvent`
Responses: 202 `SimulationResult`, 400 `Problem`, 401 `Problem`, 403 `Problem`, 409 `Problem`, 422 `Problem`, 429 `Problem`, default `Problem`

Delivered to the customer's active endpoints subscribed to the type, with `data.sandbox: true`.

**Sandbox only:** `404 feature-disabled` wherever the sandbox is off (always in production). Callers: a `wb_test_` API key of the customer, or a member session of a developer sandbox workspace (`403` for live keys and other sessions). Every simulation answers `202 SimulationResult`; `queued` outcomes arrive through the normal pipeline (ledger, notifications, integrator webhooks) within seconds. Rules: docs/SANDBOX.md.

**API key scope:** `webhooks:manage`.