Sandbox Cards

Sandbox cards are not real payment instruments. In HSRC Pay they are a runtime allowlist used by the sandbox provider to verify that the submitted card data is known sandbox test data.

Important boundary: sandbox cards do not simulate specific issuer errors such as insufficient funds, invalid account, stolen card, expired card, issuer unavailable, or risk/fraud responses. A sandbox card is only a sandbox card.

What Sandbox Cards Do

What Sandbox Cards Do Not Do

Sandbox card numbers are not scenario switches. Do not map a specific PAN to a specific issuer decline or provider failure.

Use provider/sandbox scenario configuration for explicit error simulation. In the Felix sandbox adapter this is handled through expectedSandboxErr; it is independent from the card number. The card must still be valid sandbox card data when the flow requires card validation.

Card Validation Logic

The sandbox provider validates card data only for card payment methods:

1. pan is reduced to digits only.
2. month is normalized to two digits.
3. year is normalized to the last two digits.
4. If cvv or cvc is present, it is reduced to digits only and matched exactly.
5. If the card is not found in the allowlist, the provider returns invalid_payment_method.

3DS Behavior

3DS is controlled by payment configuration, not by choosing a special card number:

Sandbox Card List

Use these cards only in sandbox. They are dummy test data and are accepted only by the sandbox provider allowlist.

Example Usage

const { data } = await api.post(`/v1/payments/${paymentId}/confirm`, {
  payment_method: {
    type: "card",
    data: {
      pan: "4991001823456701",
      month: "05",
      year: "28",
      cvv: "123",
    },
  },
  payer_identity: { ip_address: clientIp, user_agent: ua },
});

if (data.payment.status === "REQUIRES_ACTION") {
  redirectUser(data.confirmResult.paymentNextAction?.url);
}

Production Boundary

Sandbox cards must not be used with production credentials or production provider routes. Production card behavior comes from the real provider/card network response and is not controlled by this sandbox allowlist.

Common Mistakes

• Treating sandbox card numbers as issuer error triggers.
• Expecting a PAN to simulate insufficient funds, invalid account, stolen card, expired card, or issuer unavailable.
• Testing only success and skipping secure_mode: true.
• Sending sandbox cards to production.
• Sending production card data to sandbox.
• Designing user-facing UI around raw provider strings instead of normalized errors.

Related docs

• Sandbox Network
• Sandbox Issuer Resolution
• 3DS Simulation
• Testing Declines
• Routing Simulation