About Address Verification

The Address Verification System (AVS) compares purchaser-provided address data against card holder 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 card holder.

At the end of the 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

AVS attempts to match address data provided by the purchaser with the card holder'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 card holder, 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 user object that represents the card holder.
  • The parent user object associated with the card holder.
  • The business object associated with the card holder.
  • The card.fulfillment.shipping object associated with the card.
  • The bulkissuance.fulfillment.shipping object associated with the card.
  • The cardproduct.fulfillment.shipping object associated with the card.

For example, if the user object that represents the card holder does not contain address data, AVS attempts to match the address data contained in the parent user object.

Note: At transaction time, the card holder must provide the merchant with the address that AVS expects, but it might not be the personal address of the card holder. For example, an expense card can be associated with the address of the employee's office or another corporate address. You should make card holders aware of which address they should provide merchants for AVS purposes.

Configuring AVS behaviors

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 card holder 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.

"address_verification": {
"auth_messages": {
"validate": true,
"decline_on_address_number_mismatch": false,
"decline_on_postal_code_mismatch": true
}
}

Note: To review your card product's AVS configuration, send a GET 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

The AVS process changes depending on the type of transaction.

Verifying authorizations and account verifications

The following diagram outlines how AVS handles authorization and account verification messages.

For example, when a card holder attempts to make a purchase, the following process occurs:

  1. The merchant sends an authorization message to the card network.
  2. The card network sends an authorization message to the Marqeta platform.
  3. 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.
  4. 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.
  5. The Marqeta platform returns an authorization response to the card network.
  6. The card network returns an authorization response to the merchant.

Verifying digital wallet token requests

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:

  1. The digital wallet sends a token request to the card network.
  2. The card network sends a token request to the Marqeta platform.
  3. If AVS is enabled for in-app provisioning, AVS determines if the provided address data matches the address data held on file.
  4. 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.
  5. The Marqeta platform returns a DECISION_GREEN response to the card network.
  6. The card network provisions a token to the digital wallet.

Reviewing AVS data

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.

"address_verification" : {
"request" : {
"street_address" : "2000 High St",
"postal_code" : "94601"
},
"on_file" : {
"street_address" : "2000 High Street",
"postal_code" : "94601"
},
"response" : {
"code" : "0000",
"memo" : "Address and postal code match"
}
}

AVS response codes

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* Not validated*

Note: An AVS response of "Not validated" indicates AVS did not attempt a match determination due to card product configurations. However, the Marqeta platform responds to the card network with a successful AVS validation.


Overriding AVS with Just-in-Time Funding

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.