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.

AVS primarily supports U.S. and Canadian addresses; however, some issuers may also return AVS results for international (non-US) addresses. When processing non-US cards, the availability and accuracy of AVS may vary depending on the issuing country's support for address verification.

Key benefits:

• Helps reduce chargeback risk and fraud losses
• Adds a validation layer before settlement
• Often used in card-not-present (CNP) transactions, such as e-commerce, MOTO, etc.

---

Configure AVS requirements for a Merchant

The Address Verification System (AVS) enforces address and CVV validation for keyed (manual) transactions to reduce fraud and improve interchange optimization. It adds an additional layer of validation during payment processing by verifying the cardholder’s billing address and ZIP code against issuer records. These checks help detect suspicious activity and reduce the risk of fraudulent transactions.

The below Loss Prevention settings for keyed and swiped transactions can be updated via the POST /checkout/v3/fraudSetting?merchantId={merchantId} endpoint.

These nodes control the AVS behavior when processing a keyed (manual entry) transaction. When these parameters are enabled, the system enforces address, ZIP code, and CVV validation. If any required field is missing or invalid, the transaction is automatically declined, ensuring stronger fraud prevention.

To know more, kindly refer to the Merchant Configuration and Payment Controls.

To implement AVS effectively, consider the following operational requirements:

• Merchants must collect the customer’s billing street address and postal code at checkout to perform verification.
• AVS validation is available only if the card issuer supports AVS for the given card type.
• Merchants should interpret AVS result codes and apply appropriate decision logic (e.g., approve, review, or decline) based on the response.
• All address data collected must comply with applicable privacy and data protection regulations, ensuring secure handling of sensitive customer information.

---

How It Works

• Once enabled, make a POST request to /checkout/v3/payment endpoint with including the AVS fields.

  Parameter	Required	Description
  amount	✓	Amount to charge (in USD currency)
  cardAccount	✓	Valid Payment Card details or a vaulted token Note: You can vault the card for future use using Card Vaulting guide
  merchantId	✓	The Merchant's unique identifier that is used to process the payment.
  tenderType	✓	Set to CARD for card transactions.
  paymentType		Type of transaction. It is defaulted to Sale
  customerName		The name of the customer. Recommended for guest checkout where the card is not vaulted.
  posData		An object containing Point of Sale data. While optional, we highly recommend including this object for all keyed (card-not-present/online) transactions to improve approval rates and potentially lower processing fees. You can view more details of the recommended POS data based on presentment type here.

• Our system processes the payment and returns a response indicating the outcome. You can learn the outcome of the request via GET /checkout/v3/payment/{id} or wait for the Payment webhook You can determine the result by checking the status and responseCode fields in the response.

  • status: The primary outcome of the transaction, either Approved or Declined.
  • responseCode: A detailed code explaining the reason for the status. See our comprehensive Response code guide guide for full list

• 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

• For every approved payment, it is critical to store two identifiers:

  • id : The unique Payment ID. Use this for retrieving or voiding the transaction before it settles.
  • paymentToken: The secure Transaction Token. Use this for follow-up actions like refunds or adjustments after the transaction has settled.

• 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.

AVS Behavior for International Billing Addresses

AVS supports both U.S. and international billing addresses, and any street address or postal/ZIP code can be submitted through our APIs. However, the way this information is processed varies by card network.

Here is how each network handles non-U.S. or non-Canadian AVS data:

Important Notes:

• There is no technical limitation preventing international customers from using the API — the behavior is purely dependent on card-network rules.
• Even if Discover drops or normalizes the AVS data, the transaction will still authorize — it will not be blocked due to missing AVS fields.
• Issuer rules may still apply. If a card issuer requires AVS for fraud screening, missing/modified data (especially for Discover) may influence approval.

Recommendation: Include the raw international address inside the metadata object. This ensures the original data is preserved, even if the network strips or normalizes it.

---

AVS response codes

During every payment transaction, the Address Verification Service (AVS) checks whether the billing address and postal or ZIP code provided by the customer match the records held by the issuing bank. The AVS response codes returned in the API response indicate the outcome of this validation, helping merchants decide whether to approve, review, or decline the transaction.

The table below outlines the standard AVS Scenario IDs and their meanings.

AVS (Address Verification Service) Scenario IDs

When Auto-Decline AVS mismatches is enabled under Loss Prevention settings, the system automatically declines transactions where the provided address or postal code does not match. However, E, G, I, R, S, U, 3, 4 are few of the response codes that are exempted from this rule, meaning that such transactions may still be approved depending on the issuer’s configuration.

---

Test scenarios for AVS, CVV and EMS

To help validate integration and transaction handling, the following test card scenarios simulate various AVS, CVV, and EMS (Enhanced Merchant Screening) conditions. These cases allow developers to confirm how their payment flow responds to different verification outcomes, partial approvals, and fraud scoring logic.

These test cards are for sandbox testing only and should never be used for real payments. Each table below corresponds to a major card brand and lists the expected AVS, CVV, and EMS behaviors.

Discover Card Testing Scenarios

Mastercard Card Test Scenarios

Enhanced Merchant Screening (EMS) simulates risk evaluation and fraud scoring, enabling merchants to verify how their system reacts to various approval thresholds and reason codes.

AMEX Card Testing Scenarios

VISA Card Testing Scenarios

---

Troubleshooting

• Approved despite Auto‑Decline setting: Check if the AVS result is on the exempt list above.
• Payment rejected for missing AVS fields: Verify Merchant's 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

Pending items

• Need to confirm if Test Data specific to AVS should be added here, or moved under "Test Data" category