What a card test scenario generator does
A card test scenario generator creates synthetic card records paired with the response a payment gateway should return for each one. You give it a list of outcomes, such as approve, do not honor, insufficient funds, expired card, or 3D Secure challenge, and it returns sandbox card numbers that route to those outcomes. Every number it produces passes the Luhn check so your form validation and tokenization code run the same path they would in production, and every number comes from a processor test BIN range, so no real account is involved.
Teams use it for integration tests, QA regression runs, load tests, and sales demos. It is a development tool. It is not a way to check whether a live card works, and it should never be pointed at a production payment endpoint or loaded with real cardholder data.
Card Test Case Generator Guide
Prerequisites
- A sandbox merchant account with your processor, with test API keys issued.
- The processor's published test BIN list and its decline code reference.
- A language runtime and test framework, for example Python with pytest or Node with Jest.
- A written note from your compliance lead confirming the environment holds no live cardholder data.
Build the generator
- List every response your checkout must handle. Pull the exact codes from the processor decline table and include soft declines, hard declines, and authentication-required outcomes.
- Map each response to the test BIN or test card the processor documents for it. Some processors use one BIN plus a fixed amount trigger, others use a dedicated number per outcome.
- Write a Luhn check digit function. Take the digits left of the final position, double every second digit from the right, subtract nine from any result over nine, sum, then use the value that makes the total a multiple of ten.
- Assemble each card number from a test BIN, a fixed length filler, and the computed check digit. Keep total length at 16 digits unless the processor states otherwise.
- Attach the scenario metadata: expiry, CVV, cardholder name, currency, amount, expected response code, and whether a 3D Secure challenge is expected.
- Define the output schema as JSON with fields for pan, exp_month, exp_year, cvv, amount, currency, expected_code, and requires_3ds.
- Seed your random filler so the same seed always produces the same set of cards. Reproducible failures are the whole point of a generator.
- Wire the generator into your test suite as a fixture so each test pulls a fresh scenario instead of a hardcoded number.
- Add edge cases: expired date, mismatched CVV, zero amount, currency not supported by the merchant account, and a card number that fails Luhn.
- Run every scenario against the sandbox, record the actual response code, and fail the run when actual and expected diverge.
Guardrails
Keep the generator behind a test-only build flag. Reject any BIN that is not on the processor test list, and refuse to emit a number whose issuer identification number belongs to a live range. Log scenario IDs, never full PANs. Rotate sandbox keys on the same schedule as production keys. If a test needs a real issuer response, ask the processor for a certified test account rather than reaching for a live card.
Review the scenario list whenever you upgrade the processor SDK, because decline codes and test BINs change between API versions and a stale expectation will hide a real regression.