CVV Test Framework: Test Card Verification Values Safely

What is a CVV test framework?

A CVV test framework is a set of sandbox card numbers, fixed test CVV values, and automated test cases that check how your payment code reads, transmits, and handles the card verification value. It runs against a processor sandbox, never a live account, and it proves two things: valid codes approve, and bad codes decline with the expected error.

read more

Teams run it before launch, after every gateway upgrade, and whenever a checkout change touches the card form.

related article

What does the CVV prove at authorization?

The CVV is a short code printed on the card but left out of the magnetic stripe and chip data. Visa, Mastercard, and Discover use three digits. American Express uses a four-digit card identification number, or CID.

related article

The issuer compares the submitted value against its own record and returns one of three results: match, no match, or not processed. A no-match result means the number was mistyped or the card data came from somewhere other than the plastic.

Where do test CVV values come from?

Processor sandboxes

Payment providers publish test card numbers that behave like real ones. Stripe, Adyen, Braintree, Checkout.com, and CyberSource all list test PANs with matching CVC values in their developer docs.

Each test number maps to a fixed result. One approves. Another returns a CVV mismatch. A third returns a generic decline. You pick the number that triggers the path you want to test.

Why the test values are fixed

Sandbox card numbers are wired to specific CVCs and specific responses. Change one digit and the outcome flips. That predictability is the point: a test can assert on a known decline code instead of guessing.

Which cases belong in the suite?

• Valid CVV with a valid card number and future expiry: expect approval.
• Wrong CVV length, such as two digits for Visa or three for Amex: expect a validation error before any network call.
• Non-numeric input: expect the form to reject it.
• Correct card number, wrong CVV for that test card: expect a CVV no-match decline code.
• CVV matched but AVS failed: expect the decline or the review flag your gateway defines.
• Missing CVV on a card-not-present charge: expect behavior that matches your risk settings.
• Repeated submit of the same request: expect idempotency, so the buyer is not charged twice.
• 3D Secure challenge flow: expect the CVV check to survive the redirect and the return leg.

How do you build the framework?

1. Pull the test card list and matching CVC values from each processor you support.
2. Store them as fixtures in a config file, kept apart from production credentials.
3. Write table-driven tests where each row holds a card number, a CVV, and the expected result.
4. Mock or sandbox the processor call so the suite runs without network flakiness.
5. Assert on structured response fields, such as the decline code, not on the human-readable message.
6. Add a scan that checks logs, fixtures, and database rows for the literal CVV string after each run.

What breaks in real integrations?

• The CVV lands in an application log or an error tracker. That is a compliance failure waiting on an audit.
• Tests assert on the full decline message. Gateway copy changes and the suite goes red for no reason.
• Sandbox test values leak into production config and a live charge goes out with a fake card.
• Nobody tests the CVV field on mobile keyboards, where numeric pads and paste behavior differ.
• The CVV gets written to a database column for debugging and never removed.

Can you store a CVV after authorization?

No. PCI DSS classifies the CVV as sensitive authentication data and forbids keeping it after authorization, whether encrypted or hashed. Your test framework should enforce that rule, not work around it.

Vault the card with the processor, keep a token, and drop the code the moment the authorization response arrives.

FAQ

What is a test CVV number?

A test CVV is a fixed value tied to a sandbox card number and published by a payment processor. It triggers a known result in a test environment and has no connection to any real account.

Is CVV the same as CVC?

They are the same field under different names. Visa calls it CVV2, Mastercard uses CVC2, Discover uses CID, and American Express uses a four-digit CID. Your code should treat all of them as one input with network-specific length rules.

Why does a valid card decline on CVV in the sandbox?

In most cases the test CVC does not match that specific test card number, or the card is configured to return a mismatch. Check the processor test table and the decline code before you debug your own logic.

Does a CVV mismatch mean fraud?

No. It means the code did not match the issuer record. Typos, a reissued card, and shared card details all produce the same result.