CVV Filters

Configure Card Verification Value (CVV) filters to prevent fraudulent transactions.

Overview

CVV (Card Verification Value) is the 3-4 digit security code on the back (or front for Amex) of credit cards. CVV verification confirms the customer has physical possession of the card. Use CVV filters to:

🛡️ Prevent fraud - Block transactions with mismatched CVV
✅ Accept/decline based on CVV response codes
📊 Custom rules - Define your own CVV acceptance criteria
🔐 Require CVV - Force CVV for all transactions
📈 Risk scoring - Weight CVV in fraud decisions

Get CVV 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": {...},
    "cvvFilterConfig": {
      "enabled": true,
      "required": true,
      "action": "decline",
      "acceptedCodes": ["M"],
      "declinedCodes": ["N"],
      "bypassCodes": ["U", "P", "S"]
    }
  }
}

Update CVV 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 '{
    "cvvFilterConfig": {
      "enabled": true,
      "required": true,
      "action": "decline",
      "acceptedCodes": ["M"],
      "declinedCodes": ["N", "P"]
    }
  }'

CVV Response Codes

Common Response Codes

Code	Meaning	Description	Recommendation
M	Match	CVV matches	✅ Accept
N	No match	CVV does not match	❌ Decline
P	Not processed	CVV not processed	⚠️ Review
S	Not supported	Issuer doesn't support CVV	⚠️ Bypass
U	Unknown	Information unavailable	⚠️ Bypass

Configuration Options

Enable/Disable CVV

{
  "cvvFilterConfig": {
    "enabled": true
  }
}

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

Require CVV

Force CVV to be provided for all transactions:

{
  "required": true
}

⚠️ Highly Recommended: Always require CVV for card-not-present transactions.

Filter Actions

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

{
  "action": "decline"
}

Accepted Codes

Specify which CVV codes to accept:

{
  "acceptedCodes": ["M"]
}

Declined Codes

Specify which CVV codes to decline:

{
  "declinedCodes": ["N"]
}

Bypass Codes

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

{
  "bypassCodes": ["U", "P", "S"]
}

Preset Configurations

Strict (Recommended)

Only accept perfect matches:

{
  "cvvFilterConfig": {
    "enabled": true,
    "required": true,
    "action": "decline",
    "acceptedCodes": ["M"],
    "declinedCodes": ["N"],
    "bypassCodes": ["U", "P", "S"]
  }
}

✅ Best for: Most merchants - provides strong fraud protection

Balanced

Accept matches, review unprocessed:

{
  "cvvFilterConfig": {
    "enabled": true,
    "required": true,
    "action": "decline",
    "acceptedCodes": ["M"],
    "declinedCodes": ["N"],
    "bypassCodes": ["U", "S"]
  }
}

✅ Best for: Merchants with manual review process

Lenient (Not Recommended)

Flag suspicious transactions only:

{
  "cvvFilterConfig": {
    "enabled": true,
    "required": false,
    "action": "flag",
    "acceptedCodes": ["M"],
    "declinedCodes": [],
    "bypassCodes": ["N", "U", "P", "S"]
  }
}

⚠️ Warning: Significantly increases fraud risk

Transaction Response

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

{
  "success": true,
  "data": {
    "transactionId": "txn_abc123",
    "status": "approved",
    "cvvResponse": "M",
    "cvvResponseText": "CVV matches",
    "cvvResult": "pass"
  }
}

Declined by CVV

{
  "success": false,
  "data": {
    "transactionId": "txn_declined_123",
    "status": "declined",
    "cvvResponse": "N",
    "cvvResponseText": "CVV does not match",
    "cvvResult": "fail",
    "declineReason": "CVV mismatch"
  }
}

Testing CVV Filters

Test CVV Codes

Use these CVV codes in sandbox to trigger specific responses:

CVV	Response Code	Result
123	M	Match - approved
999	N	No match - declined
000	U	Unknown - bypass

# Test CVV match
curl -X POST https://dev.auxcore.net/api/v1/transactions \
  -d '{
    "amount": 100.00,
    "card": {
      "number": "4111111111111111",
      "cvv": "123"
    },
    ...
  }'
# Should be approved

# Test CVV mismatch
curl -X POST https://dev.auxcore.net/api/v1/transactions \
  -d '{
    "amount": 100.00,
    "card": {
      "number": "4111111111111111",
      "cvv": "999"
    },
    ...
  }'
# Should be declined

Best Practices

✅ DO:

Always require CVV - For card-not-present transactions
Only accept matches - Decline mismatches
Bypass system errors - U, S codes are not customer's fault
Test in sandbox - Verify settings work correctly
Combine with AVS - Strongest fraud prevention
Monitor decline rates - Adjust if needed
Educate customers - Where to find CVV

❌ DON'T:

Don't make CVV optional - Massive fraud risk
Don't accept mismatches - Clear fraud indicator
Don't decline system errors - Use bypass instead
Don't rely on CVV alone - Use with AVS
Don't store CVV - PCI violation
Don't skip testing - Could block legitimate customers

Common Scenarios

Scenario 1: Wrong CVV Entered

Customer makes typo entering CVV

CVV Response: N (no match)
Recommendation: Decline, ask customer to re-enter

Scenario 2: International Card

Card from country that doesn't support CVV

CVV Response: S (not supported)
Recommendation: Bypass CVV, use other fraud signals

Scenario 3: System Issue

Processor unable to verify CVV

CVV Response: U (unknown)
Recommendation: Bypass CVV, not customer's fault

Scenario 4: Fraudulent Transaction

Fraudster has card number but not CVV

CVV Response: N (no match)
Recommendation: Decline - likely fraud

Combining with Other Fraud Tools

CVV + AVS (Recommended)

Most effective fraud prevention:

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

Result: Transaction must pass BOTH CVV and AVS checks

CVV + Transaction Limits

Combine with amount-based rules:

{
  "cvvFilterConfig": {
    "enabled": true,
    "required": true
  },
  "transactionLimits": {
    "maxAmount": 1000.00,
    "dailyLimit": 5000.00
  }
}

Result: Strong fraud prevention for high-value transactions

Why CVV Matters

Fraud Prevention

CVV proves the customer has physical possession of the card:

Stolen card numbers - Fraudsters often don't have CVV
Data breaches - CVV isn't stored in databases
Card-not-present fraud - Primary defense mechanism

Chargeback Protection

CVV verification helps dispute chargebacks:

Proves you took reasonable precautions
Shifts liability in some cases
Reduces chargeback rates by ~40%

Compliance

Some industries require CVV:

High-risk merchants
Specific card brand requirements
Regulatory compliance

PCI Compliance

⚠️ CRITICAL: You MUST NOT store CVV after authorization.

Prohibited:

Storing CVV in databases
Logging CVV in log files
Including CVV in backup files
Transmitting CVV via email

Allowed:

Collecting CVV for transaction
Sending CVV to payment processor
Displaying masked CVV (XXX)

Storing CVV violates PCI DSS and results in:

Fines up to $500,000
Loss of processing privileges
Liability for fraud

Analytics

Track CVV performance:

Metrics to Monitor

CVV match rate - % of transactions with matching CVV
CVV decline rate - % declined due to CVV
False positive rate - Legitimate transactions declined
Fraud prevention rate - Fraud stopped by CVV

Example Query

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

Response:

{
  "success": true,
  "data": {
    "totalTransactions": 1000,
    "cvvMatches": 920,
    "cvvMismatches": 60,
    "cvvBypass": 20,
    "matchRate": 0.92,
    "fraudPrevented": 58
  }
}

Error Handling

CVV Required but Not Provided

{
  "success": false,
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "CVV is required",
    "field": "card.cvv"
  }
}

Invalid CVV Format

{
  "success": false,
  "error": {
    "code": "INVALID_CVV",
    "message": "CVV must be 3-4 digits",
    "field": "card.cvv"
  }
}

Next Steps

Need help? Contact support@auxvault.com