AVS (Address Verification Service) is a fraud-mitigation tool that checks whether the billing address (street address and/or postal code) provided by the cardholder matches the address on file with the card issuer. This helps reduce instances of fraudulent or unauthorized transactions, and increases confidence in approving card payments.

Key benefits:

• Helps reduce chargeback risk and fraud losses
• Adds a validation layer before settlement
• Enables merchants to make better decisioning (accept, decline, or flag)
• Often used in card-not-present (CNP) contexts (e-commerce, MOTO, etc.)

Eligibility & Requirements

📘

AVS fields are required only when AVS requirements are enabled under Settings → Loss Prevention in the MX™ Merchant Portal. If AVS fields are included in a payment request, the AVS check will run regardless of this setting. The configuration simply determines whether these fields are mandatory and how mismatches are handled (for example, auto-decline or manual review).

How It Works

• Enable AVS Requirements: Activate AVS requirements for the merchant via the Loss Prevention settings in the MX™ Merchant Portal.
• Configure AVS Requirements: Define the specific AVS rules for the merchant, including whether fields are required and how mismatches should be handled (auto-decline or manual review).
• Create Payment with AVS details: The cardholder provides their billing address at checkout via the POST /checkout/v3/payment API endpoint. The merchant’s system submits the address along with the authorization request.
• Verify Address with Issuer: The issuing bank compares the submitted billing address and postal/ZIP code with the cardholder’s records. A payment’s AVS (Address Verification Service) compares the billing street and postal code you send to the issuer’s records. In payment requests, AVS data lives inside the cardAccount object as:
  • avsStreet
  • avsZip
• Receive AVS Result: The issuer returns an AVS result code indicating the match status for street address and postal/ZIP code.

Based on the AVS result, the payment processor determines whether to approve, flag, or decline the transaction.

Configure AVS requirements for a Merchant

Use the POST https://sandbox.api.mxmerchant.com/checkout/v3/fraudsetting?merchantId=XXXXXXXXX API endpoint to configure merchant-specific AVS and fraud prevention rules programmatically.

Replace merchantId with the relevant merchant ID.

The settings determine whether AVS fields are required for keyed and swiped transactions and whether mismatches are auto‑declined:

AVS response codes

The AVS codes shared in the response, indicate the result of an address verification check performed during a payment transaction. These codes help merchants understand whether the billing address and postal code provided by the cardholder match the issuer’s records, and guide appropriate actions such as approval, review, or decline of the transaction.

AVS (Address Verification Service) Scenario IDs

If Loss Prevention is set to Auto‑Decline AVS mismatches, the response codes E, G, I, R, S, U, 3, 4 are exempted from auto‑decline and a transaction may still be approved.

Test scenarios

The following tables provide test card numbers and associated AVS, CVV, and EMS scenarios that can be used to validate your payment platform’s handling of various transaction conditions. These scenarios help verify:

• How the system responds to address and CVV verification results
• Partial approvals and decline handling
• Fraud scoring or EMS (Enhanced Merchant Screening) responses
• Transaction limits and approval percentages

Note: These card numbers are for testing purposes only and should not be used for actual payments. Each table corresponds to a specific card brand — Discover, Mastercard, AMEX, and VISA — and includes the expected behavior for AVS, CVV, and EMS checks where applicable.

Card Testing Scenarios — Discover

Card Testing Scenarios — Mastercard

EMS (Enhanced Merchant Screening) simulates risk scoring or fraud evaluation. It helps verify how your platform reacts to fraud scores, reason codes, and approval overrides.

Card Testing Scenarios — AMEX

Card Testing Scenarios — VISA

Troubleshooting

• Approved despite Auto‑Decline setting: Check if the AVS result is on the exempt list above.
• Payment rejected for missing AVS fields: Verify Loss Prevention settings for keyed/swiped requirements.
• High AVS mismatch rate: Confirm you are sending billing address details (not shipping), and normalize address formats.

See also

• Retrieve Payment API
• Cancel Payment API
• Refund Payment API
• Payments lifecycle

Open / Pending items to be discussed

• Need to confirm how to link Loss Prevention > setting to enable AVS requirements , since this is UI . Although the text is mentioned as a note, but how to add more context about it.
• Need to add “Configure AVS requirements for a Merchant” in API Tryouts
• Links for Refund API tryout and Payments lifecycle