The best practices for card test cases are: use sandbox card numbers only, tie each card to one expected outcome, cover the full payment lifecycle, and re-run the suite on every gateway or API change. A documented matrix plus automation catches payment bugs that a folder of random test numbers misses.
The ground rules behind every good card test suite
Payment bugs hide in untested branches. Each rule below closes one of those branches.
- Test numbers only. Real PANs in a test environment turn a QA project into a PCI problem.
- One card, one outcome. Pair a specific number with a specific response so a failure points to one cause.
- Full lifecycle. Authorization, capture, void, refund, partial refund, chargeback, and settlement each need their own cases.
- Declines count as much as approvals. A gateway that accepts everything is broken, not healthy.
- Version the suite with the API. A green run against v1 says nothing about v2.
- Assert on payloads, not just status codes. Compare amounts, currency, auth codes, and idempotency keys.
Top pick: a version-controlled card test matrix
A card test matrix lists every card number, the exact input, the expected response code, and the assertion that proves the result. Kept in the same repo as the integration code, it becomes the source of truth for every release.
Why it wins
- Coverage is visible. A gap in the table is a gap you can name.
- Failures are traceable. One card maps to one behavior, so triage takes minutes.
- Onboarding is fast. A new developer reads the matrix and knows what the system promises.
- It survives processor changes. Swap the numbers, keep the outcomes.
Where it falls short
A matrix is only as good as its upkeep. If nobody updates it when a new decline code ships, the suite lies to you. Budget review time for every payment release.
Three alternatives worth keeping in the toolbox
1. Processor sandbox card sets
Stripe, Adyen, and Braintree publish test numbers that trigger named outcomes, from insufficient funds to 3D Secure challenges. They cost nothing and match production behavior for the processor you use.
Limits: the sets differ by vendor, cover that vendor's quirks, and change with little notice. Pin the ones you depend on.
2. Generated PANs with Luhn and BIN rules
You can generate numbers that pass the Luhn checksum and look like a real BIN range. This works for testing your own validation layer before any network call happens.
Limits: a generated number proves format handling and nothing about authorization. Never use it to stand in for a gateway test.
3. Token vault and network token fixtures
Vault fixtures store a card reference once, then return a token for each test run. They fit subscription, stored-credential, and network token flows where the PAN never returns to your app.
Limits: setup cost is real, and stale fixtures break after card expiry rules change.
How do you build a card test case checklist?
- List every outcome your gateway can return, including declines, timeouts, and duplicate authorizations.
- Assign one test card or token to each outcome.
- Write the expected assertion for each case: response code, amount, currency, and stored state.
- Add negative cases: expired card, wrong CVV, wrong ZIP, mismatched currency, zero amount.
- Automate the run in CI and fail the build on any mismatch.
- Review the matrix when the processor changes its docs or you move API versions.
Which card scenarios must you cover?
- Approved authorization, capture, and settlement.
- Soft decline with a retry path, hard decline with no retry.
- Insufficient funds, expired card, restricted card, reported stolen card.
- CVV mismatch and AVS mismatch, tested apart from each other.
- 3D Secure frictionless flow and challenged flow, including a failed challenge.
- Timeout and retry, plus a duplicate submission with the same idempotency key.
- Partial refund, full refund, and refund after settlement.
- Chargeback and retrieval request handling.
Common mistakes that waste QA time
- Reusing one good card for every test, which hides decline handling.
- Asserting only on HTTP 200 and ignoring the body.
- Sharing test cards across teams with no record of which card means what.
- Testing against live endpoints because the sandbox felt slow.
- Skipping idempotency, then finding duplicate charges in production.
FAQ
How many card test cases is enough?
Enough to cover every response your gateway can send, every lifecycle step, and every decline you plan to handle in the UI. For a typical card-not-present integration that lands between 30 and 60 cases.
Can you test with real cards?
No. Live PANs in a test system expand PCI scope and put cardholder data at risk for no gain. Processor test numbers reproduce the same outcomes.
Do test cards fall under PCI DSS?
Published test numbers are not real cardholder data, so they sit outside that part of PCI DSS scope. The moment a live PAN lands in a test file, scope comes back.
Verdict
Start with a version-controlled card test matrix, then borrow from processor sandbox sets when you need vendor-specific declines. Add token fixtures once stored credentials enter the picture. The tool matters less than the discipline: one card, one outcome, asserted on every build.