Circle APIs Documentation

Learn how to integrate with Circle APIs to accept traditional and stablecoin payments, embed digital wallets 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.

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.

AVS Check Result

Explanation

Complete or full match

Both the street address and postal code provided match the issuer's information. As far as AVS check, this card is good for payments.

Partial match

Either the street address or the postal code provided doesn't match the issuer's information. As far as AVS check, you should proceed with caution for payments on this card.

Check not supported or unavailable

AVS is not supported or available for this card (it could be because the card is from outside the U.S., UK, or Canada). As far as AVS check, you should proceed with caution for payments on this card.

No match or failure

Neither the street address nor the postal code provided match the issuer's information. As far as AVS check, you can still process payments for this card, but you will be doing so at your own risk. You should understand exactly why you are deciding to proceed.

For more lower level details on possible AVS check response codes and how to interpret them across the Visa and Mastercard networks, check the [test card numbers][Test Card Numbers](doc:test-card-numbers#section-address-verification-service-avs-check) page.

Running CVV and AVS Checks

Card Creation Time

When creating a card, you have 2 options in terms of card verification (see below). Use the verification parameter to indicate your choice.

verification value

Result

none

No CVV card verification check is performed.

cvv

CVV check is performed.

As explained earlier, the AVS check is automatically performed. You should check the card creation response to decide on how to act upon the results of that check.

For more details, check the create card endpoint.

Payments Time

When creating a payment, you have 2 options in terms of card verification (see below). Use the verification parameter to indicate your choice.

verification value

Result

none

No CVV card verification check is performed.

cvv

CVV check is performed.

As explained earlier, the AVS check is automatically performed. You should check the payment status to decide on how to act upon the results of that check.

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.