Skip to content

Simulation API reference

TL;DR - Six dev-only endpoints under https://dev.magma.builders/api/v1/sandbox that drive what's normally out of your hands: KYC outcomes, inbound deposits, settlement. Auth is a Keycloak operator bearer token from an MFA login - API keys are not accepted. The machine-readable spec lives at /api/sandbox-docs - that is the contract; this page is the orientation.

Base URL and availability

https://dev.magma.builders/api/v1/sandbox

These endpoints exist only in the dev environment - in production the same paths return 404. In dev they show up in two places: inline in the Product API Swagger (/api/docs), each filed under its matching section (KYC/block/deposit under Organizations, the advance levers under Transactions), and in their own standalone spec at /api/sandbox-docs. In production they are absent from /api/docs, which stays prod-faithful.

Authentication

Send a Keycloak bearer token on every call:

Authorization: Bearer <token>

The token is obtained exactly like Option B of the API reference - the same realm your operators log in through - with two constraints:

  • it must come from an MFA login (the TOTP step you enrolled at first login), and
  • the operator needs the operate or admin role - view users get 403.

API keys don't work here

Unlike the Product API, the Simulation API does not accept the X-Api-Key header. Mutating a shared environment is gated on a real, MFA-verified operator session.

Tenant scoping - every id you pass is a Magma id (the ones the dashboard and Product API show), and every lookup is scoped to your fintech: another tenant's customer or transaction is a 404, not yours to touch. Each call is also audit-logged with the operator who made it.

Endpoints

Method Path Parameters Purpose
POST /organizations/{orgId}/kyc result = verified (default) / review / failed Decide the KYC / KYB outcome. How-to
POST /organizations/{orgId}/block blocked = true (default) / false Block or unblock the customer; payouts while blocked fail with BLOCKED. How-to
POST /virtual-accounts/{vaId}/deposit JSON body, all optional: amount (default 1000), currency (USD), status (COMPLETED / PENDING / FAILED), sender_name, payment_rail (ACH) Inject a deposit - fiat top-up or on-ramp. How-to
POST /transactions/{id}/deposit-advance to = in_transit / in_destination (default) Walk an on-ramp deposit's settlement steps. How-to
POST /transactions/{id}/advance to = processing / completed (default) / failed / expired / deposit_received Advance a payout's lifecycle. How-to
GET /state - Inspect the sandbox. See below.

GET /state

Returns a snapshot of the sandbox: the registered webhook URL, the auto_advance flag (whether happy paths advance on their own - see Simulate payout settlement), and entity counts. Handy as a liveness check and to confirm which mode the environment is in.

Responses and errors

On success the sandbox's response is relayed as-is with status 200. Errors:

Status Meaning
400 Invalid id format, or an unrecognized result / to value.
401 Missing or invalid bearer token.
403 Valid token, but the operator only has the view role.
404 The resource isn't in your fintech, or it has no provider-side counterpart yet (e.g. advancing a transaction whose payout never reached the provider).
502 The sandbox service is unreachable - ping your Magma contact.

What's next