Sandbox Issuer Resolution
How sandbox card prefixes resolve issuer and BIN metadata, and what this does not simulate.
Sandbox issuer resolution exists in HSRC Pay, but it is not an issuer behavior simulation engine.
The codebase resolves card prefixes to an issuer plus BIN metadata: network, country, brand, IIN, phone, prefix, and card type. The resolved issuer is stored on the payment method and can be used by routing capability checks. It does not create issuer behavior.
Runtime Model
| Step | What happens |
|---|---|
| PAN cleanup | Non-digit characters are removed from the submitted card number. |
| Network fallback | The resolver can infer a network from card-number ranges. |
| BIN lookup | The sandbox repository loads bin_list rows and selects the longest matching prefix. |
| Issuer + metadata result | The resolved result contains issuer, network, country, iin, brand, phone, prefix, and type. |
| Payment method update | The resolved fields are persisted on the payment method and _sys_resolve_result metadata. |
| Routing input | Provider capability matching can read issuer, network, country, card type, currency, secure mode, and installment data. |
What This Does
- Resolves a sandbox issuer for card payment methods when the card prefix matches a BIN record.
- Adds sandbox-only BIN metadata to card payment methods.
- Lets tests cover provider method compatibility by issuer, network, country, and card type when provider capabilities are configured for those fields.
- Keeps sandbox BIN data separate from production BIN intelligence.
What This Does Not Do
- It is not a real issuer, bank, ACS, card network, or licensed financial institution.
- It does not simulate issuer decisions.
- It does not map BINs or issuers to
requires_action, hard decline, soft decline, insufficient funds, invalid account, fraud, or issuer unavailable. - It does not guarantee production approval, routing, fees, or provider behavior.
- It is not a public API for managing issuer profiles.
Relationship With Sandbox Cards
Sandbox cards and sandbox issuer resolution are related but not the same thing:
| Area | Source | Runtime purpose |
|---|---|---|
| Sandbox card allowlist | SandboxCards | Accept or reject card test data in the sandbox provider. |
| Sandbox issuer resolution | SandboxBinList / bin_list | Resolve issuer and BIN metadata for the payment method. |
| 3DS result | Payment config + sandbox adapter | secure_mode: true returns requires_action for a valid sandbox card. |
| Explicit error simulation | Provider/sandbox scenario config | expectedSandboxErr or equivalent configuration, not card/BIN number. |
Example Metadata
The public docs intentionally do not expose the full internal BIN list. The shape is:
| Field | Meaning |
|---|---|
prefix | Matching card prefix used by longest-prefix lookup |
iin | IIN value, usually derived from the prefix |
network | VISA, MASTERCARD, TROY, AMEX, etc. |
issuer | Resolved sandbox issuer label; not a real issuer decision engine |
country | Country metadata used as a routing input |
brand | Sandbox card product label |
type | CREDIT, DEBIT, or PREPAID |
phone | Sandbox metadata field from the BIN record |