DEV Community

Cover image for Building a Visa CE3.0 Eligibility Matcher: Data Model, Rules, Edge Cases
Jarrod Wright for Chargebacks911

Posted on AI-assisted

Building a Visa CE3.0 Eligibility Matcher: Data Model, Rules, Edge Cases

Visa's Compelling Evidence 3.0 (CE3.0) rule can stop a card-absent fraud dispute (reason code 10.4) when the merchant shows that the same card made earlier, undisputed purchases with matching identifiers. Most coverage frames this as a disputes-team topic. In practice, whether you qualify is decided months earlier by your checkout, logging, and data-retention code.

If your system didn't capture a stable device ID or a normalized shipping address at purchase time, you can't produce it later. This article treats CE3.0 as an engineering problem. It covers what to store, how to normalize it, how to write the matcher, and where implementations commonly break.

For the business context, the dispute lifecycle, and recent rule changes, see this overview of Visa Compelling Evidence 3.0.

The rule, restated as a spec

Here are the commonly described qualification criteria, written the way you'd hand them to an engineer:

  • Scope: the disputed transaction is a Visa card-absent dispute under reason code 10.4.
  • Cardinality: you need at least two prior transactions on the same underlying card (PAN) at your business.
  • Clean history: neither prior transaction may have been reported as fraud.
  • Age window: each prior transaction must be more than 120 days and no more than 365 days before the dispute.
  • Matching: each prior transaction must share at least two data elements with the disputed transaction. The eligible elements are:
    • customer account or login ID
    • full delivery address
    • device ID or fingerprint
    • IP address
  • Anchor constraint: at least one of the matching elements must be the device ID or the IP address.
  • Descriptions: you need an item or service description for all three transactions.
  • Excluded: email address and phone number do not count, even though older evidence rules accepted them.

There are also edge-case exceptions:

  • Subscriptions: the IP captured at sign-up can be reused as the matching IP for later recurring charges.
  • Tokenization: matching is done on the underlying card number, so tokenized purchases count.
  • Original credits: the 120-day minimum reportedly doesn't apply to original credit transactions.

Treat these as configuration, not constants. The numbers and exceptions have changed since launch, and the scope is expanding.

What you must capture at purchase time

The matcher is only as good as the record written at checkout. A minimal schema:

CREATE TABLE txn_evidence (
  txn_id              TEXT PRIMARY KEY,
  arn                 TEXT UNIQUE,        -- acquirer reference number
  pan_ref             TEXT NOT NULL,      -- stable card identity (see below)
  card_brand          TEXT NOT NULL,
  created_at          TIMESTAMPTZ NOT NULL,
  amount_minor        BIGINT NOT NULL,
  item_description    TEXT NOT NULL,
  account_id          TEXT,
  ship_addr_norm      TEXT,               -- normalized, not raw
  device_id           TEXT,
  ip_address          INET,
  subscription_id     TEXT,
  is_signup_txn       BOOLEAN DEFAULT FALSE,
  fraud_reported      BOOLEAN DEFAULT FALSE,
  disputed            BOOLEAN DEFAULT FALSE
);
CREATE INDEX ON txn_evidence (pan_ref, created_at);
Enter fullscreen mode Exit fullscreen mode

A few design decisions matter here.

pan_ref: the hardest column

You should not store raw PANs, and your processor may give you a different token per payment method, wallet, or network token. If you key on whatever token you received, two purchases on the same physical card can look unrelated.

Pick an identifier that is stable across tokenization. Options include a processor-provided card fingerprint or a payment account reference, if your stack exposes one. Document which one you use. If you change processors, plan a mapping migration, or your history effectively resets.

ship_addr_norm: normalize once, at write time

"123 Main St Apt 4" and "123 MAIN STREET #4" are the same address to a human and different strings to an equality check. Normalize when you write the record, using a deterministic function you version. Re-normalizing old rows with a new algorithm silently changes match results.

device_id: stability over cleverness

A fingerprint that changes after every browser update produces zero matches. When you evaluate a device ID approach, measure how often the same returning customer gets the same ID across 4 to 12 months, not over a single session. Native app installs with a persisted ID usually do better than browser-only signals.

ip_address: store what you saw

Log the client IP as seen at your edge. If you're behind a CDN or load balancer, make sure you record the forwarded client IP and not your proxy's address. This is a common and invisible bug.

The matcher

Here's a straightforward Python implementation. It's deliberately explicit so each rule can be tested on its own.

from dataclasses import dataclass
from datetime import datetime, timedelta

MIN_AGE = timedelta(days=120)
MAX_AGE = timedelta(days=365)
ANCHORS = {'device_id', 'ip_address'}
ELEMENTS = ['account_id', 'ship_addr_norm', 'device_id', 'ip_address']

@dataclass
class Txn:
    txn_id: str
    pan_ref: str
    created_at: datetime
    item_description: str | None
    account_id: str | None
    ship_addr_norm: str | None
    device_id: str | None
    ip_address: str | None
    subscription_id: str | None = None
    signup_ip: str | None = None   # populated for recurring charges
    fraud_reported: bool = False

def effective_ip(t: Txn) -> str | None:
    # Subscription accommodation: reuse sign-up IP for recurring charges
    return t.ip_address or t.signup_ip

def matched_elements(disputed: Txn, prior: Txn) -> set[str]:
    hits = set()
    for el in ELEMENTS:
        if el == 'ip_address':
            a, b = effective_ip(disputed), effective_ip(prior)
        else:
            a, b = getattr(disputed, el), getattr(prior, el)
        if a and b and a == b:   # nulls never match
            hits.add(el)
    return hits

def qualifies(disputed: Txn, prior: Txn, dispute_date: datetime) -> tuple[bool, str]:
    if prior.pan_ref != disputed.pan_ref:
        return False, 'different card'
    if prior.fraud_reported:
        return False, 'fraud reported'
    age = dispute_date - prior.created_at
    if not (MIN_AGE < age <= MAX_AGE):
        return False, f'outside window ({age.days}d)'
    if not prior.item_description:
        return False, 'missing description'
    hits = matched_elements(disputed, prior)
    if len(hits) < 2:
        return False, f'only {len(hits)} match(es)'
    if not hits & ANCHORS:
        return False, 'no device/IP anchor'
    return True, ','.join(sorted(hits))

def find_ce3_candidates(disputed, history, dispute_date):
    if not disputed.item_description:
        return None, ['disputed txn missing description']
    results = [(p, *qualifies(disputed, p, dispute_date)) for p in history]
    passing = sorted([r for r in results if r[1]],
                     key=lambda r: r[0].created_at, reverse=True)
    log = [f'{p.txn_id}: {reason}' for p, ok, reason in results]
    return (passing[:2] if len(passing) >= 2 else None), log
Enter fullscreen mode Exit fullscreen mode

The function returns the reason for every rejected candidate. That audit log is the most useful thing you'll build. When a dispute doesn't qualify, "no device/IP anchor on 6 of 6 candidates" tells you exactly which capture pipeline to fix.

Worked example

Say a dispute arrives on 2025-11-01 for a purchase made 2025-10-20. The card has this history:

Txn Date Age at dispute Account Address Device IP Result
A 2025-08-15 78d match match match match Fail: too recent
B 2025-06-01 153d match match — differs Fail: no anchor
C 2025-04-10 205d match — match — Pass (account + device)
D 2025-01-05 300d — match — match Pass (address + IP)
E 2024-09-01 426d match match match match Fail: too old

C and D qualify. Notice two things:

  • The "best" match, A, is useless because it's too recent.
  • B fails because device capture was missing that month. That is an engineering defect, not a customer behavior problem.

Decision table for common scenarios

Scenario Likely outcome Engineering lever
First-time buyer Cannot qualify None; no history exists
Monthly subscription, same card Usually qualifies Persist sign-up IP and link it to recurring charges
Annual billing Usually can't get two priors in the window None within this rule
Guest checkout, no account Needs address plus device/IP Prioritize stable device ID
Customer switched to a mobile wallet Depends on card identity Key on a tokenization-stable pan_ref
Behind a CDN, logging proxy IPs IP never matches Fix forwarded-IP extraction

Common mistakes and how to catch them

Treating nulls as equal. None == None is True in Python. Without an explicit null guard, two transactions with no device ID "match." A unit test with all-null elements should return zero hits.

Off-by-one on the window. The rule says more than 120 days and no more than 365. Write boundary tests at 120, 121, 365, and 366 days. Be explicit about time zones and whether you count from the dispute date or another reference date. Confirm the reference date with your acquirer.

Counting email or phone. Legacy evidence code often includes them. Remove them from the CE3.0 path, but keep them for older-style evidence packages that issuers still evaluate in representment.

Using fraud-flagged history. Join against your dispute and fraud-report tables at query time rather than relying on a cached flag. Fraud reports can arrive weeks after a transaction.

Retention too short. If logs containing IP and device data expire at 90 days, you cannot ever qualify. Align retention with the 365-day lookback, and check that against your privacy obligations and data-minimization policy.

Inconsistent item descriptions. "SKU-8812" is not a description. Store a human-readable line item at purchase time.

Monitoring

Track the qualification rate across all 10.4 disputes and break down rejection reasons. A rising "no anchor" share usually means a client release broke device capture. A sudden drop in IP matches often traces back to an infrastructure change at the edge. These metrics turn CE3.0 from a disputes-team afterthought into a data-quality signal for your whole payments stack.

Top comments (0)