AVS

Address Verification System (AVS) is a security feature that verifies the billing address of the cardholder. Advantages of AVS include better protection against fraud, and lower interchange (as by performing address verification on your cardholder’s billing information you can qualify for the lowest rate.)

AVS compares the billing address the shopper enters with the one on file at the payment card company. AVS is only supported on a limited set of acquiring connections, card types, and only for a limited set of countries (United States, Canada, and UK).

To use AVS you must supply the full address of the shopper using the billingAddress child element of the payment authorisation request, as shown below:

"billingAddress" : {
  "country" : "US",  
  "city" : "SF",
  "street" : "Example street",
  "houseNumberOrName" : "40",
  "stateOrProvince" : "California",
  "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">California</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, provide the following child elements:

  • city – always required
  • street – always required
  • houseNumberOrName – required in US and Canada.
  • stateOrProvince – required in US and Canada.
  • country – always required
  • postalCode – optional

    See Address for more information about the fields.

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


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 web site.

Different card brands and networks have specific AVS response codes. They are mapped to our generic response codes, which are the ones you receive by default. If you prefer to receive the actual response code from the card or network, contact the Adyen Support Team to request enabling the raw AVS reason for you. After enabling, this information is included in your notifications.

AVS result testing

You can test AVS result values. Assign the appropriate values to the child elements of the billingAddress element, as described below:

Child Element Value to test AVS
street Test AVS result
houseNumberOrName <specify_here_the_avsResult_value_to_test>

You still need to include and define all the other billingAddress child elements, but their values do not impact the avsResult return value you want to test.

You can use a test card number from this list to test AVS results.

Result values

-1 Not sent.
0 Unknown.
1

Address matches, but the postal code does not match.

2

Neither postal code nor address match.

3 AVS unavailable.
4 AVS not supported for this card type.
5 No AVS data provided.
6

Postal code matches, but the address does not match.

7

Both postal code and address match.

8 Address not checked, postal code unknown.
9 Address matches, postal code unknown.
10 Address doesn't match, postal code unknown.
11 Postal code not checked, address unknown.
12 Address matches, postal code not checked.
13 Address doesn't match, postal code not checked.
14 Postal code matches, address unknown.
15 Postal code matches, address not checked.
16 Postal code doesn't match, address unknown.
17 Postal code doesn't match, address not checked.
18 Neither postal code nor address were checked.
19 Name and postal code matches.
20 Name, address and postal code matches.
21 Name and address matches.
22 Name matches.
23 Postal code matches, name doesn't match.
24 Both postal code and address matches, name doesn't match.
25 Address matches, name doesn't match.
26 Neither postal code, address nor name matches.

Questions

Can't find something you are looking for? Look at our FAQ for answers or send an email to support.