Sandbox overview¶
TL;DR - The dev environment at https://dev.magma.builders runs the same
dashboard and API as production, but against a built-in sandbox instead of the
real payments provider. No real money moves. The things that are normally out
of your hands - KYC outcomes, inbound wires, settlement - you drive yourself,
from a hosted verification page or a dev-only Simulation API.
What the sandbox is¶
The dev environment is the full Magma product: the same dashboard, the same Product API, the same statuses, fees, and PDF receipts described in the User guide. The only thing replaced is the upstream payments provider behind it, which is simulated. That means everything in the User guide applies as written - this section only documents what behaves differently and the levers you use to move money that doesn't exist.
What's different from production¶
| Production | Sandbox (dev) | |
|---|---|---|
| KYC / KYB | The provider's hosted document flow | A verification page with three outcome buttons, or one API call |
| Inbound deposits | Real wires from real banks | Injected with one API call |
| Payout settlement | Real rails, 1-5 business days | Seconds - automatic, or driven by you |
| OTP on fiat payouts | Delivered to your phone | Any 6-digit code works (e.g. 000000) |
| Money | Real | None |
Dev only
The Simulation API exists only in the dev environment - the same paths return 404 in production, so there is no way to "simulate" anything against real money. Conversely: everything you create in dev is test data and may be reset.
Two ways to drive it¶
The hosted verification page - zero setup. Every new customer gets a KYC link (visible on their detail page); in dev that link opens a page where you pick the outcome yourself. Enough for demos and manual testing of the happy path. See Simulate KYC / KYB.
The Simulation API - six authenticated endpoints under
https://dev.magma.builders/api/v1/sandbox, callable from curl, Postman, or
your test suite:
| What you want | Call | How-to |
|---|---|---|
| Approve / review / reject KYC | POST /organizations/{orgId}/kyc |
Simulate KYC / KYB |
| Block / unblock a customer | POST /organizations/{orgId}/block |
Simulate KYC / KYB |
| Fund a balance | POST /virtual-accounts/{vaId}/deposit |
Simulate deposits |
| Walk an on-ramp deposit | POST /transactions/{id}/deposit-advance |
Simulate deposits |
| Settle / fail / expire a payout | POST /transactions/{id}/advance |
Simulate payout settlement |
| Inspect the sandbox | GET /state |
Simulation API reference |
Authentication and error semantics are on the
Simulation API reference; the machine-readable contract is the
dedicated Swagger at
/api/sandbox-docs (separate
from the Product API spec).
The happy path advances on its own¶
By default the dev sandbox runs with auto-advance on: a few seconds after
each action, the next lifecycle step fires by itself. Virtual accounts
activate, payouts walk pending → processing → completed, on-ramp deposits
land. The one thing that never auto-advances is KYC - a new customer
stays created until you decide the outcome.
GET /api/v1/sandbox/state tells you whether auto_advance is on. The
manual advance endpoints exist for the paths auto-advance won't take for
you - failures, expiries - and for deterministic step-by-step tests. See
Simulate payout settlement.
Where to go next¶
- Simulate KYC / KYB - get your first customer to
active. - Simulate deposits - fund the balance.
- Simulate payout settlement - send and settle payouts.
- Simulation API reference - auth, endpoints, errors.
- End-to-end walkthrough - the whole loop in ten minutes.