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 - Block transactions with mismatched addresses
✅ Accept/decline based on AVS response codes
📊 Custom rules - Define your own AVS acceptance criteria
🌍 International support - Handle international addresses
📈 Risk scoring - Weight AVS in fraud decisions

Get AVS Settings

Endpoint

GET /api/v1/merchants/:merchantId/fraud-settings

curl https://dev.auxcore.net/api/v1/merchants/merchant_123/fraud-settings \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "X-Tenant-ID: your-tenant-id"

Response:

{
  "success": true,
  "data": {
    "avsFilterConfig": {
      "enabled": true,
      "action": "decline",
      "acceptedCodes": ["Y", "A", "Z", "M"],
      "declinedCodes": ["N"],
      "bypassCodes": ["U", "R", "S"],
      "internationalBypass": true
    },
    "cvvFilterConfig": {...}
  }
}

Update AVS Settings

Endpoint

PUT /api/v1/merchants/:merchantId/fraud-settings

curl -X PUT https://dev.auxcore.net/api/v1/merchants/merchant_123/fraud-settings \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "X-Tenant-ID: your-tenant-id" \
  -H "Content-Type: application/json" \
  -d '{
    "avsFilterConfig": {
      "enabled": true,
      "action": "decline",
      "acceptedCodes": ["Y", "M"],
      "declinedCodes": ["N", "A", "Z"],
      "internationalBypass": false
    }
  }'

AVS Response Codes

Common Response Codes

Code	Address	ZIP	Description	Recommendation
Y	✅ Match	✅ Match	Full match	✅ Accept
A	✅ Match	❌ No match	Address match only	⚠️ Review
Z	❌ No match	✅ Match	ZIP match only	⚠️ Review
N	❌ No match	❌ No match	No match	❌ Decline
M	✅ Match	✅ Match	Full match (international)	✅ Accept
U	❓ Unknown	❓ Unknown	Information unavailable	⚠️ Bypass
R	N/A	N/A	Retry / System unavailable	⚠️ Bypass
S	N/A	N/A	Service not supported	⚠️ Bypass
G	N/A	N/A	Non-US card issuer	⚠️ Bypass

Configuration Options

Enable/Disable AVS

{
  "avsFilterConfig": {
    "enabled": true
  }
}

When disabled, AVS checks still run but won't affect transaction approval.

Filter Actions

Action	Description
`decline`	Automatically decline transactions
`flag`	Flag for manual review
`log`	Log only (no action)

{
  "action": "decline"
}

Accepted Codes

Specify which AVS codes to accept:

{
  "acceptedCodes": ["Y", "M", "A", "Z"]
}

Declined Codes

Specify which AVS codes to decline:

{
  "declinedCodes": ["N"]
}

Bypass Codes

Codes that bypass the filter (neither accept nor decline):

{
  "bypassCodes": ["U", "R", "S", "G"]
}

International Bypass

Automatically bypass AVS for international cards:

{
  "internationalBypass": true
}

⚠️ Note: Many international cards don't support AVS.

Preset Configurations

Strict (High Security)

Accept only perfect matches:

{
  "avsFilterConfig": {
    "enabled": true,
    "action": "decline",
    "acceptedCodes": ["Y", "M"],
    "declinedCodes": ["N", "A", "Z"],
    "bypassCodes": ["U", "R", "S"],
    "internationalBypass": false
  }
}

Balanced (Recommended)

Accept full and partial matches:

{
  "avsFilterConfig": {
    "enabled": true,
    "action": "decline",
    "acceptedCodes": ["Y", "M", "A", "Z"],
    "declinedCodes": ["N"],
    "bypassCodes": ["U", "R", "S", "G"],
    "internationalBypass": true
  }
}

Lenient (Low Security)

Flag suspicious transactions for review:

{
  "avsFilterConfig": {
    "enabled": true,
    "action": "flag",
    "acceptedCodes": ["Y", "M", "A", "Z"],
    "declinedCodes": [],
    "bypassCodes": ["N", "U", "R", "S", "G"],
    "internationalBypass": true
  }
}

Transaction Response

When AVS filtering is enabled, transaction responses include AVS data:

{
  "success": true,
  "data": {
    "transactionId": "txn_abc123",
    "status": "approved",
    "avsResponse": "Y",
    "avsResponseText": "Address and ZIP match",
    "avsResult": "pass"
  }
}

Declined by AVS

{
  "success": false,
  "data": {
    "transactionId": "txn_declined_123",
    "status": "declined",
    "avsResponse": "N",
    "avsResponseText": "Address and ZIP do not match",
    "avsResult": "fail",
    "declineReason": "AVS mismatch"
  }
}

Testing AVS Filters

Test Addresses

Use these addresses in sandbox to trigger specific AVS responses:

Address	ZIP	AVS Code
123 Main St	12345	Y (full match)
456 Oak Ave	99999	A (address match)
789 Elm St	12345	Z (ZIP match)
999 Test Ln	99999	N (no match)

# Test AVS decline
curl -X POST https://dev.auxcore.net/api/v1/transactions \
  -d '{
    "amount": 100.00,
    "billing": {
      "address": "999 Test Ln",
      "zip": "99999"
    },
    ...
  }'
# Should be declined with AVS mismatch

Best Practices

✅ DO:

Start with balanced settings - Too strict reduces conversion
Bypass international cards - AVS less reliable internationally
Test in sandbox first - Ensure settings work correctly
Monitor decline rates - Adjust if too many legitimate declines
Combine with CVV - Use both for stronger fraud prevention
Review flagged transactions - Manual review catches edge cases

❌ DON'T:

Don't decline everything - Legitimate transactions may have minor mismatches
Don't ignore system errors - Bypass U, R, S codes
Don't rely on AVS alone - Use as part of comprehensive fraud strategy
Don't forget international - Enable international bypass
Don't change frequently - Causes inconsistent customer experience

Common Scenarios

Scenario 1: Address Typo

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

AVS Response: A (address match, ZIP match)
Recommendation: Accept (minor formatting difference)

Scenario 2: Recently Moved

Customer moved but hasn't updated address with bank

AVS Response: N (no match)
Recommendation: Flag for review or contact customer

Scenario 3: International Card

Customer using non-US card

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

Scenario 4: Corporate Card

Card has corporate billing address, different from customer

AVS Response: N (no match)
Recommendation: Flag for review

Combining with Other Fraud Tools

AVS + CVV

Most effective fraud prevention:

{
  "avsFilterConfig": {
    "enabled": true,
    "acceptedCodes": ["Y", "M", "A", "Z"]
  },
  "cvvFilterConfig": {
    "enabled": true,
    "acceptedCodes": ["M"]
  }
}

AVS + Transaction Limits

Combine with amount-based rules:

{
  "avsFilterConfig": {
    "enabled": true,
    "acceptedCodes": ["Y", "M", "A", "Z"]
  },
  "maxTicketAmount": 500.00
}

For transactions > $500, require perfect AVS match.

Analytics

Track AVS performance:

Metrics to Monitor

AVS decline rate - % of transactions declined by AVS
False positive rate - Legitimate transactions declined
Chargeback prevention - Chargebacks avoided by AVS
Code distribution - Which AVS codes you receive most

Example Query

curl "https://dev.auxcore.net/api/v1/analytics/avs?startDate=2026-01-01&endDate=2026-01-31" \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "X-Tenant-ID: your-tenant-id"

Error Handling

AVS Unavailable

{
  "success": true,
  "data": {
    "transactionId": "txn_abc123",
    "status": "approved",
    "avsResponse": "U",
    "avsResponseText": "Address information unavailable",
    "avsResult": "bypass"
  }
}

Invalid Configuration

{
  "success": false,
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "Invalid AVS code in acceptedCodes: X",
    "field": "avsFilterConfig.acceptedCodes"
  }
}

Next Steps

Need help? Contact support@auxvault.com