Circle APIs Documentation

Learn how to integrate with Circle APIs to accept traditional and USDC payments, automate payouts, embed digital dollar accounts into your product or service, or power your internet marketplace.

Verifying Card Details

Why is verifying card details important?

As with other types of "pull" payment methods, card transactions are reversible. In other words, you might assume a payment has been completed and it is final, only to find out weeks later that it has been reversed.

While reversible payments are useful for end users and provide them with stronger protection, they are also a reason to think very carefully about how to minimize payment reversals. End users have several reasons to pursue a payment reversal, but many times the root cause is a fraudulent transaction in the first place.

🚧

Fraud Liability

You are ultimately liable for any and all losses caused by fraudulent transactions or other types of payment reversals.

Essentially you want to have a reasonable level of certainty that the end user using your product is actually in control of the payment method being used. Verifying card details is a tool to help ensure that is the case.

CVV Verification

What is CVV?

CVV stands for card verification value, also known as card verification code (CVC). It is a code part of a debit or credit card that is private to the end user. Asking for the CVV of a debit or a credit card is a way to increase the level of confidence that the end user is actually in physical possession of the card, given that databases of stolen cards often don't include the CVV.

The CVV Check

The CVV check can be performed at the time of card creation, as well as at the time of payment creation. You can use it in one of those operations, or in both.

If your use case benefits from creating card objects that will be used for multiple payments in the future, you might want to consider running the CVV check at card creation time. If the CVV check is successful at the time of card creation, you can assume that card is "good" for future payments, and you can opt not to run CVV checks for subsequent payments for that card.

You can come up with more sophisticated rules where you run CVV checks for subsequent payments depending on the payment amount (if it's significantly higher than usual) and other risk variables. Keep in mind that not running CVV checks during payments time significantly reduces your ability to dispute payment reversals later on.

If your use case does not benefit from creating card objects that will be used for multiple payments in the future, you might want to consider not running the CVV check at card creation time, and instead run the check consistently at payments time.

As mentioned earlier, collecting the CVV from your end user and running a positive check can help you dispute payment reversals once they happen.

The CVV is always sent to the API endpoints in an encrypted way inside the encryptedData object. Check the encryption section of the accepting card payments guide for more details.

CodeDescription
pendingCheck in progress
passValue matched
failValue not matched
unavailableCard issuer does not support CVV check
not_requestedCheck not requested (only for payment request - CVV is always attempted for card creation)

Address Verification

What is AVS?

Address Verification Service (AVS) is another mechanism that customers can use to prevent card fraud. The address verification service compares the billing address submitted by the end user against the billing address kept on file by the card issuer.

📘

AVS Coverage

The address verification check only applies to cards issued in the United States, Canada, and the United Kingdom.

The AVS Check

The address verification check is executed automatically for every card creation and payment creation transaction. The check can compare 2 distinct parts of the end user's billing address: the postal code, and the first address line.

CodeSummaryDescription
APartial matchStreet address matches, but both 5-digit and 9-digit ZIP Code do not match.
BPartial matchStreet Address Match for International Transaction. Postal Code not verified due to incompatible formats.
CVerification unavailableStreet Address and Postal Code not verified for International Transaction due to incompatible formats.
DFull Match (International Transaction)Street Address and Postal Code match for International Transaction.
EData invalidAVS data is invalid or AVS is not allowed for this card type.
FFull Match (UK only)Street address and postal code match. Applies to U.K. only.
GVerification unavailableNon-US Issuer does not participate.
IVerification unavailableAddress information not verified for international transaction.
KAddress mismatchCard member’s name matches but billing address and billing postal code do not match.
LPartial matchCard member’s name and billing postal code match, but billing address does not match.
MFull match (International Transaction)Street Address match for international transaction. Address and Postal Code match.
NNo matchNo match for address or ZIP/postal code.
OPartial matchCard member’s name and billing address match, but billing postal code does not match.
PPartial match (International Transaction)Postal code match. Acquirer sent both postal code and street address, but street address not verified due to incompatible formats.
RVerification unavailableIssuer system unavailable, retry.
SVerification unavailableAVS not supported
UVerification unavailableAddress unavailable
WPartial matchPostal code matches but address does not match
XFull matchStreet address and postal code match
YFull matchStreet address and postal code match
ZPartial match5 digit zip code match only
-Verification unavailableAn error occurred attempting AVS check

Running CVV and AVS Checks

Card Creation Time

The results of the verification checks are returned in the verification property of the response. The checks are done asynchronously so the value of verification.cvv and verification.avs will be initially be returned as pending. You will need to poll the GET /cards/{id} endpoint or use a subscription notification to wait for the checks to complete and inspect the returned values.

For more details, check the create card endpoint.

Payment Time

When creating a payment, you have 2 options in terms of card verification. If the value of the verification property in the request is cvv then a CVV check will be performed, with a value of none the CVV check is skipped. As with the card creation request the verification results will be returned in the verification property of the payment response.
If a CVV check is requested and the result is not pass then the payment will be failed. An AVS check will be performed for both cvv and none values but the payment will not be failed in the case of a mismatch.
For more details, check the create payments endpoint.

Updated about a month ago


Verifying Card Details


Suggested Edits are limited on API Reference Pages

You can only suggest edits to Markdown body content, but not to the API spec.