Sandbox Network

Sandbox is the environment where you exercise payment behavior before going live. A passing test card does not mean integration is done; 3DS, decline, routing fallback, and webhook retries should be rehearsed here too.

There is no real money movement, real issuer, or real card network; lifecycle and event discipline are simulated with the same logic as production.

Sandbox only: Sandbox Network is not a real bank, real card network, real issuer, or real money movement. Sandbox issuer resolution and sandbox provider behavior are for test and development only.

What Is Sandbox Network?

Sandbox Network is the environment where HSRC Pay simulates pre-production payment behavior using the same domain model, lifecycle discipline, and event/webhook model.

Use it to test:

• Payment create, confirm, authorization, capture, refund, and void flows
• Provider capability selection and adapter behavior
• Secure mode and multi-step payment flows that require requires_action
• Hard decline, soft decline, timeout, and provider unavailable scenarios
• Routing strategy, fallback, retry, and event delivery behavior

The sandbox environment is not a real financial network; it is a simulation of real lifecycle discipline.

Why Is a Test Card Alone Not Enough?

Simple test cards usually answer one question: "Did this payment return success?" Real payment integration raises more important questions:

• Does the provider support this payment method and secure mode?
• Does resolved issuer, BIN country, network, or card type change provider capability matching?
• Is payment state updated correctly after a 3DS challenge?
• Is fallback attempted after a soft decline?
• Is webhook retry and idempotency behavior correct?
• Are capture, refund, and void lifecycles handled correctly in the merchant system?

Sandbox cards alone are not enough; card validation, issuer resolution, BIN metadata, provider catalog/method fit, routing engine, adapter result, and event delivery must be tested together.

Sandbox vs Production

Production involves real provider credentials, real merchant settings, real payment intent, and real financial outcomes. Sandbox produces behavior with the same domain model, lifecycle, and event discipline without moving real money.

Core Components

• Payment Method: Normalizes card or other payment method data; carries fields such as issuer, network, country, IIN, brand, and type into payment decisions.
• Sandbox Issuer Resolution: Sandbox-only BIN/IIN records used to resolve issuer and card prefix metadata. This is not an issuer behavior simulation engine.
• Provider Catalog/Method: Represents which payment methods, networks, and transaction types sandbox providers support.
• Provider adapter execution: The confirm orchestrator's adapter pay / resume call for a routing candidate and normalized result (confirmResult.latestResult.kind).
• Routing Simulation: Tests provider selection and fallback behavior from payment, payment method metadata, provider capability, health, and rule inputs.
• Event/Webhook Delivery: Delivers payment outcomes to the merchant system as lifecycle-aligned, idempotently processable events.

Payment Lifecycle

The sandbox lifecycle follows the same mental model as production:

1. The merchant creates a checkout session or payment.
2. The user selects a sandbox payment method.
3. HSRC Pay normalizes the payment method.
4. The routing engine ranks suitable sandbox provider candidates.
5. The orchestrator runs a charge attempt with the adapter.
6. Payment becomes SUCCEEDED, AUTHORIZED, REQUIRES_ACTION, or REQUIRES_PAYMENT_METHOD; charge status carries the decline.
7. Webhooks and events go to the merchant system.

Summary: create → confirm → routing plan → charge attempt(s) → payment/charge status → webhook. See Payment Flows for details.

Routing and Provider Simulation

The goal of sandbox is not to return every payment as success. The goal is for the merchant to test scenarios such as success, hard decline, soft decline, timeout, 3DS challenge, capture, refund, void, webhook retry, and routing fallback in a controlled way.

Routing simulation can produce behavior from inputs such as:

• Resolved issuer, card network, BIN country, card type, and currency
• Provider capability: 3DS, capture, refund, void, installment support
• Merchant routing strategy and fallback settings
• Sandbox scenario inputs such as provider health or expected error

3DS and Requires Action Flows

When secure mode is enabled, the sandbox adapter may produce requires_action instead of returning direct success. This result tests whether the merchant or hosted checkout frontend can handle multi-step flows such as challenge, redirect, or HTML render.

In an API-only integration, you handle redirect via paymentNextAction.url; in hosted checkout, the checkout experience may take this step.

Decline and Error Simulation

Decline tests show the quality of payment integration. Card numbers do not simulate issuer declines. In sandbox, card-list validation can produce invalid_payment_method, while explicit provider/sandbox scenario configuration can produce provider timeout, system unknown, and other normalized error outcomes.

Instead of depending on raw provider errors, the merchant application should behave according to the normalized result and event model.

Security and Data Boundaries

• Sandbox credentials do not replace production credentials.
• Production cards must not be sent to the sandbox environment.
• Card data, credentials, signature material, and raw provider secrets must be masked in logs.
• Sandbox issuer labels and provider names do not claim to be real financial institutions.
• Sandbox tests do not guarantee production authorization rates or real provider costs.

What It Is Not

Sandbox Network is not a real bank. It is not a real card network. It is not a real issuer. It does not create real money movement.

Sandbox issuer resolution and sandbox providers are for test and development only. This structure does not replace real financial institutions, licensed payment institutions, card networks, or issuer decisions. The purpose of sandbox is not to mimic a real financial network to bypass regulation; it is to validate merchant integrations pre-production in a safe, traceable way.

Next Steps

• Sandbox Cards for the sandbox card allowlist and validation rules
• Sandbox Issuer Resolution for resolved issuer and card prefix metadata
• Provider and Adapter Model for the provider model
• Routing Simulation for routing fallback tests
• 3DS Simulation for secure mode flows
• Testing Declines for decline/error tests

Related docs

• Sandbox Cards
• Sandbox Issuer Resolution
• Provider and Adapter Model
• Routing Simulation
• 3DS Simulation
• Testing Declines