CVV Validation API: How Card Security Code Checks Work

A CVV validation API checks the 3 or 4 digit security code on a payment card during a card-not-present transaction. It sends the code to the issuing bank and returns a result such as match, no match, or not processed. The check confirms the code, not the card number, the billing address, or the funds in the account.

cvv validation api

What Does a CVV Validation API Check?

Three things happen in sequence, and they are easy to confuse.

related article

• Length and format. The API confirms the field holds digits and the right number of them.
• Presence. Many processors return a distinct code when the customer leaves the field empty.
• Issuer match. The issuer compares the submitted code against the value tied to that card.

The third check is the one that matters. The first two run on your side and need no network call.

Top CVV Test API Example: A Comprehensive Guide

How many digits does each card use?

• Visa, Mastercard, Discover: three digits on the back, to the right of the signature strip.
• American Express: four digits on the front, above the card number.
• UnionPay and most regional networks: three digits on the back.

Names differ by network. CVV2, CVC2, CID, and CSC all mean the same field.

Does a CVV check use the Luhn algorithm?

No. Luhn validates the card number, not the security code. A common error in homemade validation code is running a Luhn check on the CVV and rejecting valid cards.

What Data Does the Request Need?

A standard authorization call carries the same fields for every card-not-present purchase.

• Card number, typed or tokenized
• Expiry month and year
• The 3 or 4 digit security code
• Amount and currency
• Cardholder name and billing address, used for address verification

The code travels with the authorization request and is dropped from the response. If a gateway echoes the code back anywhere in the payload, stop and ask why.

How Does the Check Flow Through a Payment?

1. The customer types the card number, expiry date, and security code into the checkout form.
2. The form posts the data to your gateway or processor over an encrypted connection.
3. The processor builds an authorization request with the code attached.
4. The issuer compares the code with its records.
5. The response carries two answers: an approval or decline, plus a CVV result code.

Those two answers can disagree. A transaction may authorize while the CVV result comes back as no match, and your business rules decide what happens next.

What Do the CVV Result Codes Mean?

Codes vary by network and processor, but most map to the same ideas.

• M or Y: match. The code the customer entered is correct.
• N: no match. The code is wrong.
• P: not processed. The issuer did not run the check.
• S: the code should have been on the request but was missing.
• U: the issuer cannot verify, often because it does not participate.
• X: no response from the network.

Read your processor's documentation before you act on a code. Some gateways add their own values, and a few map several network codes to a single letter.

Why PCI DSS Forbids Storing the CVV

PCI DSS Requirement 3.2 lists the CVV as sensitive authentication data. Merchants may not store it after authorization, not even in encrypted form. That rule shapes what any CVV validation API can be.

An API of this kind cannot look up a stored code, because no compliant system keeps one. Validation is a live request to the issuer, made once, at the moment of the transaction.

What can you store instead?

Store a payment token from your gateway. The token stands in for the card number on later charges, and the customer re-enters the security code or the issuer handles it through a network token. Nothing in that flow exposes the code.

Should You Build One or Use a Gateway Endpoint?

Most merchants call an endpoint that already exists. Stripe, Adyen, Braintree, and similar providers expose CVV checks as a field on the authorization call. You set a flag, read the response code, and decide what a no-match means for your order flow.

Direct issuer connections require sponsorship from an acquiring bank, network certification, and an annual audit. That path fits large processors, not a single store.

Common Mistakes With CVV Checks

• Blocking every no-match. Issuers return U and P for reasons that have nothing to do with fraud, and hard declines cost you sales.
• Storing the code in logs. Debug output often captures full request bodies, which puts you out of compliance.
• Treating a match as proof of identity. A thief who holds stolen card data usually has the code too.
• Validating only in the browser. Client-side checks help the customer, but they are never a control.

FAQ

Is CVV validation the same as AVS?

No. AVS compares the billing address and postal code with the issuer's records. CVV compares the security code. Processors run both inside the same authorization request and return separate result codes.

What is a test CVV used for?

Sandbox environments publish fixed card numbers and codes that trigger a specific result. Developers use them to test a match, a no-match, and a not-processed response without touching a real card.

Does a CVV check stop fraud?

It lowers card-not-present fraud, and card networks treat it as one input among several. It does not stop a thief who already holds the full card data, and it never replaces address checks, velocity rules, or 3D Secure.

Can an API validate a card without charging it?

Some processors offer a zero-dollar or one-dollar authorization for card-on-file setup, and those calls often include a CVV check. Confirm the terms with your processor, because network rules limit how you may use them.