Sandbox Overview

The Axys staging environment is not a simplified test mode. It is a high-fidelity emulation of production — built around a purpose-built emulation engine that simulates the full lifecycle of third-party systems, asynchronous processes, and real-world chaotic events that your integration will encounter in production. The goal is to make staging feel indistinguishable from production in every way that matters to your code.

📘

The zero-code-change guarantee. API endpoints, data structures, response shapes, and request payloads are identical between staging and production. The only differences are your credentials, the base URL, and the fact that backend states, events, and side effects are simulated rather than real. When you're ready to go live, you change three things — your certificate, your API key, and your base URL — and nothing else.

Why "emulation" rather than "sandbox"

Traditional API sandboxes are typically happy-path environments: static test data, instant synchronous responses, and no surprises. They're useful for checking that a request reaches an endpoint and returns the right shape — but they leave an entire class of integration failures undetected until production.

The Axys emulation engine is designed around a different philosophy: production resilience over integration convenience. It specifically replicates:

• Third-party system asynchronicity — compliance providers, correspondent banking networks, blockchain mempools, and card networks don't respond instantly or uniformly. The emulation engine introduces realistic timing distributions so your polling logic, timeout handling, and backoff strategies are tested against representative delays — not artificial immediacy.
• Non-deterministic outcomes — in production, a KYC submission can be approved, declined, or enter a manual review queue. A crypto deposit can arrive in seconds or minutes. An OTP can expire before the cardholder enters it. The emulation engine generates these outcomes realistically, not as hardcoded pass/fail toggles — with specific exceptions for scenarios you explicitly need to force (see Simulation Endpoints).
• Chaotic events — edge cases that occur rarely in production but can cause serious failures when they do: temporary third-party unavailability, partial responses, delayed webhook delivery, and state transitions that arrive out of expected sequence. Your integration will encounter these in staging before it encounters them in production.
• Realistic compliance lifecycle — cardholder status transitions follow the full timing and probabilistic distribution of real KYC processes, including cases where the outcome takes hours rather than seconds.

The production parity model

flowchart LR
    subgraph Staging["Staging environment (staging.api.axyscards.com/v2)"]
        SA["Your integration"]
        SE["Emulation engine"]
        SS["Simulated third parties\n(KYC / banking / blockchain / card network)"]
        SA -->|"Same API calls,\nsame request/response shapes"| SE
        SE -->|"Simulated states,\nrealistic timing, chaotic events"| SS
        SS -->|"Simulated outcomes\n(async, probabilistic)"| SE
        SE --> SA
    end
    subgraph Production["Production environment (production.api.axyscards.com/v2)"]
        PA["Your integration"]
        PP["Axys Platform"]
        PT["Real third parties"]
        PA -->|"Same API calls,\nsame request/response shapes"| PP
        PP <-->|"Real transactions,\nreal timing, real outcomes"| PT
    end
    Staging -.->|"Cert + key + base URL\nonly"| Production

The emulation engine sits between your API calls and the simulated third-party systems in staging — handling the same requests your code will make in production, and returning the same response shapes, while substituting real external interactions with high-fidelity simulations.

What the emulation engine covers

Staging-only simulation endpoints

Because the emulation engine produces realistic (non-deterministic) outcomes by default, controlled test scenarios — where you need a specific outcome on demand — are available via a set of staging-only simulation endpoints under /staging/*. These let you force specific states (KYC pass or fail, a crypto deposit of a precise amount, a card spend, a pre-generated OTP) without waiting for the emulation engine's natural timing.

These endpoints do not exist in production and will return 404 if called against the production base URL.

See Simulation Endpoints for the full reference.

What stays the same

What differs

What's next

• Simulation Endpoints — force specific test scenarios on demand
• Testing Your Integration — test matrix and resilience scenarios
• Going Live from Sandbox — the zero-code-change transition