A CVV test API is a sandbox endpoint that accepts fake card numbers and dummy CVV codes so you can exercise card verification logic without touching real cardholder data. You do not need a real card to test it, and you should not use one. In test mode the CVV is a placeholder: usually any three digits for Visa and Mastercard, four for American Express. The gateway validates format and runs its decline rules. It never checks whether the code matches a real account.
What test mode actually validates
Developers often assume the sandbox is checking the CVV itself. It is not. What you can verify in test mode:
- That your form collects a CVV of the right length for the card brand.
- That your code maps a CVV failure to the correct decline reason and user message.
- That retry and idempotency logic behaves when a payment is rejected.
- That 3D Secure and SCA flows handle a failed verification step.
- That nothing sensitive lands in your logs.
The test values worth memorizing
Stripe is the most common starting point. Card 4242 4242 4242 4242 always succeeds with any three digit CVC and any future expiry. For failure paths, 4000 0000 0000 0002 returns a generic card decline, and 4000 0000 0000 0127 returns an incorrect CVC decline. Adyen and Braintree publish similar lists, each with their own numbers for CVC and address verification outcomes.
Testing a CVV mismatch
Use the gateway's designated incorrect-CVC card rather than inventing a bad code on a success card. That is the difference between testing your error handling and testing nothing. The response should come back as a decline with a reason code such as incorrect_cvc or a CVV2 failure, and your UI should ask the customer to re-enter the code rather than showing a generic failure.
Keeping test and live apart
The single most common incident I look for is a live key leaking into a test environment or a test card reaching production. Guard against both:
- Load keys from environment variables and never commit them.
- Assert the key prefix at startup. Test keys and live keys have different prefixes in most gateways; fail fast if the wrong one appears.
- Block known test card numbers in production builds if your flow allows manual entry.
- Scrub card fields from logs, traces and error reports at the source.
What to assert in your suite
Good tests check behavior, not just status codes. Assert that a CVV decline produces the right internal reason, that the customer sees an actionable message, that no charge is captured, and that the request is safe to retry. Test the same card twice with the same idempotency key and confirm you get one charge, not two.
Rules that do not relax in test mode
PCI DSS still applies to your integration design. You may not store the CVV after authorization, in test or in production, and you should not log it even briefly. Nothing about a sandbox changes that. Treat sandbox credentials like live credentials and keep your test data obviously fake so nobody mistakes it for a real record.
Pitfalls I see often
Hardcoding a test card in a shared fixture and forgetting it. Assuming issuer behavior matches sandbox behavior, when real issuers decline for reasons no test card simulates. Skipping the CVV failure path because the happy path passed. And testing only one card brand, which hides length and formatting bugs for Amex and for cards with no CVV at all.
Cover the success case, one CVV decline, one generic decline, and one timeout. That set catches almost everything before it reaches a real customer.