About Address Verification
The Address Verification System (AVS) compares purchaser-provided address data against cardholder address data held on file by the Marqeta platform and makes a match determination. You can configure AVS to decline transactions programmatically based on a mismatched street address or postal code.
AVS is useful for card-not-present environments, such as e-commerce websites, and points of sale without clerks, such as automated fuel dispensers—wherever there is additional need to verify that the person making the purchase is the legitimate cardholder.
At the end of this guide, you should understand:
-
How AVS makes a match determination.
-
The role of AVS in the transaction lifecycle.
-
How the Marqeta platform records AVS decisions.
-
How AVS affects transactions using Just-in-Time (JIT) Funding.
AVS match determinations
Copy section link
AVS attempts to match address data provided by the purchaser with the cardholder’s address data. If the merchant does not provide address data in the transaction message, the Marqeta platform does not attempt address verification.
If you enable AVS for a given transaction type, and the merchant includes the address data of the cardholder, the Marqeta platform’s transaction record includes the purchaser-provided address, the Marqeta platform’s on-file address, and the Marqeta platform’s match determination, which indicates whether the two street addresses and postal codes match.
Multiple resources on the Marqeta platform can contain the on-file address data. AVS checks the following objects for an on-file address, listed in priority order:
-
The
userobject that represents the cardholder. -
The parent
userobject associated with the cardholder. -
The
businessobject associated with the cardholder. -
The
card.fulfillment.shippingobject associated with the card. -
The
bulkissuance.fulfillment.shippingobject associated with the card. -
The
cardproduct.fulfillment.shippingobject associated with the card.
For example, if the user object that represents the cardholder does not contain address data, AVS attempts to match the address data contained in the parent user object.
Tip
At transaction time, the cardholder must provide the merchant with the address that AVS expects, but it might not be the personal address of the cardholder. For example, an expense card can be associated with the address of the employee’s office or another corporate address. You should make cardholders aware of which address they should provide merchants for AVS purposes.
Configuring AVS behaviors
Copy section link
The Marqeta platform defines AVS behaviors at the card product level—AVS behaviors apply to all cards in a card product. AVS match determinations are enabled by default for the following types of transactions:
-
Authorization messages.
-
Account verification messages.
-
Digital wallet token activation requests.
You can disable AVS match determinations for one transaction type, such as authorizations, while enabling it for another, such as account verification messages.
If AVS is enabled for authorization or account verification messages, you can configure the following AVS behaviors, which occur in addition to making the match determination:
-
Decline the transaction based on a mismatched street address (false by default).
-
Decline the transaction based on a mismatched postal code (true by default).
Using the default configuration, AVS declines the transaction if a cardholder provides an incorrect postal code, but not if they provide an incorrect street address.
The Marqeta platform does not decline digital wallet token activation requests based on AVS mismatches. Instead, the Marqeta platform returns a "Not declined" response to the card network, which triggers a request for further verification before provisioning a digital wallet token. See Managing the Lifecycle of Digital Wallet Tokens for more information about additional verification options.
The following code sample shows the address_verification object of a card product.
This object defines AVS behaviors for transactions attempted using cards associated with the card product.
In this example, the Marqeta platform would decline authorizations with mismatched postal code data.
Tip
To review your card product’s AVS configuration, send aGET request to /cardproducts/{token} using your card product’s token as the path parameter.
For a complete description of the /cardproducts endpoint, see Card Products.
AVS at transaction time
Copy section link
The AVS process changes depending on the type of transaction.
Verifying authorizations and account verifications
Copy section link
The following diagram outlines how AVS handles authorization and account verification messages.
For example, when a cardholder attempts to make a purchase, the following process occurs:
-
The merchant sends an authorization message to the card network.
-
The card network sends an authorization message to the Marqeta platform.
-
If the merchant provides address data, and AVS is enabled for authorization messages, AVS determines if the purchaser-provided address data matches the address data held on-file.
-
If AVS is configured to decline transactions due to street address or postal code mismatches, and the street address or postal code do not match, the Marqeta platform declines the transaction; otherwise, the transaction proceeds.
-
The Marqeta platform returns an authorization response to the card network.
-
The card network returns an authorization response to the merchant.
Verifying digital wallet token requests
Copy section link
The following diagram outlines how AVS handles digital wallet token requests.
For example, when a user wants to add a card to their digital wallet, the following process occurs:
-
The digital wallet sends a token request to the card network.
-
The card network sends a token request to the Marqeta platform.
-
If AVS is enabled for in-app provisioning, AVS determines if the provided address data matches the address data held on file.
-
If the street address or postal code do not match, the Marqeta platform returns a DECISION_YELLOW response to the card network; otherwise the transaction proceeds.
-
The Marqeta platform returns a DECISION_GREEN response to the card network.
-
The card network provisions a token to the digital wallet.
Reviewing AVS data
Copy section link
When AVS makes a match determination, it stores the results in the address_verification object within the transaction message.
The address_verification object contains the following AVS data:
Address data sent by the merchant in the transaction message.
Address data held by the Marqeta platform.
A standardized response code and memo that describe the AVS match determination.
The following is a sample address_verification object as it would appear in a transaction notification sent to your webhook endpoint.
AVS response codes
Copy section link
When AVS makes a match determination, the Marqeta platform indicates the results using a standardized response code with a memo that provides more details.
The following table lists the possible response code values based on the AVS match determination:
| Code | Address | Postal Code |
|---|---|---|
0000 |
Match |
Match |
0001 |
Match |
Unmatched |
0002 |
Match |
Data not present |
0100 |
Unmatched |
Match |
0101 |
Unmatched |
Unmatched |
0102 |
Unmatched |
Data not present |
0200 |
Data not present |
Match |
0201 |
Data not present |
Unmatched |
0303 |
Not validated (see note below) |
Not validated (see note below) |
Warning
An AVS response of "Not validated" (code0303) indicates that AVS did not attempt a match determination because the AVS feature has been explicitly disabled for this card product or program.
When AVS is disabled, the Marqeta platform automatically informs the card network that AVS validation was successful, even though no AVS was actually performed. If you choose to disable AVS for your program, you lose the right to submit chargebacks due to fraud. Contact your Marqeta representative for more information.
Overriding AVS with Just-in-Time Funding
Copy section link
If you fund accounts using the Gateway JIT Funding feature, your system can override the AVS match determination by including updated address data in your JIT Funding response. This is useful if your system’s on-file address data is more up to date than what is held by the Marqeta platform.
For more information on overriding AVS match determinations, see Using AVS with JIT Funding. For more information on JIT Funding, see About Just-in-Time Funding.