Address Verification Service

Address Verification Service (AVS) is a security feature used to compare the billing address entered by the payer with the records held by the card issuer. An AVS result code is returned in the transaction response message indicating the extent to which the addresses match or fail to match. The merchant application is responsible for deciding how to handle the payment transaction on the basis of the AVS result code. It is also possible to reject a transaction based on the AVS response using the Risk Management service. For more information about Risk Management, contact your payment service provider.

AVS is only supported on some acquirers. Furthermore, not all banks support AVS, so even if AVS data is passed in the transaction request, if the issuing bank does not support AVS, it will not be processed.

The fields used for payer's name and billing address may be used to send address verification information.

Sample Request and Response

This section details a sample AVS request and response.

Sample AVS requests
    {
        "apiOperation": "PAY",
        "order": {
            "amount": "100.00",
            "currency": "EUR",
            "transactionFiltering": {
                "avsResponseCodeRules": [
                    {
                        "avsResponseCode": "ADDRESS_MATCH",
                        "action": "NO_ACTION"
                    },
                    {
                        "avsResponseCode": "ADDRESS_ZIP_MATCH",
                        "action": "NO_ACTION"
                    },
                    {
                        "avsResponseCode": "NAME_ADDRESS_MATCH",
                        "action": "REVIEW"
                    },
                    {
                        "avsResponseCode": "NAME_MATCH",
                        "action": "NO_ACTION"
                    },
                    {
                        "avsResponseCode": "NAME_ZIP_MATCH",
                        "action": "REJECT"
                    },
                    {
                        "avsResponseCode": "NOT_AVAILABLE",
                        "action": "REVIEW"
                    },
                    {
                        "avsResponseCode": "NOT_REQUESTED",
                        "action": "NO_ACTION"
                    },
                    {
                        "avsResponseCode": "NOT_VERIFIED",
                        "action": "REJECT"
                    },
                    {
                        "avsResponseCode": "NO_MATCH",
                        "action": "REVIEW"
                    },
                    {
                        "avsResponseCode": "SERVICE_NOT_AVAILABLE_RETRY",
                        "action": "NO_ACTION"
                    },
                    {
                        "avsResponseCode": "SERVICE_NOT_SUPPORTED",
                        "action": "REJECT"
                    },
                    {
                        "avsResponseCode": "ZIP_MATCH",
                        "action": "REVIEW"
                    }
                ]
            }
        },
        "sourceOfFunds": {
            "provided": {
                "card": {
                    "expiry": {
                        "month": "05",
                        "year": "20"
                    },
                    "number": "<16 digit card number>"
                }
            },
            "type": "CARD"
        }
    }
    
    
Sample AVS response
  
        {
            "gatewayEntryPoint": "WEB_SERVICES_API",
            "merchant": "AVSCSC_PAY",
            "order": {
                "amount": 100.00,
                "authenticationStatus": "AUTHENTICATION_NOT_IN_EFFECT",
                "chargeback": {
                    "amount": 0,
                    "currency": "EUR"
                },
                "creationTime": "2022-04-28T13:36:22.376Z",
                "currency": "EUR",
                "id": "831941870",
                "lastUpdatedTime": "2022-04-28T13:36:22.758Z",
                "merchantAmount": 100.00,
                "merchantCategoryCode": "6879",
                "merchantCurrency": "EUR",
                "status": "CAPTURED",
                "totalAuthorizedAmount": 100.00,
                "totalCapturedAmount": 100.00,
                "totalDisbursedAmount": 0.00,
                "totalRefundedAmount": 0.00,
                "transactionFiltering": {
                    "avsResponseCodeRules": [
                        {
                            "action": "NO_ACTION",
                            "avsResponseCode": "ADDRESS_MATCH"
                        },
                        {
                            "action": "NO_ACTION",
                            "avsResponseCode": "ADDRESS_ZIP_MATCH"
                        },
                        {
                            "action": "REVIEW",
                            "avsResponseCode": "NAME_ADDRESS_MATCH"
                        },
                        {
                            "action": "NO_ACTION",
                            "avsResponseCode": "NAME_MATCH"
                        },
                        {
                            "action": "REJECT",
                            "avsResponseCode": "NAME_ZIP_MATCH"
                        },
                        {
                            "action": "REVIEW",
                            "avsResponseCode": "NOT_AVAILABLE"
                        },
                        {
                            "action": "NO_ACTION",
                            "avsResponseCode": "NOT_REQUESTED"
                        },
                        {
                            "action": "REJECT",
                            "avsResponseCode": "NOT_VERIFIED"
                        },
                        {
                            "action": "REVIEW",
                            "avsResponseCode": "NO_MATCH"
                        },
                        {
                            "action": "NO_ACTION",
                            "avsResponseCode": "SERVICE_NOT_AVAILABLE_RETRY"
                        },
                        {
                            "action": "REJECT",
                            "avsResponseCode": "SERVICE_NOT_SUPPORTED"
                        },
                        {
                            "action": "REVIEW",
                            "avsResponseCode": "ZIP_MATCH"
                        }
                    ]
                }
            },
            "response": {
                "acquirerCode": "0000",
                "cardSecurityCode": {
                    "acquirerCode": "M",
                    "gatewayCode": "MATCH"
                },
                "cardholderVerification": {
                    "avs": {
                        "acquirerCode": "M",
                        "gatewayCode": "ADDRESS_ZIP_MATCH"
                    }
                },
                "gatewayCode": "APPROVED",
                "gatewayRecommendation": "NO_ACTION"
            },
            "result": "SUCCESS",
            "risk": {
                "response": {
                    "gatewayCode": "ACCEPTED",
                    "review": {
                        "decision": "NOT_REQUIRED"
                    },
                    "rule": [
                        {
                            "data": "M",
                            "name": "MERCHANT_AVS",
                            "recommendation": "NO_ACTION",
                            "type": "MERCHANT_RULE"
                        },
                        {
                            "data": "512345",
                            "name": "MERCHANT_BIN_RANGE",
                            "recommendation": "NO_ACTION",
                            "type": "MERCHANT_RULE"
                        },
                        {
                            "data": "M",
                            "name": "MERCHANT_CSC",
                            "recommendation": "NO_ACTION",
                            "type": "MERCHANT_RULE"
                        },
                        {
                            "name": "SUSPECT_CARD_LIST",
                            "recommendation": "NO_ACTION",
                            "type": "MERCHANT_RULE"
                        },
                        {
                            "name": "TRUSTED_CARD_LIST",
                            "recommendation": "NO_ACTION",
                            "type": "MERCHANT_RULE"
                        },
                        {
                            "data": "512345",
                            "name": "MSO_BIN_RANGE",
                            "recommendation": "NO_ACTION",
                            "type": "MSO_RULE"
                        },
                        {
                            "data": "M",
                            "name": "MSO_CSC",
                            "recommendation": "NO_ACTION",
                            "type": "MSO_RULE"
                        }
                    ]
                }
            },
            "sourceOfFunds": {
                "provided": {
                    "card": {
                        "brand": "MASTERCARD",
                        "expiry": {
                            "month": "5",
                            "year": "20"
                        },
                        "fundingMethod": "CREDIT",
                        "number": "512345xxxxxx0008",
                        "scheme": "MASTERCARD",
                        "storedOnFile": "NOT_STORED"
                    }
                },
                "type": "CARD"
            },
            "timeOfLastUpdate": "2022-04-28T13:36:22.758Z",
            "timeOfRecord": "2022-04-28T13:36:22.606Z",
            "transaction": {
                "acquirer": {
                    "batch": 1,
                    "id": "SYSTEST_ACQ1",
                    "merchantId": "123456"
                },
                "amount": 100.00,
                "authenticationStatus": "AUTHENTICATION_NOT_IN_EFFECT",
                "authorizationCode": "OK098Z",
                "currency": "EUR",
                "id": "85290238",
                "receipt": "2204284",
                "source": "INTERNET",
                "stan": "4",
                "terminal": "2345678",
                "type": "PAYMENT"
            },
            "version": "64"
        }
    

AVS API Reference[REST][NVP]

Copyright © 2022 MasterCard