Sandbox Testing Guide

The emulation engine exists to surface integration failures before production. This page provides a structured test approach: a test matrix covering every major flow, guidance on exercising non-happy-path and resilience scenarios, and the specific emulation behaviors that deserve the most attention.

📘

All test scenarios on this page run against the staging base URL (https://staging.api.axyscards.com/v2). Use your staging credentials throughout. Simulation endpoints (/staging/*) are staging-only — see Simulation Endpoints.

Test matrix

Cardholder onboarding

Card issuance and lifecycle

Crypto funding (STP)

Bank-rail funding

3-D Secure / OTP

Reconciliation

Resilience and non-happy-path testing

The emulation engine is specifically designed to surface these scenarios organically over repeated test runs. Complement the deterministic simulation endpoints (above) with unforced emulation runs where you don't call any /staging/* endpoint and observe what the engine produces naturally.

Timing and asynchronicity

Test your polling logic against the emulation engine's natural timing distributions — don't assume the happy-path test sequence (force a KYC pass, get an instant result) is representative of production behavior. Specifically:

• Run your full onboarding flow without calling POST /staging/kyc/validate and observe how long the emulation engine takes to produce an outcome. Your polling backoff schedule should handle both fast (seconds) and slow (hours) reviews without timing out prematurely or hammering the API.
• Run POST /staging/simulate-crypto-deposit and observe the interval between ledgerBalance and availableBalance updates. This emulates the chain-specific confirmation and off-ramp timing — your monitoring code should not assume they arrive close together.

Error injection

The emulation engine produces some error conditions organically:

• status = 6 (Error during KYC submission) — observe your error handling and re-submission path
• status = 7 (Admin Decline) — observe your support-ticket escalation path
• Webhook delivery delays — observe whether your OTP delivery pipeline has adequate timeout handling
• transStatus = 4 (Declined transaction) — the emulation engine can produce declined authorizations; observe how your reconciliation code handles these

Boundary conditions

Building an automated test suite

The simulation endpoints are designed to be called programmatically — making it straightforward to build an automated integration test suite that runs the full test matrix on every deployment. A suggested structure:

// test-suite.js — runs against staging only
const assert = process.env.AXYS_ENV === 'staging'
  || (() => { throw new Error('Tests must run against staging') })();

describe('Cardholder onboarding', () => {
  it('reaches Approved after KYC pass', async () => { /* ... */ });
  it('reaches Compliance Decline after KYC fail', async () => { /* ... */ });
  it('handles re-submission correctly', async () => { /* ... */ });
});

describe('Card funding — crypto STP', () => {
  it('updates ledgerBalance before availableBalance', async () => { /* ... */ });
  it('polling logic handles emulated delay correctly', async () => { /* ... */ });
});

describe('3DS OTP', () => {
  it('delivers OTP before expiresAt', async () => { /* ... */ });
  it('handles OTP expiry gracefully', async () => { /* ... */ });
});

Guard every test suite with an environment check — process.env.AXYS_ENV !== 'staging' should prevent the suite from running against the production API key, even if one is accidentally in scope.

What's next

• Going Live from Sandbox
• Simulation Endpoints
• Program Launch Checklist