Environments

Miracle provides two environments — sandbox for testing and live for real payments. Both environments run the same processing pipeline. The only difference is whether transactions hit test provider adapters (sandbox) or real providers (live).

Environment comparison

	Sandbox	Live
Purpose	Testing and development	Real payments
API base URL	Same URL — determined by API key, not separate hosts	Same URL
API key prefix	`sk_test_` / `pk_test_`	`sk_live_` / `pk_live_`
Real money	No	Yes
Test cards	Accepted (magic card numbers)	Rejected — use real cards
Webhooks	Sent to your endpoint	Sent to your endpoint
Settlement	Not generated	Generated per schedule
Fees	Calculated but not charged	Calculated and charged
Dashboard	Sandbox section in Portal ("TEST MODE" indicator)	Live section in Portal

Sandbox details

Sandbox transactions go through the full processing pipeline — routing, provider adapter, callback, status update, webhooks — but hit test adapters that return deterministic results based on magic values in the input (card number, amount).

Key points:

No real money is processed. Ledger entries are recorded with livemode: false and never trigger real settlement or billing.
Use test card numbers to simulate scenarios. Different card numbers produce different outcomes — success, decline, 3DS challenge, timeout, and more. See Test Cards.
Webhooks are delivered the same way as in live. Your webhook endpoint receives the same event structure, so you can validate your integration end-to-end.
Data is isolated. Sandbox and live data never mix. All queries filter by livemode, and the routing layer enforces that test traffic can only reach test terminals.

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.

Switching environments

The environment is determined entirely by which API key you use. There is no configuration flag or environment parameter to set.

Key prefix	Environment
`sk_test_` / `pk_test_`	Sandbox
`sk_live_` / `pk_live_`	Live

To switch from sandbox to live, replace your test key with a live key. No other change is needed — the API endpoints, request format, and response format are identical.

# Sandbox — same URL, test key
curl https://api.miracle.com/v1/payments \
  -H "Authorization: Bearer sk_test_your_secret_key"

# Live — same URL, live key
curl https://api.miracle.com/v1/payments \
  -H "Authorization: Bearer sk_live_your_secret_key"

Sandbox and production share the same deployment. There are no separate hosts or base URLs. The API key prefix (sk_test_ vs sk_live_) determines which environment processes your request.

The livemode value is derived server-side from your API key. It cannot be overridden by request parameters. This prevents accidental live transactions during development.

Livemode flag

Every API response includes a livemode field that tells you which environment processed the request:

{
  "data": {
    "id": "pay_01H...",
    "livemode": false,
    "status": "succeeded"
  }
}

livemode: false — sandbox transaction (test key was used).
livemode: true — live transaction (live key was used).

The livemode flag propagates to all related entities: transactions, ledger entries, balance entries, and webhook events. The Portal dashboard uses this flag to separate sandbox and live data.

Quick test

The sandbox uses a last-4-digit magic system: the last 4 digits of any Luhn-valid card number determine the outcome. For example, any card ending in 0000 succeeds, and any card ending in 0034 declines with "insufficient funds". You can use any valid card number you like -- only the last 4 digits matter.

Use any Luhn-valid card ending in 0000 with any future expiry and any CVC to simulate a successful payment in sandbox.

See the full list of magic card suffixes and 3DS scenarios in Test Cards.

Magic amounts (where the payment amount controls the outcome) are not currently active. Only magic card suffixes control test outcomes.

Next step

Ready to process your first test payment?

Your First Payment -->