AVS Filters#

Configure Address Verification Service (AVS) filters to prevent fraudulent transactions.

Overview#

AVS (Address Verification Service) compares the billing address provided by the customer with the address on file at the card issuer. Use AVS filters to:

• 🛡️ Prevent fraud - Decline approved sales whose AVS result you do not accept
• ✅ Accept/decline based on AVS response categories
• ⚙️ Two layers - A merchant-wide filter (Fraud Prevention settings) and per-gateway rules (Gateways tab)

AVS filtering is applied after the gateway approves a card sale. If a filter rejects the AVS result, the transaction is recorded as declined with response code 220 and response text Do Not Honor – Address Verification Failed. Filters only apply to card payments (not ACH, cash, etc.).

curl https://uat.auxcore.net/api/v1/merchants/3f2a9c1e-7b4d-4e8a-9f10-2c5d6e7f8a90/fraud-settings \
  -H "Authorization: Bearer YOUR_TOKEN"

{
  "success": true,
  "data": {
    "enabled": true,
    "avsRejectCodes": ["noMatch"],
    "cvvRejectCodes": ["noMatch"],
    "rejectOnUnavailable": false,
    "rejectOnError": false,
    "rejectOnNoMatch": true,
    "rejectOnPartialMatch": false
  }
}

curl -X PUT https://uat.auxcore.net/api/v1/merchants/3f2a9c1e-7b4d-4e8a-9f10-2c5d6e7f8a90/fraud-settings \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "enabled": true,
    "avsRejectCodes": ["noMatch", "partialMatch"],
    "cvvRejectCodes": ["noMatch"]
  }'

{
  "success": true,
  "data": {
    "enabled": true,
    "avsRejectCodes": ["noMatch", "partialMatch"],
    "cvvRejectCodes": ["noMatch"],
    "rejectOnUnavailable": false,
    "rejectOnError": false,
    "rejectOnNoMatch": true,
    "rejectOnPartialMatch": false
  },
  "message": "Fraud prevention settings updated successfully"
}

AVS Reject Categories#

avsRejectCodes takes category keys, not raw AVS letters. Each key maps to these gateway AVS codes:

The filter is stored as an allow-list of the eleven letters in the table below minus the ones you reject. Y (full match) is never declined. If avsRejectCodes is empty (or enabled is false), AVS never declines. Once at least one key is selected, any code outside those eleven letters (for example X, D or M, which some processors return) is also declined. The merchant-level filter only runs when the gateway returned an AVS code.

AVS Response Codes#

{
  "requireAVS": true,
  "avsRules": {
    "rejectOnMismatch": true,
    "allowedResponses": ["Y", "A", "Z"]
  }
}

Preset Configurations#

Strict (High Security)#

Decline anything that is not a full match:

{
  "enabled": true,
  "avsRejectCodes": ["noMatch", "partialMatch", "unavailable", "notSupported"],
  "cvvRejectCodes": ["noMatch"]
}

Balanced (Recommended)#

Decline only complete mismatches:

{
  "enabled": true,
  "avsRejectCodes": ["noMatch"],
  "cvvRejectCodes": ["noMatch"]
}

Off#

Never decline on AVS:

{
  "enabled": true,
  "avsRejectCodes": [],
  "cvvRejectCodes": ["noMatch"]
}

Transaction Response#

The public transaction response returns the gateway's AVS code in data.AvsResult:

{
  "success": true,
  "status": "success",
  "status_code": 200,
  "message": "Transaction approved",
  "data": {
    "TransactionId": "8d1c2b3a-4e5f-4a6b-9c7d-0e1f2a3b4c5d",
    "Status": "1",
    "Amount": 100.00,
    "ResponseCode": "100",
    "AvsResult": "Y",
    "CvvResult": "M"
  }
}

Declined by AVS#

Returned with HTTP 402:

{
  "success": false,
  "status": "declined",
  "status_code": 402,
  "message": "Do Not Honor – Address Verification Failed",
  "data": {
    "TransactionId": "5a6b7c8d-9e0f-4a1b-8c2d-3e4f5a6b7c8d",
    "Status": "9",
    "Amount": 100.00,
    "ResponseCode": "220",
    "ResponseMessage": "Do Not Honor – Address Verification Failed",
    "AvsResult": "N",
    "CvvResult": "M"
  }
}

When a per-gateway requireAVS rule declines because no AVS result came back, the response text is Do Not Honor – Address Verification Required.

Note: AVS is evaluated after the gateway authorizes the sale. A filter decline marks the transaction declined in AuxCORE; it does not automatically void the authorization at the processor.

Testing AVS Filters#

AVS results in Sandbox come from the processor's own test environment, so the address/ZIP values that trigger each code depend on the gateway configured for the merchant (see your processor's test documentation). Verify your filter by checking data.AvsResult and data.ResponseCode (220) on the transaction response.

curl -X POST https://uat.auxcore.net/api/v1/public/transaction \
  -H "x-api-key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "Amount": 10.00,
    "SuggestedMode": "Card",
    "pciToken": "pci_tok_8f2c1a9b7e4d",
    "BillingAddress": "123 Main Street",
    "BillingPostalCode": "10001"
  }'

Raw CardNumber / CVV is rejected on Sandbox and Production (400 PCI_SCOPE_VIOLATION); collect the card with the PCI SDK and send its pciToken.

Best Practices#

✅ DO:#

• Start with balanced settings - Too strict reduces conversion
• Leave unavailable / notSupported unselected for international traffic - many non-US issuers don't support AVS
• Test in Sandbox first - Ensure settings work with your processor
• Monitor decline rates - Adjust if too many legitimate declines
• Combine with CVV - Use both for stronger fraud prevention

❌ DON'T:#

• Don't decline everything - Legitimate transactions may have minor mismatches
• Don't rely on AVS alone - Use as part of comprehensive fraud strategy
• Don't change frequently - Causes inconsistent customer experience

Common Scenarios#

Scenario 1: Address Typo#

Customer enters "123 Main Street" but card on file shows "124 Main St"

AVS Response: Z (ZIP match only)
Recommendation: Accept — leave partialMatch unselected

Scenario 2: Recently Moved#

Customer moved but hasn't updated address with bank

AVS Response: N (no match)
Recommendation: Decline (noMatch) or contact customer

Scenario 3: International Card#

Customer using non-US card

AVS Response: G (non-US issuer)
Recommendation: Leave unavailable unselected, use other fraud signals

Reviewing AVS Results#

There is no dedicated AVS analytics endpoint. Filter the transaction list by AVS code instead:

curl "https://uat.auxcore.net/api/v1/transactions?avsFilter=N&dateFrom=2026-01-01&dateTo=2026-01-31" \
  -H "Authorization: Bearer YOUR_TOKEN"

avsFilter (and cvvFilter) take a comma-separated list of raw response codes.

Next Steps#

• Configure CVV filters →
• Risk management →
• View fraud analytics →

Need help? Contact support@auxcore.net