Sandbox
The sandbox environment lets you test your integration without processing real payments. Transactions go through the full processing pipeline — routing, provider adapter, callbacks, status updates, webhooks — but hit test adapters that return deterministic results. Your code is tested against the same logic that runs in production.
How sandbox works
- Test API keys (
sk_test_.../pk_test_...) activate sandbox mode. Thelivemodeflag is determined server-side from your key — you cannot override it. - Same API, same behavior. Sandbox runs the same processing pipeline as live. The only difference is that transactions hit test provider adapters instead of real providers.
- Test cards simulate scenarios. Magic card numbers produce different outcomes — success, decline, 3DS challenge, timeout, and more.
- Webhooks are delivered to your endpoint with the same structure and signing as in live. You can validate your webhook handler end-to-end.
- Data is isolated. Sandbox and live data never mix. All entities are tagged with
livemode: false, and the routing layer enforces that test traffic only reaches test terminals.
Getting started with sandbox
- Get your test API keys. Sign up and create a key pair in the Miracle Portal. See Get API Credentials for step-by-step instructions.
- Use test cards. Simulate different payment scenarios with magic card numbers. See Test Cards for the full list.
- Set up webhooks. Register a webhook endpoint and verify it receives events during sandbox testing. See Webhook Testing for local development tips.
- Test 3DS scenarios. Use the card suffix
0018to trigger a 3DS redirect. After the cardholder completes the challenge, callPOST /v1/payments/{id}/complete-actionwith aredirectResultvalue to simulate different 3DS outcomes. See Test Cards: 3DS scenarios for the full list. - Build and test your integration. Use the sandbox to test your full payment flow — create payments, handle 3DS, process refunds — before going live.
Sandbox vs. live
| Sandbox | Live | |
|---|---|---|
| API key prefix | sk_test_ / pk_test_ | sk_live_ / pk_live_ |
| Real money | No — test adapters only | Yes — real providers |
| Test cards | Accepted (magic card numbers) | Rejected |
| Webhooks | Delivered to your endpoint | Delivered to your endpoint |
| Settlement | Not generated | Generated per schedule |
| Fees | Calculated but not charged | Calculated and charged |
| Ledger entries | Recorded with livemode: false | Recorded with livemode: true |
| Dashboard | Shown with "TEST MODE" indicator | Normal display |
livemode propagation
The livemode flag is determined server-side from your API key and propagates through the entire pipeline: transactions, ledger entries, balance entries, and webhook events all inherit the same livemode value. All queries and aggregations filter by livemode, so sandbox and live data never mix. You cannot override the livemode flag in your requests.
When a merchant is created in sandbox, test terminals and channels are auto-provisioned based on the tenant's integration categories. No manual setup needed — you can start testing immediately.
Related
- Environments — full comparison of sandbox and live environments
- Test Cards — magic card numbers and expected outcomes
- Webhook Testing — test webhooks during local development
- Go-Live Checklist — steps to move from sandbox to production