How to test CVV validation for UnionPay cards

You test UnionPay CVV checks with sandbox credentials and the test card numbers your payment processor publishes. Send three authorizations: one with the correct CVN2, one with a wrong CVN2, and one with the field left empty. Compare each response against the decline codes listed in your processor's integration guide. This guide covers sandbox testing only. It does not cover live card data, and no test run should ever use a real cardholder account.

Prerequisites

• Sandbox merchant account and API credentials from your acquirer or gateway
• The processor's test card list, including at least one UnionPay test PAN
• Access to the sandbox dashboard or request log viewer
• A written list of expected response codes copied from the integration guide

Procedure

1. Open the test card page in your processor's documentation and copy a UnionPay test PAN, expiry date, and CVN2 value.
2. Point your client at the sandbox base URL and confirm the request carries the test API key, not a production key.
3. Submit an authorization with the matching CVN2 and record the approval response.
4. Resubmit the same PAN with a CVN2 that differs by one digit and record the decline code.
5. Submit again with the CVN2 field omitted and record the validation error the gateway returns.
6. Send a four-digit value in the CVN2 field and confirm the gateway rejects the format before the request reaches the network.
7. Repeat all four cases on every channel you support, such as the card-not-present API, the hosted payment page, and terminal emulation.
8. Map each response to your order state machine so a CVN2 mismatch routes to manual review instead of a silent failure.
9. Save the cases as a regression suite that runs on every release.

What a UnionPay CVN2 value looks like

UnionPay prints a three-digit CVN2 on the signature panel of the card. Test values from your processor follow the same three-digit format, so a four-digit entry is a format error, not a mismatch. Treat the format check and the value check as two separate test cases, because gateways reject them with different codes.

Common mistakes

• Running the test with production keys, which turns a harmless case into a live authorization attempt.
• Storing the CVN2 after authorization. PCI DSS forbids retaining the verification value once the transaction completes, in test or production.
• Assuming decline codes match across processors. Each gateway maps a CVN2 mismatch to its own code, so read the response, not the HTTP status.
• Testing only the approved path. The mismatch and empty-field cases are the ones that expose broken error handling.