Search

Are you looking for test card numbers?

Would you like to contact support?

Risk-management icon

Address Verification System (AVS)

Set up and use Address Verification System (AVS) checks to reduce fraud risk.

The Address Verification System (AVS) is a service that verifies if a billing address matches the address of a credit card holder. AVS is a widely used fraud-prevention measure for Card Not Present (CNP) transactions, such as online payments or point-of-sale Mail Order/Telephone Order (MOTO) payments.
AVS gives you a way to check if the shopper who is placing the order is the same person as the credit card holder, which is more likely if the billing address details match.

How does AVS work?

When a shopper pays for a transaction, you can collect their billing address details. Then, you send that data in the billingAddress object in the payment authorisation request. When you've enabled AVS, the system will check if and to what extent these billing address details match the issuing bank's credit card holder information on file.

The response to the payment request will contain an Adyen AVS response code that is mapped to a raw AVS response code. You can see the mapping in the mapping table.

When the AVS check results in a mismatch, you can trigger a risk rule. You can use the standard risk rule Billing address does not match cardholder address, or you can create a custom risk rule. Based on the AVS response, you can decide what to do with the payment: you can accept, make an exception, or cancel a transaction.

AVS is supported for card payments with Visa, MasterCard, Discover or American Express. Credit card issuers in the United States, Canada, and the United Kingdom must support AVS verification requests when you send them in, however, using AVS is not mandatory for you as a merchant.

Enable and test AVS

To be able to trigger AVS and the AVS risk rules, you set up your payment authorisation requests to include billing address details. How you do that depends on your integration. Follow the instructions below that are relevant for you.

AVS in API requests

  1. Collect the shopper's billing address.

    • Checkout API: Make sure that you collect the shopper's billing address details to include them in the /payments request. If you're using a client-side integration for Web, the Web Drop-in and Card Component can be configured to collect your shopper's billing address.
    • Classic integration: Make sure that you collect the shopper's billing address details to include them in the /authorise request.
  2. Send the collected billing address information in the payment authorisation request. Provide the full address of the shopper using the billingAddress child element:

    {
      "billingAddress":
      {
        "country":"US",
        "city":"SF",
        "street":"Example street",
        "houseNumberOrName":"40",
        "stateOrProvince":"CA",
        "postalCode":"91351"
      }
    }
    <billingAddress xmlns="http://payment.services.adyen.com">
      <country xmlns="http://common.services.adyen.com">US</country>
        <city xmlns="http://common.services.adyen.com">SF</city>
        <street xmlns="http://common.services.adyen.com">Example street</street>
        <houseNumberOrName xmlns="http://common.services.adyen.com">40</houseNumberOrName>
        <stateOrProvince xmlns="http://common.services.adyen.com">CA</stateOrProvince>
        <postalCode xmlns="http://common.services.adyen.com">91351</postalCode>
      </billingAddress>
    billingAddress.country=US&billingAddress.street=Example+street&billingAddress.houseNumberOrName=40&billingAddress.postalCode=91351&billingAddress.stateOrProvince=CA&billingAddress.city=SF
    • When you submit the billingAddress object for AVS, the following child elements are required:
    Field Type Required Description
    country String -white_check_mark- The country value format needs to adhere to the ISO 3166-1 alpha-2 standard. An invalid country code results in a transaction/request rejection. You can look up country codes on the ISO website.
    city String -white_check_mark- The name of the city.
    street String -white_check_mark- The name of the street.
    houseNumberOrName String -white_check_mark- The number or name of the house.
    postalCode String -white_check_mark- A maximum of five digits for an address in the US, or a maximum of ten characters for an address in all other countries.
    stateOrProvince String -x- Required for for shoppers from the UK, US or Canada. Provide the child element stateOrProvince as defined in ISO 3166-2. For example, CA in US or ON for Canada. AVS does not validate stateOrProvince.
    • Pass address lines, like apartment or unit number, as part of street.
    • If you don't know the country or are not collecting the country from the shopper, provide country as ZZ.

    To qualify for better interchange rates submit the billing address and ZIP code for card not present transactions. This is not guaranteed, contact Support Team to learn more.

AVS for Hosted Payment Pages (HPP)

To turn on AVS for an HPP skin:

  1. Go to Customer Area > Account > Skins.
  2. Find and select the [Skin Code] that you want to edit.
  3. Under Skin Options, select the Billing Address Fields (AVS) check box. 

    The AVS setting is skin-specific. You must turn it on for each skin to apply AVS.

For a list of parameters required for this call, refer to HPP billing address and AVS fields.

You can choose to have the HPPs pre-populate the billing address information from your own system, as shown below:

    <input type="hidden" name="billingAddressType" value="1" />
    <input type="hidden" name="billingAddress.country" value="US" />
    <input type="hidden" name="billingAddress.city" value="SF" />
    <input type="hidden" name="billingAddress.street" value="Example Street" />
    <input type="hidden" name="billingAddress.houseNumberOrName" value="40" />
    <input type="hidden" name="billingAddress.stateOrProvince" value="CA" />
    <input type="hidden" name="billingAddress.postalCode" value="91351" />

Test AVS results

To test your system's response to receiving an avsResult:

  1. Use our provided AVS test cards and billing addresses or create your own test cards.
  2. Include and define all the required billingAddress parameters.
  3. Set the value of street to Test AVS result.
  4. Set the value of houseNumberOrName to the AVS response code that you want to test from the mapping table. This table shows AVS response codes returned by Adyen, which are mapped to raw AVS response codes from acquirers.

Use AVS risk rules

You can use and configure the standard consistency risk rule Billing address does not match cardholder address.

Alternatively, you can configure custom risk rules using AVS responses. In your custom rule, for the field avsResponseCode, you can use the Adyen response values from the mapping table to define the risk rule behavior.

AVS responses and mapping

Different card brands and networks have specific AVS response codes. Many of them are mapped to the response codes that you receive from Adyen. We also have a number of Adyen AVS response codes to accommodate acquirers that send in slightly different raw AVS responses.

For the mapping of AVS results for point-of-sale MOTO transactions with AVS, refer to AVS responses for point of sale.

If you prefer to receive the actual response code from the card or network, you can turn these on in your Customer Area:

  1. Log in to your Customer Area.
  2. Go to Account > API URLs > Additional data settings.
  3. Select the Acquirer result and Raw acquirer result check boxes.

Should you experience any issues, contact Support Team.

AVS Adyen response code Description AVS Raw response code Description Applies to
0 Unknown. - Adyen did not receive an answer from the issuing bank. You can allow or disallow transactions with an unknown AVS result through the AVS consistency rule options. All issuers
1 Address matches, but the postal code does not match. A

Visa and MasterCard: Address matches, postal code does not.

American Express: Address only matches.

Visa, MasterCard, American Express
2 Neither postal code nor address match. N Neither address nor postal code matches. Visa, MasterCard, Discover, American Express
3 AVS unavailable. U, S, R

U: No data from issuer/Authorization Platform. Discover: System unavailable or timed out.

S: AVS currently not supported.

R: System unavailable or timed out. Discover: Not applicable.

Visa, MasterCard, Discover, American Express
4 AVS not supported for this card type. - - Any other credit card apart from Visa, MasterCard, Discover, American Express
5 No AVS data provided. - - Visa, MasterCard, Discover, American Express
6

Postal code matches, but the address does not match.

W, Z, T

W - MasterCard only: For U.S. addresses, nine-digit postal code matches, address does not; for address outside the U.S., postal code matches, address does not.

Z - Visa: for U.S. addresses, either five-digit or nine-digit postal code matches, address does not.

Z - MasterCard and Discover: for U.S. addresses, five-digit postal code matches, address does not.

Z - American Express: only postal code matches.

T - Discover only: for U.S. addresses, nine-digit postal code matches, address does not.

Visa, MasterCard, Discover, American Express
7 Both postal code and address match. A, D, F, M, X, Y

D: Visa only. Street address and postal code match.

F: Visa only. Street address and postal code match. Applies to U.K. only.

M: Visa only. Street address and postal code match.

X - Visa and American Express: not applicable.

X - MasterCard: For U.S. addresses, all postal code digits match; for addresses outside the U.S., postal code and address match.

X - Discover: For U.S. addresses, nine-digit postal code and address match.

A - Discover: Address and five-digit postal code match.

Y - Visa: For U.S. addresses, five-digit postal or nine-digit postal code matches.

Y - MasterCard: For U.S. addresses, five-digit postal code and address matches.

Y - Discover: Address only matches.

Y - American Express: Postal code and address matches.

Visa, MasterCard, Discover, American Express
8 Address not checked, postal code unknown. - Only used for acquirers that do not use a standard AVS raw response. Visa, MasterCard, Discover, American Express
9 Address matches, postal code unknown. - Only used for acquirers that do not use a standard AVS raw response. Visa, MasterCard, Discover, American Express
10 Address doesn't match, postal code unknown. - Only used for acquirers that do not use a standard AVS raw response. Visa, MasterCard, Discover, American Express
11 Postal code not checked, address unknown. - Only used for acquirers that do not use a standard AVS raw response. Visa, MasterCard, Discover, American Express
12 Address matches, postal code not checked. B Visa only. Street address match. Postal code not verified because of incompatible formats. (Acquirer sent both street address and postal code.) Visa
13 Address doesn't match, postal code not checked. - Only used for acquirers that do not use a standard AVS raw response. Visa, MasterCard, Discover, American Express
14

Postal code matches, address unknown.

- Only used for acquirers that do not use a standard AVS raw response. Visa, MasterCard, Discover, American Express
15

Postal code matches, address not checked.

P Visa only. Postal codes match. Street address not verified because of incompatible formats. (Acquirer sent both street address and postal code.) Visa
16 Postal code doesn't match, address unknown. - Only used for acquirers that do not use a standard AVS raw response. Visa, MasterCard, Discover, American Express
17 Postal code doesn't match, address not checked. - Only used for acquirers that do not use a standard AVS raw response. Visa, MasterCard, Discover, American Express
18 Neither postal code nor address were checked. C, G, I

C: Visa only. Street address and postal code not verified because of incompatible formats. (Acquirer sent both street address and postal code.)

G: Visa only. Non-AVS participant outside the U.S.; address not verified for international transaction.

I: Visa only. Address information not verified for international transaction.

Visa
19 Name and postal code matches. - Only used for acquirers that do not use a standard AVS raw response. Visa, MasterCard, Discover, American Express
20 Name, address and postal code matches. - Only used for acquirers that do not use a standard AVS raw response. Visa, MasterCard, Discover, American Express
21 Name and address matches. - Only used for acquirers that do not use a standard AVS raw response. Visa, MasterCard, Discover, American Express
22 Name matches. - Only used for acquirers that do not use a standard AVS raw response. Visa, MasterCard, Discover, American Express
23

Postal code matches, name doesn't match.

- Only used for acquirers that do not use a standard AVS raw response. Visa, MasterCard, Discover, American Express
24

Both postal code and address matches, name doesn't match.

- Only used for acquirers that do not use a standard AVS raw response. Visa, MasterCard, Discover, American Express
25

Address matches, name doesn't match.

- Only used for acquirers that do not use a standard AVS raw response. Visa, MasterCard, Discover, American Express
26 Neither postal code, address nor name matches. - Only used for acquirers that do not use a standard AVS raw response. Visa, MasterCard, Discover, American Express

See also