Sandbox vs live

QairoPay runs two environments. They are operationally identical — same endpoints, same payload shapes, same error codes, same webhook event types — but isolated.

	Sandbox	Live
Base URL	https://api.sandbox.qairopay.com	https://api.qairopay.com
Key prefix	qp_sk_sandbox_… / qp_pk_sandbox_…	qp_sk_live_… / qp_pk_live_…
Money	Test USDC, no fiat off-ramp	Real USDC, real card networks, real settlement
Card transactions	Simulated authorizations via the dashboard or POST /v1/test/... helpers	Real card-network traffic
Webhooks	Delivered to your registered sandbox endpoint	Delivered to your registered live endpoint
Rate limits	Same envelope; you can request a temporary lift for load tests	Production limits
Audit log	Tenant-isolated	Tenant-isolated
Data persistence	Permanent unless you reset (button in dashboard)	Permanent (and subject to the retention windows in your DPA)

What you can do in sandbox that you can’t in live

Sandbox includes a small set of test endpoints for exercising flows that, in production, depend on physical hardware or a third party:

• POST /v1/test/cards/simulate_authorization — trigger an inbound card auth.
• POST /v1/test/cards/simulate_decline — trigger a decline with any reason code.
• POST /v1/test/settlements/advance_clock — fast-forward the settlement state machine to test off-ramp callbacks.
• POST /v1/test/passes/simulate_scan — emit a scanner event without a physical reader.

These endpoints return 404 not_found in live.

What you can’t do in sandbox that you can in live

• State MTL gating doesn’t apply in sandbox. A program that would be blocked from issuance to a particular state in live will work in sandbox.
• Sponsor-bank KYB is not performed in sandbox. Tenants are auto-approved.
• Real fiat off-ramps are not available. You cannot wire money from sandbox.

Promoting sandbox configuration to live

Pass templates, card programs, and webhook endpoints are first-class resources you can promote from sandbox to live with a single command:

qairopay promote pass-template tpl_01HZX --to live

Promotion copies the resource configuration verbatim, generates new IDs in the live environment, and emits a promotion.created event with both IDs. Data is not promoted — only configuration.

Tip

Treat sandbox as your CI environment. Run your integration tests against sandbox on every PR; promote configuration to live behind the same review gate you use for any production change.

When sandbox and live diverge

If you ever observe behavior in live that differs from sandbox in a way not listed above, that is a bug. Send a reproduction to developers@qairopay.com — sandbox/live parity is a constitutional invariant we monitor and break only with explicit deprecation notice.