DEV Community: Jarrod Wright

Detecting Brushing Orders With Convergence Scoring, Not Single Rules

Jarrod Wright — Thu, 05 Nov 2026 21:20:12 +0000

Brushing is review manipulation that runs on real transactions. Someone places a cheap order to a real address, often with a name that isn't theirs, so a package ships and a tracking number exists. That tracking number turns a fake order into a "verified purchase."

If you run a storefront, your checkout can be the place where those orders get created. They are low value, they fulfill cleanly, and nobody contacts support. Then fraud-coded disputes arrive weeks later, because some of the cards were stolen.

This article covers the engineering side: how to turn weak, ambiguous signals into a scorer that catches brushing patterns without blocking gift buyers and new customers. For the merchant and policy side, including vendor liability and what to do once you know your position, see Brushing A Junk Package Is a Merchant Problem, Not Just a Consumer Curiosity.

Why single-signal rules fail here

The usual brushing indicators are:

One shipping address shared by unrelated customer names
An account created minutes before its first and only order
Order value sitting at the lowest amount that qualifies for something, such as free shipping or a promo
An address plus payment-instrument pair that has appeared before
No post-purchase contact: no support tickets, no tracking page views, no return requests

Each of these fires on legitimate traffic all the time. Gift orders ship to someone else's address. Roommates and families share addresses. Every new customer has a new account. A rule like if account_age < 1h: decline will cost more in false declines than brushing ever would.

The useful property is convergence. One order that hits four or five of these signals at once looks much more like an order placed to get a tracking number. Your system should score each signal, combine the scores, and scale the response to what is at stake.

Data flow

Here is the pipeline at a high level:

checkout event
   │
   ▼
normalize (address, name, payment fingerprint, email)
   │
   ▼
entity graph lookup ── address ↔ names ↔ payment fingerprints ↔ accounts
   │
   ▼
real-time signals (computable at checkout)
   │
   ▼
score + tier ──► allow / allow+watch / hold for review
   │
   ▼
retrospective sweep (T+N days): post-purchase signals, cluster detection
   │
   ▼
re-score, flag clusters, feed evidence file

The split between real-time and retrospective matters. Some of the strongest signals do not exist yet at checkout time.

Step 1: Normalize before you compare

If you skip this step, "shared address" detection is nearly useless. 123 Main St Apt 4, 123 MAIN STREET #4, and 123 Main St., Unit 4 need to collapse to one key.

In practice:

Use an address validation or standardization service where you can, such as the USPS standardization format for US addresses. Otherwise, at minimum, uppercase the string, expand or contract street suffixes consistently, and strip punctuation.
Keep the unit as its own field. Two names at 123 Main St in different units are not a signal. Two names at the same unit might be.
Hash the normalized address into an address_key.
For payment, use the fingerprint your processor gives you. Many gateways expose a stable card fingerprint so you never touch the PAN. Never build this from raw card data yourself.
Normalize names loosely: lowercase, strip honorifics, and treat J Smith and John Smith as possibly the same person. You are trying to detect unrelated names, so lean toward false merges rather than false splits.

Step 2: Maintain an entity graph

You don't need a graph database to start. A few relational tables with rolling windows are enough:

-- edges observed per order
CREATE TABLE order_entities (
  order_id        TEXT PRIMARY KEY,
  account_id      TEXT,
  address_key     TEXT,
  name_key        TEXT,
  payment_fp      TEXT,
  created_at      TIMESTAMPTZ,
  order_total     NUMERIC
);

CREATE INDEX ON order_entities (address_key, created_at);
CREATE INDEX ON order_entities (payment_fp, created_at);

The query that does most of the work is "distinct names at this address in the last N days":

SELECT COUNT(DISTINCT name_key)
FROM order_entities
WHERE address_key = $1
  AND created_at > now() - interval '30 days';

Run the same query for payment fingerprints per address, and addresses per fingerprint. A single card shipping to many addresses under many names is a different pattern from a household, and it is worth a separate signal.

Step 3: Score the signals

Here is a minimal scorer in Python. The weights are placeholders. You will tune them against your own labeled disputes.

from dataclasses import dataclass

@dataclass
class Signals:
    distinct_names_at_address: int   # 30-day window
    account_age_minutes: float
    order_total: float
    qualifying_threshold: float      # e.g. free-shipping minimum
    addr_payment_pair_seen: int      # prior orders with same pair
    names_on_payment_fp: int         # 30-day window

def score(s: Signals) -> tuple[float, list[str]]:
    reasons = []
    total = 0.0

    if s.distinct_names_at_address >= 3:
        total += 2.0; reasons.append("address_shared_by_unrelated_names")
    elif s.distinct_names_at_address == 2:
        total += 0.5  # households and gifts are common

    if s.account_age_minutes < 30:
        total += 1.0; reasons.append("account_created_just_before_order")

    # within 5% above the qualifying threshold
    if s.qualifying_threshold and \
       s.qualifying_threshold <= s.order_total <= s.qualifying_threshold * 1.05:
        total += 1.0; reasons.append("lowest_qualifying_value")

    if s.addr_payment_pair_seen >= 2:
        total += 1.5; reasons.append("address_payment_pair_repeated")

    if s.names_on_payment_fp >= 3:
        total += 2.0; reasons.append("one_card_many_names")

    return total, reasons

Returning reasons is not optional. Your reviewers need to see why an order was held, and you will need the same data later if you ever have to explain a pattern to a processor or platform.

Step 4: Tier the response by exposure

Score alone should not decide the outcome. Combine it with what you stand to lose.

Score	Order value	Signals converging	Action
< 2	any	0–1	Allow
2–3.5	low	2	Allow, add to watchlist cluster
2–3.5	high	2	Step-up verification (e.g. 3DS) or manual review
≥ 4	low	3+	Hold for review before fulfillment
≥ 4	high	3+	Hold; review the whole cluster, not just this order

The counterintuitive row is the low-value, high-score order. In most fraud models, cheap orders get waved through. Brushing orders are cheap on purpose, so low value is one of the signals. When it converges with the others, the low price stops being a reason to relax.

Step 5: Run a retrospective sweep

"No post-purchase contact" is one of the most telling brushing signals, and you cannot compute it at checkout. It only becomes meaningful after delivery. Treat it as a batch job:

def retrospective_flags(order, days_since_delivery):
    if days_since_delivery < 14:
        return []
    flags = []
    if (order.tracking_page_views == 0 and
        order.support_tickets == 0 and
        order.marketing_email_opens == 0):
        flags.append("zero_post_purchase_engagement")
    return flags

Then re-score, and more importantly, cluster. Group flagged orders by shared address_key or payment_fp. One silent order is nothing. Twelve silent orders that share two addresses and three cards are a pattern. That lets you proactively review, refund, or report before the disputes show up.

If you sell on a marketplace and can see review data, add one more retrospective check: verified reviews posted before the carrier's earliest plausible delivery date for that order. That gap shouldn't exist with legitimate buyers.

Common mistakes and how to catch them

Comparing raw address strings. Symptom: shared-address counts look suspiciously low. Test by seeding fixtures with known variants of one address and asserting they produce one address_key.

Dropping the unit number. Symptom: every apartment building and office tower lights up. Check your top 20 addresses by distinct-name count. If they are all large residential buildings, your normalization collapsed units.

Ignoring freight forwarders and reshippers. Package-forwarding warehouses legitimately receive orders for thousands of unrelated names. Keep an allowlist of known forwarder addresses and score them separately, or you will hold every international customer.

Label leakage in model training. If you train a model on features that include post-delivery engagement, then deploy it at checkout, it will look excellent offline and do poorly in production. Keep real-time and retrospective feature sets separate, and evaluate each at the point in time it would actually run.

Hardcoding the qualifying threshold. The "lowest qualifying value" moves whenever marketing changes the free-shipping minimum or launches a promo. Read thresholds from the same config the checkout uses, and version them with timestamps so historical scores stay explainable.

Scoring orders, never clusters. Brushing is a volume activity. A per-order view misses the operation. Make cluster review a first-class workflow for analysts.

Not logging the decision. If an order is allowed, held, or refunded, store the score, reasons, threshold versions, and timestamp. If disputes arrive, a dated record showing you detected and acted on a pattern is far more useful than a reconstruction made after the fact.

Testing the scorer

Build synthetic fixtures for at least these cases and assert the tier:

First-time customer, own address, normal basket → Allow
New customer sending a gift to a different address → Allow or watch
Household with two names, one card → Allow
Five names, one unit, two cards, all orders at threshold → Hold
Forwarder address with 200 names → Allow (allowlist path)

Then backtest against historical fraud-coded disputes. Look for precision at the hold tier: of the orders you would have held, how many later disputed or clustered? Optimize that before you chase recall. Every false hold costs a real customer.

Wrapping up

Brushing detection isn't a single clever rule. It's normalization, an entity graph with rolling windows, a scorer that explains itself, response tiers tied to exposure, and a delayed sweep that picks up the signals checkout can't see. The goal is to flag the order that matches everything at once, and let the gift buyer who matches one thing through.

This article was drafted with AI assistance and reviewed by our team.

Build a Chargeback Diagnostic From Reason Codes Before Buying Tooling

Jarrod Wright — Thu, 05 Nov 2026 21:12:43 +0000

Most teams pick dispute tooling based on how loud the problem feels. Finance sees lost revenue, the acquirer sends a warning about your chargeback ratio, and someone gets told to "buy chargeback software."

That label covers three different jobs:

Prevention stops bad transactions before they happen, for example fraud screening and authentication.
Deflection resolves a cardholder inquiry before it becomes a chargeback, for example issuer alerts and data-sharing tools.
Recovery fights filed chargebacks through representment.

Each job fixes a different failure. The fastest way to find out which one you need is a diagnostic built on your own dispute data. This article shows how to build one: normalize dispute records, map network reason codes to categories, correct for mislabeled fraud, and calculate the numbers that should drive the decision. For a vendor-level comparison of how tools split across these jobs, see this comparison of chargeback management software.

What each job actually moves

Before writing any code, be clear about what you are measuring. The three jobs affect two separate outcomes:

Job	Protects revenue?	Protects chargeback ratio?	Works on third-party fraud?	Works on first-party misuse?
Prevention (screening, auth)	Yes	Yes	Yes	Weakly
Deflection (alerts, inquiry data)	Partially (often refunds)	Mostly	Yes	Yes
Recovery (representment)	Yes, when won	Generally no	Sometimes	Yes

The column that surprises people is the ratio column. Under most network calculations, a chargeback you win still counts toward your ratio. If you are near a monitoring-program threshold, recovery alone will not bring you back under it.

Your diagnostic therefore has to answer two questions:

Which dispute types dominate?
Which outcome is the business problem: revenue, ratio, or both?

Step 1: Normalize the dispute records

Dispute data usually arrives from several places: acquirer portals, processor APIs, webhook payloads, and monthly CSV exports. Each source uses its own field names. Start by mapping everything into one schema.

from dataclasses import dataclass
from datetime import date
from typing import Optional

@dataclass
class Dispute:
    dispute_id: str
    network: str            # "visa" | "mastercard" | "amex" | "discover"
    reason_code: str        # raw network code, e.g. "10.4", "4853"
    amount_cents: int
    txn_id: str
    customer_id: Optional[str]
    device_id: Optional[str]
    filed_on: date
    stage: str              # "inquiry" | "chargeback" | "pre_arb" | "arb"
    represented: bool
    won: Optional[bool]     # None if still open

Two fields people tend to skip:

stage. Without it, you cannot tell deflected inquiries from real chargebacks, and you will double-count.
represented. Without it, you cannot calculate coverage rate. As shown later, coverage rate matters more than win rate.

Keep customer_id and device_id too. You will need them to join disputes back to order history in Step 3.

Step 2: Map reason codes to categories

Visa groups its dispute reasons into four families: fraud (10.x), authorization (11.x), processing errors (12.x), and consumer disputes (13.x). Mastercard uses four-digit codes that map into similar groups. Build one lookup table and keep it in version control, because networks revise their codes.

CATEGORY_MAP = {
    "visa": {
        "10": "fraud",
        "11": "authorization",
        "12": "processing_error",
        "13": "consumer_dispute",
    },
    "mastercard": {
        "4837": "fraud",              # No cardholder authorization
        "4863": "fraud",              # Cardholder does not recognize
        "4808": "authorization",
        "4834": "processing_error",   # Point-of-interaction error
        "4853": "consumer_dispute",   # Cardholder dispute
        "4855": "consumer_dispute",   # Goods/services not provided
    },
}

def categorize(d: Dispute) -> str:
    table = CATEGORY_MAP.get(d.network, {})
    if d.network == "visa":
        return table.get(d.reason_code.split(".")[0], "unmapped")
    return table.get(d.reason_code, "unmapped")

Treat unmapped as a real bucket and alert on it. If it grows past a few percent, either your mapping is stale or a new data source is sending codes in an unexpected format, such as "10.4 " with a trailing space or "104" without the dot.

Amex and Discover use their own code sets. Map them explicitly rather than guessing. Results on those networks also behave differently: each acts as both issuer and network, so representment outcomes usually need separate expectations.

Step 3: Correct the fraud bucket

This is where most diagnostics go wrong. A fraud reason code tells you what the cardholder claimed. It does not tell you what actually happened.

A customer who recognizes a purchase but wants their money back can still file under "no authorization." That transaction passed every fraud check because the card, device, and person were all legitimate. If you count it as third-party fraud, you will overinvest in screening, which cannot stop it.

To correct for this, join fraud-coded disputes back to order history and look for signs of an established relationship with the customer:

def likely_first_party(d: Dispute, history) -> bool:
    """history: lookup over prior settled, undisputed orders."""
    if categorize(d) != "fraud":
        return False

    prior = history.undisputed_orders(
        customer_id=d.customer_id,
        device_id=d.device_id,
        before=d.filed_on,
        min_age_days=120,
    )
    signals = 0
    if len(prior) >= 2:
        signals += 1
    if history.same_shipping_address(d.txn_id, prior):
        signals += 1
    if history.post_purchase_login(d.customer_id, d.txn_id):
        signals += 1
    if history.delivery_confirmed(d.txn_id):
        signals += 1

    return signals >= 2

The thresholds above are starting points, not rules. Tune them by hand-reviewing a sample. Pull about 50 disputes your classifier flags as first-party and 50 it leaves as true fraud, and have someone who knows your customers label them.

These same signals also matter in representment. Card networks have formalized evidence frameworks built around a history of prior undisputed transactions, so the join you build here can also feed your evidence pipeline later.

Step 4: Calculate the decision metrics

Once disputes are categorized, calculate these five numbers per month:

def diagnose(disputes, txn_count):
    cbs = [d for d in disputes if d.stage == "chargeback"]
    buckets = {}
    for d in cbs:
        key = "first_party" if likely_first_party(d, history) else categorize(d)
        buckets[key] = buckets.get(key, 0) + 1

    represented = [d for d in cbs if d.represented]
    decided = [d for d in represented if d.won is not None]
    won = [d for d in decided if d.won]

    return {
        "ratio": len(cbs) / txn_count,
        "mix": {k: v / len(cbs) for k, v in buckets.items()},
        "coverage_rate": len(represented) / len(cbs),
        "win_rate": len(won) / max(len(decided), 1),
        "effective_recovery": len(won) / len(cbs),
    }

effective_recovery is coverage rate × win rate. It answers the question that matters: what share of all your chargebacks came back as money?

Check how your acquirer calculates the ratio before relying on ratio. Networks differ in whether the denominator uses the current or previous month's transactions, and whether it counts transactions or amounts.

Worked example

Suppose a subscription merchant processes 200,000 transactions in a month and receives 400 chargebacks. That is a ratio of 0.20%.

After Steps 2 and 3, the breakdown looks like this:

Bucket	Count	Share
Fraud-coded, corrected to true third-party	130	32.5%
Fraud-coded, reclassified as first-party	90	22.5%
Consumer disputes (not received, cancelled recurring, not as described)	140	35%
Processing errors	40	10%

Without Step 3, this merchant would see 55% "fraud" and buy screening. With the correction, true third-party fraud is about a third of the volume. The other two-thirds come from first-party misuse, consumer disputes, and the merchant's own processing errors. Screening cannot stop any of those.

Those three buckets point toward other fixes:

Deflection, such as alerts and inquiry data-sharing, for first-party misuse and consumer disputes.
Root-cause work on cancellation flows and billing descriptors for consumer disputes.
Internal fixes for the 40 processing errors. No vendor should be paid to clean those up.

Now the recovery side. Assume a $60 average ticket and two representment options:

Option A represents 40% of chargebacks and wins 75%. Effective recovery is 30%, or 120 wins worth $7,200.
Option B represents 85% and wins 45%. Effective recovery is about 38%, or 153 wins worth $9,180.

Option A has the better headline win rate, but Option B recovers more money. A diagnostic that tracks effective_recovery exposes this immediately. A dashboard that only shows win rate hides it.

Common mistakes and how to catch them

Counting inquiries as chargebacks. Deflected inquiries inflate your dispute count and make deflection look useless. Filter on stage and test that the counts match your acquirer's chargeback report.

Trusting the reason code as root cause. Fraud-coded disputes from customers with years of clean history are the clearest signal of mislabeling. Run Step 3 on every report, not once.

Measuring win rate on a filtered denominator. If represented is missing from your data, you cannot calculate coverage. Make it a required field in ingestion and fail the pipeline when it is null for closed cases.

Mixing pricing units. Percentage of recovery, per-alert fees, and percentage of order value cannot be compared directly. Feed your monthly bucket counts into a cost model for each pricing structure, and include any monthly minimum.

Ignoring network splits. Report the mix and recovery metrics by network. A blended win rate can hide weak Amex or Discover results behind strong Visa results.

What the output tells you

Once the diagnostic runs monthly, the purchase decision usually becomes obvious:

True third-party fraud dominates: prevention is the job.
First-party misuse and consumer disputes dominate: deflection plus root-cause fixes, backed by recovery.
The ratio is under threshold but revenue loss is high: recovery with high coverage.
The ratio is near threshold: deflection and prevention first, because recovery will not move the count.

Build the classifier first. The tooling decision comes from the numbers it produces.

Measuring False Declines: How to See the Good Orders Your Fraud Rules Kill

Jarrod Wright — Thu, 05 Nov 2026 18:22:05 +0000

Most fraud dashboards track one number very carefully: the chargeback rate. That number only describes orders you approved. The orders you declined fall out of the data. The customer leaves, nothing settles, and nobody disputes anything.

That gap matters. Small merchants already list weak sales and uneven cash flow among their biggest problems, as a breakdown of the top business obstacles facing SMBs shows. A good customer turned away by an over-cautious rule is lost revenue that never appears as a loss. It usually gets logged as cart abandonment.

This article covers the engineering side. You will see why false declines are hard to observe, how to instrument your pipeline so you can estimate them, and how to replace a fixed risk threshold with one based on cost.

Why false declines are invisible by default

Fraud screening has a selective labels problem. You only learn the true outcome (fraud or legitimate) for transactions you let through. A declined order has no settlement, no delivery, and no dispute window. So there is no ground truth.

This creates two failure modes:

Your metrics are biased. Precision and recall computed on approved traffic say nothing about the declined population.
Your models drift toward caution. If you retrain only on approved, labeled transactions, the model never sees the good customers it rejected. Patterns that resemble those customers stay "risky" indefinitely.

To measure false declines, you need data the system does not produce on its own. The steps below build that data.

Step 1: Separate who declined the order

A "decline" in your logs can come from several places, and only some of them are yours to tune.

Decline source	Who decided	Directly tunable?	What to do with it
Merchant rule or model	Your fraud engine	Yes	Primary target for false-decline measurement
Manual review reject	Your analysts	Yes	Sample and audit reviewer decisions
3DS / authentication failure	Cardholder or issuer ACS	Partially	Check friction rates by device and region
Issuer decline (e.g. generic "do not honor")	Card issuer	No	Track separately; influence via data quality and retries
Gateway or network error	Infrastructure	No (but fixable)	Treat as reliability bug, not fraud

If you lump these together, a spike in issuer declines looks like your model got stricter. Store the decline source as a first-class field rather than inferring it from response strings later.

Step 2: Log decisions so they can be audited later

Every screening decision should leave a record that lets you reconstruct it months later, when labels for approved traffic have matured. A minimal schema:

CREATE TABLE screening_decisions (
  decision_id      UUID PRIMARY KEY,
  order_id         TEXT NOT NULL,
  customer_id      TEXT,
  card_fingerprint TEXT,          -- tokenized, never raw PAN
  amount_minor     BIGINT NOT NULL,
  currency         CHAR(3) NOT NULL,
  risk_score       NUMERIC(5,4),  -- model output, 0..1
  model_version    TEXT NOT NULL,
  rules_fired      TEXT[],
  decision         TEXT NOT NULL, -- approve | decline | review
  decline_source   TEXT,          -- merchant_model | issuer | 3ds | gateway
  holdout_flag     BOOLEAN DEFAULT FALSE,
  holdout_weight   NUMERIC,
  created_at       TIMESTAMPTZ NOT NULL DEFAULT now()
);

Two fields matter most here. model_version lets you attribute changes in decline rate to a specific deploy. holdout_flag supports the experiment in Step 4.

Step 3: Collect proxy signals

Before running any experiment, you can mine existing data for strong hints that a decline was wrong. Useful proxies:

Retry success: the same customer completes a similar order shortly after, with a different card or payment method, and that order never disputes.
Later clean history: the declined customer returns weeks later, gets approved, and builds a dispute-free record.
Support contact: the customer emails or calls about a failed payment. Fraudsters rarely ask for help.
Review overturns: an analyst approves an order the model wanted to decline.

Here is a query for the retry-success proxy:

SELECT d.decision_id, d.customer_id, d.amount_minor
FROM screening_decisions d
JOIN screening_decisions r
  ON r.customer_id = d.customer_id
 AND r.decision = 'approve'
 AND r.created_at BETWEEN d.created_at AND d.created_at + INTERVAL '24 hours'
 AND r.amount_minor BETWEEN d.amount_minor * 0.8 AND d.amount_minor * 1.2
LEFT JOIN disputes x ON x.order_id = r.order_id
WHERE d.decision = 'decline'
  AND d.decline_source = 'merchant_model'
  AND x.order_id IS NULL;

Proxies are biased in a predictable direction. They catch persistent customers, not the ones who give up and leave. Treat proxy counts as a lower bound on false declines.

Step 4: Run a controlled holdout

The only unbiased way to learn the outcome of a declined order is to approve some of them. A holdout randomly lets through a small fraction of transactions the system would have declined. You then observe their real outcomes.

import random

HOLDOUT_RATE = 0.02          # approve 2% of would-be declines
MAX_HOLDOUT_AMOUNT = 15000   # minor units; cap exposure per order

def final_decision(order, model_decision, risk_score, velocity_flag):
    if model_decision != 'decline':
        return model_decision, False, None

    eligible = (
        not velocity_flag                      # skip card-testing patterns
        and order.amount_minor <= MAX_HOLDOUT_AMOUNT
        and risk_score < 0.95                  # never release near-certain fraud
    )
    if eligible and random.random() < HOLDOUT_RATE:
        return 'approve', True, 1 / HOLDOUT_RATE
    return 'decline', False, None

Each holdout transaction stands in for 1 / HOLDOUT_RATE declines that are similar to it. That is the inverse propensity weight. When dispute outcomes mature, you estimate the false declines in the eligible population like this:

def estimate_false_declines(holdout_rows):
    # holdout_rows: matured holdout transactions with a 'disputed_fraud' label
    good = sum(r.holdout_weight for r in holdout_rows if not r.disputed_fraud)
    total = sum(r.holdout_weight for r in holdout_rows)
    return good, good / total if total else None

Practical notes:

Set a loss budget first. Agree with finance on the maximum fraud loss the holdout may cause per month. Then size the rate and amount cap to fit it.
Randomize at the right unit. If a fraudster can retry until they land in the holdout, randomize per card fingerprint or per customer, not per attempt.
Wait for labels to mature. Dispute windows can stay open for months. Results from last week's holdout are incomplete.
Respect the exclusions in your analysis. The estimate only applies to the eligible population. Do not extrapolate it to high-amount or velocity-flagged traffic.

Step 5: Replace the fixed threshold with expected cost

Many systems decline above a single score, such as risk_score > 0.7. That treats a small order and a large order the same way, and it ignores what a rejected customer is worth.

A cost-based rule compares the expected loss of each choice:

Expected cost of approving = p × (amount + chargeback_fee + handling_cost)
Expected cost of declining = (1 − p) × (margin + future_value)

Here p is the calibrated probability of fraud. Approve when the first value is smaller than the second.

def should_approve(p, amount, margin, chargeback_fee, handling_cost, future_value):
    cost_approve = p * (amount + chargeback_fee + handling_cost)
    cost_decline = (1 - p) * (margin + future_value)
    return cost_approve < cost_decline

Worked example (illustrative numbers)

An order for $80 has a 30% product margin ($24). Assume a $20 chargeback fee, $10 of handling cost, and $40 of expected future profit from a retained customer. The model outputs p = 0.25.

Cost of approving: 0.25 × (80 + 20 + 10) = $27.50
Cost of declining: 0.75 × (24 + 40) = $48.00

The rule approves. A fixed threshold of 0.2 would have declined this order.

Now change the order to $600 with the same p and a $180 margin:

Approving: 0.25 × 630 = $157.50
Declining: 0.75 × 220 = $165.00

The result is close. A small change in p flips the decision, so this order is a good candidate for manual review. The cost model also tells you where review effort pays off: on orders where the two costs are nearly equal.

This only works if p is calibrated, meaning a score of 0.25 corresponds to roughly 25% observed fraud. Check calibration with a reliability curve on matured data, including weighted holdout rows. Raw model scores are often not calibrated.

Common mistakes and how to catch them

Optimizing chargeback rate alone. You can push it toward zero by declining everything. Always report it alongside approval rate and estimated false-decline rate.
Treating all retries as attacks. Card testing shows many cards, small amounts, and rapid attempts. A real customer retrying usually shows one identity, similar amounts, and a second payment method. Split these with velocity features rather than a blanket retry penalty.
Retraining on approved traffic only. Include weighted holdout outcomes in training data, or the model's caution feeds on itself.
Reading results before labels mature. Use cohort views grouped by decision week. Compare cohorts only once each has passed your dispute-maturity window.
Silent rule accumulation. Rules added after one incident rarely get removed. Track decline volume per rule in rules_fired, and review rules whose holdout outcomes are mostly good.

A weekly scorecard

Once the instrumentation is in place, track these for each model version:

Approval rate, split by decline source
Chargeback rate on matured cohorts
Proxy-detected false declines (lower bound)
Holdout-estimated false-decline rate (unbiased, for the eligible population)
Net expected cost per 1,000 orders under the cost model

When these five move together, you can tell whether a rule change actually helped the business, or only made one metric look better.

Building Your Own Chargeback and Fraud Ratio Monitor Before the Networks Do

Jarrod Wright — Mon, 02 Nov 2026 18:21:49 +0000

Most fraud tooling answers one question: should we accept this order? Card networks care about a different question: how many of your accepted orders came back as fraud? That second number decides whether your merchant account ends up in a monitoring program, with reserves, repricing, or termination as the consequences.

Second-party fraud is where these two questions come apart. A real cardholder hands their credentials to someone else, or colludes with them. The order passes AVS, passes CVV, and the account history looks clean. Your risk model approves it. Weeks later, the cardholder reports the charge as unauthorized. A fraud-coded dispute arrives, and it counts against your ratios the same way a stolen-card order would.

You can't block what your model can't see. You can, however, measure your exposure faster and more accurately than your processor's monthly report does. This article walks through how to build that measurement.

What the networks are actually counting

The exact programs and thresholds change every few years, so treat your acquirer's current documentation as the source of truth. The structure, though, is fairly stable.

Numerator: fraud-related events tied to your merchant ID during a reporting period. Depending on the program, this includes fraud-coded disputes (for example, Visa reason code 10.4 for card-absent fraud, or Mastercard 4837), and it may also include issuer fraud reports that never became disputes.
Denominator: your settled transaction count for a period. This is usually not the same period in which the original transactions happened.
Thresholds: usually a ratio plus a minimum absolute count, so very small merchants don't get flagged over two disputes.

Visa's current program, the Visa Acquirer Monitoring Program (VAMP), combines issuer fraud reports and disputes into a single ratio. Mastercard runs separate programs for excessive chargebacks and excessive fraud. Check the current thresholds before you hardcode anything.

The detail that catches teams off guard

Issuer fraud reports (Visa TC40, Mastercard SAFE) are filed when a cardholder tells their bank a transaction was fraudulent. A fraud report can exist even if you refunded the order and no chargeback was ever filed. If your program counts fraud reports, then refunding a suspicious order early may prevent the dispute and its fee, but it won't remove the fraud report from your ratio.

For second-party fraud this matters a lot. The cardholder is the one claiming fraud, so the fraud report is almost guaranteed.

Data model

You need three event streams joined on transaction ID:

transactions(txn_id, mid, network, settled_at, amount, card_fingerprint)
disputes(dispute_id, txn_id, network, reason_code, received_at, category)
fraud_reports(report_id, txn_id, network, reported_at, fraud_type)

Normalize reason codes into a category column (fraud, consumer, processing, authorization) at ingestion time. Raw codes differ by network and change over time. Mapping them once in a lookup table keeps the downstream queries readable.

Fraud reports often come from your acquirer as a file or report rather than a webhook. Ingest them anyway. If you only track disputes, you will undercount your exposure under a combined-ratio program.

Computing the ratio the way the network does

The most common mistake is cohort mismatch: dividing this month's disputes by the transactions those disputes came from. Networks typically divide events received in a month by transactions settled in that same month (or the prior month, depending on the program). Disputes lag transactions by weeks, so the two methods give very different numbers during growth or decline.

from collections import defaultdict

def monthly_ratios(transactions, disputes, fraud_reports, mid, network):
    txn_count = defaultdict(int)
    for t in transactions:
        if t.mid == mid and t.network == network:
            txn_count[t.settled_at.strftime('%Y-%m')] += 1

    events = defaultdict(int)
    for d in disputes:
        if d.network == network and d.category == 'fraud' and belongs_to(d.txn_id, mid):
            events[d.received_at.strftime('%Y-%m')] += 1
    for r in fraud_reports:
        if r.network == network and belongs_to(r.txn_id, mid):
            events[r.reported_at.strftime('%Y-%m')] += 1

    # NOTE: whether a txn with both a fraud report and a dispute
    # counts once or twice is program-specific. Make it a config flag.
    return {
        month: {
            'events': events[month],
            'txns': txn_count[month],
            'ratio': events[month] / txn_count[month] if txn_count[month] else None,
        }
        for month in txn_count
    }

Keep the deduplication rule configurable. Some programs count a transaction that has both a fraud report and a dispute as two events. Others count it once. Getting this wrong can make you look twice as healthy as you are.

Worked example: a small ring, a big swing

Assume a merchant processes 20,000 Visa card-not-present transactions per month. Their baseline is steady: about 40 fraud-coded events a month, a ratio of 0.20%.

Now a second-party fraud pattern starts. A handful of cardholders sell their card details to a reshipper, then file fraud claims once the goods arrive. Over three weeks, 90 orders go out. Every one passes AVS and CVV.

Here's how it plays out:

Month	Settled txns	Baseline events	Ring events received	Ratio
M1 (orders ship)	20,000	40	0	0.20%
M2	20,000	40	70	0.55%
M3	20,000	40	20	0.30%

The dashboard looked clean in M1, which is when the damage was actually done. If the network counts fraud reports and disputes separately for the same transaction, the M2 ring contribution could approach 140 events, putting the ratio near 0.90%.

No single month here necessarily crosses a threshold. But a merchant already running near the limit, or one with seasonal volume dips that shrink the denominator, can tip over from one small ring. Projection matters more than the current reading.

Projecting forward

Because disputes lag, you can estimate next month's events from orders you've already shipped. Use your historical dispute-lag distribution:

def projected_events(shipped_orders, lag_curve, risk_score_fn):
    # lag_curve[k] = share of eventual fraud events arriving k months after settlement
    # risk_score_fn = estimated probability that an order becomes a fraud event
    projection = defaultdict(float)
    for o in shipped_orders:
        p = risk_score_fn(o)
        for k, share in enumerate(lag_curve):
            month = add_months(o.settled_at, k).strftime('%Y-%m')
            projection[month] += p * share
    return projection

For second-party fraud, a generic fraud score helps little, since these orders score as clean. Use signals that show up after authorization instead:

The shipping address appears across several unrelated cardholders.
A new device places an order on an account whose card history shows no prior use from that device.
Card fingerprints cluster with known reshipper or freight-forwarder addresses.
Several first-time orders on established cards land on the same delivery address within days.

Any of these can raise p for orders already in flight. That gives you an early estimate of the incoming spike.

Alerting rules that are actually useful

Alert on trajectory, not just level.

Signal	Rule	Why
Current ratio	> 60% of program threshold	Leaves room to act before the month closes
Projected ratio	Next month > 80% of threshold	Catches lagged spikes like the M2 above
Absolute count	Within 20% of the program's minimum count	Small merchants get flagged on count first
Denominator drop	Settled txns down > 25% month over month	Same events, smaller base, higher ratio
Cluster detection	≥ N fraud events sharing a ship-to address	Second-party rings often reuse addresses

Tune the percentages to your risk tolerance. The point is to page someone while there's still time to tighten rules on in-flight orders or talk to your acquirer.

Common mistakes

Aggregating across MIDs. Networks evaluate per merchant ID (and sometimes per acquirer). A healthy blended ratio can hide one MID that's in trouble.

Using order count instead of transaction count. Split shipments, partial captures, and recurring billing create multiple transactions per order. Count what the network counts.

Netting out refunds. A refunded transaction still settled. Whether it stays in the denominator depends on the program, so don't assume.

Treating won disputes as removed. Winning representment recovers funds. It generally does not remove the dispute from monitoring counts. Verify this for your programs, but don't build your projections on the assumption that wins reduce the ratio.

Ignoring reason-code drift. Issuers sometimes file consumer-type claims under fraud codes, and the reverse. Track the raw code alongside your normalized category so you can audit the mapping.

Testing the monitor

Build a fixture month with known values and assert against them. Include:

A transaction with both a fraud report and a dispute, to test the dedup flag.
A dispute received in a month after its transaction settled, to test cohort logic.
A refunded transaction that still received a fraud report.
Two MIDs, to make sure nothing leaks across them.

Then reconcile your computed ratio with your acquirer's monthly report. If they differ by more than rounding, your definitions are wrong. Find out which definition is wrong before an auditor does.

Where this fits

Monitoring won't stop second-party fraud. The orders look legitimate by design, and the liability usually stays with the merchant. What monitoring does is turn a surprise enrollment letter into a trend you saw coming weeks earlier. For the broader picture of why these losses land where they do, see this breakdown of second-party fraud liability.

From One Chargeback to a Fraud Ring: Building Link Analysis That Works

Jarrod Wright — Mon, 02 Nov 2026 18:03:54 +0000

A single disputed order rarely arrives alone. When a fraud chargeback lands, the account behind it is often one node in a small network of accounts that share a phone, a drop address, or a payment instrument. Link analysis means starting from one confirmed bad account and finding the others. It is one of the highest-leverage tools a fraud or payments engineering team can build.

It is also easy to build badly. A naive implementation either finds nothing or links your whole customer base through a single carrier-grade NAT IP. This article covers how to model the problem, how to normalize identifiers, how to stop hub nodes from poisoning the results, and how to score what you find. For the dispute-side context on why these cases are hard to win and when to fight them, see this chapter on second-party fraud.

Model It as a Bipartite Graph

Don't draw edges directly between accounts. Model two node types:

Account nodes: your customer accounts.
Identifier nodes: typed values such as (device, fp_9a3c), (card, fingerprint_77e1), (address, 12 elm st apt 4 springfield 01101), (phone, +15551234567), (email, jdoe@example.com), (ip24, 203.0.113.0/24).

An edge means "this account used this identifier." Two accounts are linked when they share an identifier node.

This structure has three practical benefits:

You can see why two accounts are linked, which you need for analyst review and for any dispute evidence.
You can measure an identifier's degree, meaning how many accounts touch it. That number is your main defense against false positives.
Adding a new identifier type is just a new kind, with no schema change.

Normalize Before You Link

Link analysis is only as good as your equality checks. Raw values almost never match across accounts, so normalize each type deliberately.

Identifier	Normalization	Pitfall
Email	Lowercase. Strip `+tag` suffixes. Apply provider-specific rules such as ignoring dots for providers that ignore them	Applying dot-stripping to providers that treat dots as significant
Phone	Convert to E.164	Numbers stored without a country code
Address	Lowercase, expand or collapse abbreviations (`street`→`st`), strip punctuation, keep the unit number	Dropping the apartment number merges a whole building
IP	Group IPv4 to /24 and IPv6 to /64	Treating a grouped IP as strong evidence
Card	Use your processor's card fingerprint or token, never a raw PAN	Storing PANs in a fraud database creates PCI scope
Device	Use your fingerprinting vendor's stable ID	Fingerprints drift after browser or OS updates

A minimal normalizer for the trickier types:

import ipaddress, re

ABBREV = {"street": "st", "avenue": "ave", "road": "rd", "apartment": "apt", "suite": "ste"}

def norm_ip(ip: str) -> str:
    addr = ipaddress.ip_address(ip)
    prefix = 24 if addr.version == 4 else 64
    return str(ipaddress.ip_network(f"{ip}/{prefix}", strict=False))

def norm_address(line1, line2, city, postal):
    raw = " ".join([line1, line2 or "", city, postal]).lower()
    raw = re.sub(r"[^a-z0-9 ]", " ", raw)
    tokens = [ABBREV.get(t, t) for t in raw.split()]
    return " ".join(tokens)

def norm_email(email: str) -> str:
    local, domain = email.lower().split("@", 1)
    local = local.split("+", 1)[0]
    return f"{local}@{domain}"

In production, use a proper address-standardization service rather than regex. The point here is the principle: decide what "same" means for each type, and write it down.

Weight Edges by How Much They Prove

Not all shared identifiers mean the same thing. A shared card fingerprint across two "unrelated" accounts is close to conclusive. A shared /24 subnet means almost nothing alone.

Assign each identifier type two numbers:

Weight: how strongly a shared value suggests the same actor.
Hub cap: the degree above which a value is probably shared infrastructure rather than a shared person.

WEIGHTS = {"card": 1.0, "device": 0.9, "address": 0.8, "phone": 0.7, "email": 0.6, "ip24": 0.2}
HUB_CAP = {"card": 3, "device": 5, "address": 8, "phone": 3, "email": 2, "ip24": 25}

These values are starting points. Tune them against confirmed cases from your own data.

Traversal With Hub Suppression

The expansion is a bounded breadth-first search from the seed account. Two rules matter:

Skip hub identifiers. If an identifier touches more accounts than its cap allows, don't traverse through it. Shared mobile-carrier IPs, corporate VPN exits, reshipping warehouses, and popular pickup lockers are all hubs.
Only strong edges propagate. Weak edges, such as a shared subnet, are recorded as supporting evidence but don't pull new accounts into the frontier.

from collections import defaultdict, deque

class LinkGraph:
    def __init__(self):
        self.acct_to_ids = defaultdict(set)
        self.id_to_accts = defaultdict(set)

    def add(self, account_id, kind, value):
        node = (kind, value)
        self.acct_to_ids[account_id].add(node)
        self.id_to_accts[node].add(account_id)

    def expand(self, seed, max_hops=2, min_weight=0.6):
        hops_of = {seed: 0}
        evidence = defaultdict(list)   # account -> [(via_account, identifier)]
        q = deque([seed])
        while q:
            acct = q.popleft()
            if hops_of[acct] >= max_hops:
                continue
            for node in self.acct_to_ids[acct]:
                kind, _ = node
                linked = self.id_to_accts[node]
                if len(linked) > HUB_CAP[kind]:
                    continue
                for other in linked:
                    if other == acct:
                        continue
                    evidence[other].append((acct, node))
                    if other not in hops_of and WEIGHTS[kind] >= min_weight:
                        hops_of[other] = hops_of[acct] + 1
                        q.append(other)
        return hops_of, evidence

Scoring linked accounts

For each discovered account, combine its edge weights with a noisy-OR. This treats each link as independent evidence, so several moderate links add up without going past 1.0:

def link_score(edges):
    p_not = 1.0
    for _, (kind, _) in edges:
        p_not *= (1 - WEIGHTS[kind])
    return 1 - p_not

An account sharing only an email (0.6) scores 0.6. An account sharing a phone and an address scores 1 - (0.3 × 0.2) = 0.94. Accounts above a high threshold go to automated action. Those in the middle go to an analyst queue.

Worked Example

Account A1 receives a fraud chargeback. You snapshot its identifiers and run the expansion.

A1 used device D1. D1 is also on A2 and A3, so the degree is 3, under the cap of 5. Both are added at hop 1.
A3 shipped to address X. X is also on A4, with a degree of 2. A4 is added at hop 2.
A4 logged in from 198.51.100.0/24, which is shared by 140 accounts. That exceeds the cap of 25, so it is skipped.
A2 shares 203.0.113.0/24 with A5. This is a weak edge (0.2), so A5 is recorded as evidence but not traversed.

The result:

Account	Hop	Links	Score	Action
A2	1	device	0.90	Auto-review, hold orders
A3	1	device	0.90	Auto-review, hold orders
A4	2	address	0.80	Analyst queue
A5	—	ip24	0.20	Log only

Without hub suppression, the 140-account subnet would have pulled in a large slice of a mobile carrier's customers. That is the most common way these systems lose analyst trust.

Data Flow: Where This Runs

A practical pipeline looks like this:

Capture. At order time, write normalized identifiers to an append-only events table with timestamps. Don't overwrite.
Snapshot on trigger. When a dispute or fraud flag arrives, freeze the seed account's identifiers before anyone closes the account or deletes payment methods. Remediation steps often destroy the very data you need.
Expand. Run the bounded traversal against the identifier index. A relational database with indexes on (kind, value) is enough at moderate scale. A graph database becomes useful when you need many hops or interactive exploration.
Score and route. High scores trigger blocks or order holds. Mid-range scores go to analysts, along with the evidence paths.
Feed back. Analyst verdicts become labels for tuning weights and caps.

Common Mistakes and How to Catch Them

Ignoring time. An address shared by two accounts three years apart may simply be a new tenant. Add a time window to edges, or decay weights with age. You can catch this by sampling linked pairs and checking how far apart their activity was.

Static hub caps. A drop address used by a fraud ring can legitimately exceed a cap, since that is what a drop is. Before skipping a high-degree node, check whether it is a known hub (a carrier IP range or a published reshipper address) or an unknown one. Unknown high-degree addresses are worth an analyst's look rather than a silent skip.

Households look like rings. Family members share devices, addresses, and sometimes cards. In second-party fraud the person misusing the account is often close to the cardholder, so this is signal, not noise. It still shouldn't trigger automatic blocks on every relative. Route household-shaped clusters, meaning a single address with shared devices, to humans.

Unbounded hops. Every extra hop multiplies the candidate set. Keep max_hops at 2 for automated actions. Allow analysts to expand further manually.

Fingerprint drift. A ring member who updates their browser may get a new device ID. Blocking only on device misses them. Blocking on the device plus the drop address plus the card fingerprint is far more durable.

No measurement. Track precision on analyst-reviewed clusters per identifier type. If email links are confirmed only a third of the time, lower the weight.

What You Get Out of It

A working link-analysis pipeline turns each confirmed fraud case into three outputs: a set of accounts to hold or block, a set of non-disposable identifiers to blocklist, and labeled data that improves your rules. The chargeback itself may be unrecoverable. The cluster behind it usually isn't.

Finding Fraud Rings with Link Analysis: A Union-Find Approach

Jarrod Wright — Wed, 28 Oct 2026 18:56:35 +0000

Most fraud checks evaluate one order at a time: is this card valid, does the AVS match, does the device look risky? That works when the attacker is using stolen credentials. It breaks down when the credentials are real, such as when a fraudster operates through accounts that belong to cooperating or recruited people. Every individual record looks clean.

What a single operator cannot easily hide is reuse. They ship to the same drop address, check out from the same laptop, or cycle the same handful of payment instruments across "unrelated" accounts. Those connections only show up when you stop looking at rows and start looking at relationships. For the full set of order-, account-, and portfolio-level warning signs in this kind of scheme, see the overview of second-party fraud red flags. This article focuses on one of them: building the link-analysis layer that surfaces shared-infrastructure clusters.

The data model: accounts and identifiers as a graph

Model your customer base as a bipartite graph:

Account nodes: one per customer account.
Identifier nodes: one per distinct device fingerprint, normalized shipping address, payment instrument fingerprint, phone number, or email.
Edges: an account is connected to every identifier it has used.

Two accounts are "linked" if a path exists between them through shared identifiers. A connected component in this graph is a candidate cluster.

You don't need a graph database to start. A table of (account_id, identifier_type, identifier_value, first_seen, last_seen) is enough, and a union-find structure can compute components over millions of edges on a single machine.

Step 1: Normalize identifiers before you link anything

Graph quality depends almost entirely on identifier normalization. Two strings that refer to the same thing must collapse to the same node, and two strings that don't must stay separate.

Identifier	Normalization	Pitfall
Shipping address	Canonicalize via an address standardization service, keep unit/apartment numbers	Dropping the unit merges every resident of an apartment building
Email	Lowercase; for providers that ignore dots or `+tags`, strip them	Applying Gmail rules to every domain creates false merges
Phone	Convert to E.164	Shared household landlines
Payment instrument	Use the processor-supplied card fingerprint or token, never the raw PAN	Network tokens can differ per wallet for the same underlying card
Device	Use a stable fingerprint ID, not raw user-agent strings	Popular device models with default settings produce near-identical fingerprints

Using a processor fingerprint for cards keeps raw card numbers out of your fraud pipeline entirely, which also keeps that system out of a large chunk of PCI DSS scope.

Step 2: Handle supernodes before they swallow your graph

This is the failure mode that kills most first attempts. Some identifiers are legitimately shared by thousands of accounts:

IP addresses behind carrier-grade NAT or corporate proxies
Office mailrooms, university dorms, and package lockers
Freight forwarders (which are both a red flag and a supernode)
Your own warehouse address used for in-store pickup

If you union through any of these, you get one giant component containing most of your customers, and the analysis becomes useless.

Two standard defenses:

Degree caps per identifier type. Count how many distinct accounts touch each identifier. Skip identifiers above a type-specific threshold when building components. An address with 4 accounts is interesting; one with 4,000 is infrastructure.
Allow/deny lists. Explicitly exclude known infrastructure (your stores, known lockers). Track known reshippers separately: don't use them to link accounts, but do flag any account that ships to them.

IPs are usually too noisy to link on at all. Use them as cluster features, not edges.

Step 3: Compute components with union-find

Union-find (disjoint set union) is a good fit: it processes edges in a single pass, with path compression and union by rank giving near-constant amortized time per operation.

from collections import defaultdict

class DSU:
    def __init__(self):
        self.parent, self.rank = {}, {}

    def find(self, x):
        self.parent.setdefault(x, x)
        self.rank.setdefault(x, 0)
        root = x
        while self.parent[root] != root:
            root = self.parent[root]
        while self.parent[x] != root:          # path compression
            self.parent[x], x = root, self.parent[x]
        return root

    def union(self, a, b):
        ra, rb = self.find(a), self.find(b)
        if ra == rb:
            return
        if self.rank[ra] < self.rank[rb]:
            ra, rb = rb, ra
        self.parent[rb] = ra
        if self.rank[ra] == self.rank[rb]:
            self.rank[ra] += 1

DEGREE_CAP = {"device": 10, "address": 8, "card": 5, "phone": 5}

def build_clusters(edges, excluded=frozenset()):
    # edges: iterable of (account_id, id_type, id_value)
    edges = list(edges)
    degree = defaultdict(set)
    for acct, t, v in edges:
        degree[(t, v)].add(acct)

    dsu = DSU()
    for acct, t, v in edges:
        dsu.find(f"acct:{acct}")              # register isolated accounts
        key = (t, v)
        if key in excluded or t not in DEGREE_CAP:
            continue
        if len(degree[key]) > DEGREE_CAP[t]:
            continue                           # supernode: skip as a link
        dsu.union(f"acct:{acct}", f"{t}:{v}")

    clusters = defaultdict(set)
    for node in list(dsu.parent):
        if node.startswith("acct:"):
            clusters[dsu.find(node)].add(node[5:])
    return [c for c in clusters.values() if len(c) > 1]

The degree caps here are placeholders. Set them from your own data by looking at the degree distribution for each identifier type and choosing a cutoff above the household-sharing range.

Worked example

Six accounts, with these edges:

Account	Device	Ship-to	Card	IP
A1	D1	S1	C1	carrier NAT
A2	D1	S2	C2	carrier NAT
A3	D1	S3	C3	home ISP
A4	D9	S3	C4	home ISP
A5	D5	S5	C5	carrier NAT
A6	D6	S6	C6	carrier NAT

Walking through it:

A1, A2, A3 share device D1, so they merge.
A3 and A4 share address S3, which pulls A4 into the same component, even though A4 never touched D1. This transitive link is exactly what row-level review misses.
A5 and A6 share only the carrier NAT IP, which isn't an edge type at all. They stay separate.

Result: one cluster {A1, A2, A3, A4}. Four accounts with four different cards and four different names, connected by one laptop and one drop address.

Step 4: Score clusters, not just membership

A component is a candidate, not a verdict. Families share devices. Roommates share addresses. Compute features per cluster and score them:

Feature	Benign pattern	Suspicious pattern
Distinct surnames / billing names	1 to 2	Many, unrelated
Distinct billing addresses	1 to 2	Many, geographically spread
Shared ship-to vs. billing	Ship-to matches someone's billing	Shared ship-to matches no one's billing
Account creation/reactivation spread	Months or years	Narrow window
Promo redemptions per account	Low	Every account redeemed a new-customer offer
Disputes in cluster	None	Any fraud dispute on any member
Link type mix	Address only	Device and address and card

The last row matters. A cluster held together by a single shared address is weak evidence. A cluster where accounts share devices and addresses and cards is much harder to explain innocently.

A dispute on any member is also a strong propagation signal. When one account in a cluster files a fraud claim, review the open orders of the others before they ship.

Step 5: Add time to the edges

Identifier reuse that's years apart means something different from reuse within the same week. Store first_seen and last_seen on each edge and either:

build components only from edges active within a rolling window (say, 90 days), or
weight edges by recency and compute clusters with a weighted method instead of plain union-find.

Without this, an address that changed hands two tenants ago will keep linking strangers forever.

Batch vs. real-time

Union-find supports incremental unions but not deletions. A practical split:

Nightly batch: rebuild components from scratch with current degree caps and time windows. This handles expiring edges cleanly.
At checkout: look up the incoming order's device, address, and card in the precomputed cluster index. If any of them belongs to a flagged cluster, add that to the order's risk score.

If you need fully real-time linking, a graph database or a streaming connected-components job is the next step, but most teams get substantial value from the batch-plus-lookup pattern first.

Common mistakes and how to catch them

One giant component. Check the size of your largest cluster after every run. If it suddenly jumps, a new supernode slipped under the cap. Log the top identifiers by degree each run.
Linking on IP. Almost always too noisy. Use it as a feature.
Over-normalizing addresses. Spot-check clusters linked only by address; if they're all apartment buildings, your unit parsing is broken.
Auto-declining cluster members. Feed cluster risk into scoring or step-up verification, not hard blocks. Many cluster members will be legitimate.
Never measuring outcomes. Track dispute rates for flagged vs. unflagged clusters over time. If flagged clusters don't dispute at a higher rate, your features or thresholds are wrong.

Testing the pipeline

You rarely have clean labels, so seed your own. Inject synthetic rings into a copy of production data: N accounts sharing a device and a drop address, with varied names and cards. Then verify that:

each synthetic ring comes back as exactly one cluster,
it doesn't merge with real customers through a supernode, and
its cluster score lands above your review threshold.

Also inject benign patterns, like a family of four on one device with one shared address, and confirm they score low. Both test sets belong in CI, so a change to normalization or degree caps can't silently break detection.

Link analysis won't catch a lone actor using a single borrowed account. What it does catch is scale, which is where most of the losses are. Once reuse becomes visible as structure, it's very hard for an operator to hide.

Modeling PayPal's Tiered Dispute Fee With a Trailing-Window Monitor

Jarrod Wright — Fri, 23 Oct 2026 17:55:51 +0000

Most fee logic in a payments integration is stateless. You take a transaction amount, apply a percentage and a fixed component, and you're done. PayPal's US dispute fee doesn't work that way. The fee charged on a dispute depends on your account's recent history, not on the dispute itself.

As of the fee schedule cited in this roundup of PayPal statistics on volume, fees, and fraud, disputes on PayPal-account and Guest Checkout payments cost $15 by default and $30 once your dispute rate reaches 1.5% or more across more than 100 sales in the previous three full months. Card chargebacks that don't go through a PayPal account or Guest Checkout are handled separately, with a flat $20 fee.

This article treats that rule as an engineering problem. The goal is a small service that computes your current tier, forecasts next month's tier, and tells you how much headroom you have before the fee doubles.

Why this deserves code instead of a spreadsheet

A tiered fee driven by a rolling window has three properties that make it easy to get wrong by hand:

Lag. A bad month doesn't hurt you immediately. It hurts you for the next three months.
A volume gate. Below 101 sales in the window, the rate doesn't matter at all. Cross that line and a rate you've been running for months suddenly counts.
A hard threshold. At 1.5% exactly, you're in the higher tier. One dispute can flip it.

If you already ingest dispute events, through webhooks such as CUSTOMER.DISPUTE.CREATED or by polling the Disputes API, you have everything you need to compute this yourself.

Defining the window precisely

"Previous three full months" means calendar months that have fully closed. It doesn't mean the last 90 days. For a date in March, the window is December 1 through the end of February.

That has a consequence that's easy to miss. A spike in January sits in the window for February, March, and April:

Billing month	Window	Includes January?
February	Nov–Jan	Yes
March	Dec–Feb	Yes
April	Jan–Mar	Yes
May	Feb–Apr	No

One bad month can mean a full quarter of doubled dispute fees. Your monitor should surface that horizon explicitly.

The data you need

Per account, per calendar month:

sales_count: completed sales that count toward the denominator.
dispute_count: disputes that count toward the numerator.

Two open questions you must answer against PayPal's current terms before trusting your numbers:

Attribution. Is a dispute counted in the month it was opened, or in the month of the original sale? These give different results when disputes arrive weeks after purchase.
Scope. Which dispute stages count (inquiries, claims, chargebacks), and which payment types count as "sales"?

Don't hardcode either answer. Make them configuration, because the definition can change and you'll want to recompute history when it does.

Implementation

Here's a minimal Python version. It uses integer arithmetic for the threshold comparison so floating-point rounding can't put you on the wrong side of 1.5%.

from dataclasses import dataclass
from datetime import date
from math import ceil

# Configurable: verify against the current PayPal fee page.
THRESHOLD_BPS = 150          # 1.5% expressed in basis points
MIN_SALES_EXCLUSIVE = 100    # "more than 100" => 101+
STANDARD_FEE = 15_00         # cents
HIGH_FEE = 30_00             # cents

@dataclass
class MonthStats:
    sales: int
    disputes: int

def window_months(billing_month: date) -> list[tuple[int, int]]:
    """Three full calendar months preceding billing_month."""
    y, m = billing_month.year, billing_month.month
    out = []
    for _ in range(3):
        m -= 1
        if m == 0:
            y, m = y - 1, 12
        out.append((y, m))
    return out

def tier_for(billing_month: date, stats: dict[tuple[int, int], MonthStats]):
    months = window_months(billing_month)
    sales = sum(stats.get(k, MonthStats(0, 0)).sales for k in months)
    disputes = sum(stats.get(k, MonthStats(0, 0)).disputes for k in months)

    gated = sales > MIN_SALES_EXCLUSIVE
    # disputes / sales >= 1.5%  <=>  disputes * 10000 >= 150 * sales
    over = gated and disputes * 10_000 >= THRESHOLD_BPS * sales

    # Largest dispute count that stays below the threshold for this volume
    max_safe = ceil(THRESHOLD_BPS * sales / 10_000) - 1 if gated else None

    return {
        "window": months,
        "sales": sales,
        "disputes": disputes,
        "tier": "high" if over else "standard",
        "fee_cents": HIGH_FEE if over else STANDARD_FEE,
        "headroom": (max_safe - disputes) if max_safe is not None else None,
    }

Note that ceil of a float can misbehave at exact boundaries. For production, compute max_safe with integer math: (THRESHOLD_BPS * sales + 9999) // 10000 - 1.

Worked example

It's March. Your window is December through February:

Month	Sales	Disputes
December	950	12
January	780	14
February	670	8
Total	2,400	34

The rate is 34 / 2,400 = 1.417%. You're in the standard tier.

Now the headroom: 1.5% of 2,400 is exactly 36, and 36 disputes would meet the threshold. So the maximum safe count is 35, and your headroom is one dispute. If a single late dispute gets attributed back into February, March flips to $30 per dispute.

That's the number worth alerting on. Rate alone (1.42%, comfortably under 1.5%) gives a false sense of safety.

Forecasting April

April's window drops December and adds March. December had a relatively low rate (1.26%) on high volume. If March comes in at 700 sales and 15 disputes, April's window is 2,150 sales and 37 disputes, which is 1.72%. You'd enter the high tier in April even though no single month changed dramatically.

Your monitor should compute the next window using month-to-date figures and a projection for the rest of the current month.

The volume-gate trap

Small merchants have a specific failure mode. Consider a window with 98 sales and 6 disputes, a 6.1% rate. That's standard tier, because sales don't exceed 100.

Grow to 101 sales with the same disputes and you're instantly at 5.9% and in the high tier. Growth itself triggered the fee increase.

If you're near the gate, track two alerts:

Projected window sales crossing 100.
Projected rate at that point exceeding 1.5%.

Decision table for alerts

Window sales	Rate	Headroom	Action
≤ 100	any	n/a	Watch projected sales vs. gate
> 100	< 1.0%	large	No action
> 100	1.0–1.5%	≤ 3 disputes	Warn: one bad week flips tier
> 100	≥ 1.5%	negative	Alert: compute months until the spike rolls out

For the last row, find the earliest billing month where removing the oldest months brings the rate under 1.5%, assuming projected volume. That tells finance how long elevated fees will last.

Common mistakes and how to catch them

Using a rolling 90 days. It produces a rate that's close but not identical, and it disagrees with the actual fee most at month boundaries. Unit-test window_months around January to catch year wraparound.

Float comparison at the threshold. 0.015 * 2400 is not guaranteed to equal 36.0 exactly. Compare integers, as above.

Off-by-one on "more than 100." Write a test that asserts 100 sales is ungated and 101 is gated.

Mixing card chargebacks into the count. Card payments outside PayPal accounts and Guest Checkout carry their own $20 chargeback fee. Whether they count toward this dispute rate is a definitional question. Keep them in a separate column so you can include or exclude them by config.

Double-counting escalations. A single case can move from inquiry to claim, or get reopened. Key your dispute table on the dispute ID and dedupe on it. Don't count event rows, because one dispute can emit several webhooks.

Dropping late webhooks. Webhooks retry and can arrive out of order. Write disputes idempotently, then recompute affected windows when a dispute lands in an already-closed month. Run a nightly reconciliation against the Disputes API to catch anything the webhook path missed.

Ignoring sandbox and test traffic. Filter by environment before aggregation, or test sales will inflate your denominator and hide a real problem.

Testing the monitor

A few property-style tests go a long way:

For any sales > 100, tier == "high" exactly when disputes >= ceil(0.015 * sales).
Adding sales without disputes never moves you from standard to high, unless it crosses the 100 gate.
Shifting all data forward by one month shifts the tier output by exactly one month.

Run these against generated data, then backtest against your actual fee statements. If your computed tier disagrees with what PayPal charged in any month, your attribution or scope assumptions are wrong. Fix the configuration before trusting the forecasts.

Wrapping up

The tiered dispute fee is a small line item per case, but it's a stateful, lagging, threshold-based rule. Rules like that punish anyone who only looks at the current month. A few dozen lines of code give you three things a monthly statement won't: current tier, headroom in absolute disputes, and how many months a bad stretch will cost you.

Don't Refund on 'Delivered': Hardening Return Workflows Against FTID Fraud

Jarrod Wright — Fri, 23 Oct 2026 15:29:33 +0000

Many e-commerce backends ship with a return flow like this:

// Don't do this
app.post('/webhooks/carrier', async (req, res) => {
  const evt = req.body;
  if (evt.status === 'DELIVERED') {
    const rma = await db.returns.findByTracking(evt.trackingNumber);
    await payments.refund(rma.orderId, rma.amount);
  }
  res.sendStatus(200);
});

It is fast and cheap to run, and customers like it. It also contains a clear security bug. It treats a carrier status as proof that your merchandise came back. Fraudsters exploit this with FTID (fake tracking ID) attacks. They take the prepaid return label you issued, keep the barcode intact, and edit the visible address or move part of the label onto a decoy package. The carrier scans the barcode and moves something to somewhere. Your webhook fires DELIVERED, and your system pays out.

For the wider fraud landscape (label editing, account address switching, courier impersonation), see this overview of package redirection scams and tracking red flags. This article stays narrow. It covers how to engineer the refund trigger so a single upstream event cannot release money.

What a 'delivered' event actually asserts

A delivery scan tells you very little. In practice it means:

A barcode encoding your tracking number was scanned.
The scanning party recorded a delivery event at some location and time.

It does not assert:

That the package contents match the RMA.
That the physical address on the box matched your returns facility.
That the package passed through your receiving dock.

Model the carrier as an untrusted, eventually consistent data source. Its events are hints that move a return forward in your workflow. They should never authorize a payment by themselves.

Signals you can actually check

The carrier event is useful once you cross-check it against data you control. Depending on the carrier and your integration, these fields may be available:

Signal	Source	What it catches
Delivery scan location (city/postal code)	Carrier tracking API scan events	Label edited to send the package to a different destination
Scan path / origin postal code	Carrier scan history	Label reused from a different origin than the customer's address
Carrier-reported or billed weight	Carrier API or invoice data	Empty envelope or junk shipped as a decoy
Service type / package type	Carrier metadata	Envelope or letter service on an RMA for a boxed item
Your own dock intake scan	Your WMS	'Delivered' events that never physically arrived at your facility
Intake weight and SKU scan	Your WMS	Weight and content mismatch, item swap
Time between label issue and first scan	Your DB + carrier	Labels scanned implausibly fast or from an unusual region

The last two rows are the only ones fully under your control. They are also the strongest signals. Everything above them is supporting evidence.

Model returns as a state machine

Do not keep a boolean refunded flag. Make the states explicit and limit which actors can trigger each transition:

REQUESTED -> LABEL_ISSUED -> IN_TRANSIT -> CARRIER_DELIVERED
                                              |
                                              v
                              RECEIVED_AT_DOCK -> INSPECTED -> REFUNDED
                                              |               
                                              +--> HELD_FOR_REVIEW -> REFUNDED | REJECTED

The key rule is that carrier webhooks can only advance the return to CARRIER_DELIVERED. Only an internal event can move it to RECEIVED_AT_DOCK: a WMS scan, a staff action, or an automated scale. The refund transition requires INSPECTED or an explicit review decision.

If the business needs instant refunds for low-risk customers, implement them as a policy that operates on a risk score. Do not bypass the state machine for them.

Implementation

1. Webhook handler: record, don't act

app.post('/webhooks/carrier', verifySignature, async (req, res) => {
  const evt = normalizeCarrierEvent(req.body); // map carrier-specific codes

  // Idempotency: carriers retry, and events arrive out of order
  const inserted = await db.carrierEvents.insertIfAbsent(evt.eventId, evt);
  if (!inserted) return res.sendStatus(200);

  await queue.publish('return.carrier_event', { trackingNumber: evt.trackingNumber });
  res.sendStatus(200);
});

The handler stores the event and enqueues a job. It never calls the payments service. This also keeps the handler fast, so the carrier does not time out and retry.

2. Evaluator: compare against the RMA

type Finding = { code: string; severity: 'info' | 'warn' | 'block' };

function evaluateDelivery(rma: Return, events: CarrierEvent[]): Finding[] {
  const findings: Finding[] = [];
  const delivered = latestByTimestamp(events.filter(e => e.status === 'DELIVERED'));
  if (!delivered) return findings;

  // Destination check
  if (delivered.postalCode && !rma.facility.postalCodes.includes(delivered.postalCode)) {
    findings.push({ code: 'DEST_MISMATCH', severity: 'block' });
  }

  // Origin check: first scan should be near the customer
  const first = earliestByTimestamp(events);
  if (first?.postalCode && !isNearby(first.postalCode, rma.customerPostalCode)) {
    findings.push({ code: 'ORIGIN_UNUSUAL', severity: 'warn' });
  }

  // Weight check, if the carrier reports one
  const reported = toGrams(delivered.weight ?? first?.weight);
  if (reported != null) {
    const ratio = reported / rma.expectedShippedWeightGrams;
    if (ratio < 0.5) findings.push({ code: 'WEIGHT_LOW', severity: 'block' });
    else if (ratio < 0.8) findings.push({ code: 'WEIGHT_SOFT_LOW', severity: 'warn' });
  }

  // Service type: envelope for a boxed item
  if (delivered.packageType === 'ENVELOPE' && rma.expectedPackageType === 'BOX') {
    findings.push({ code: 'PACKAGE_TYPE_MISMATCH', severity: 'block' });
  }

  return findings;
}

The thresholds are placeholders. Calibrate them against your own historical returns (see below).

3. Intake: the authoritative check

At the dock, a scan of the return label should pull up the RMA and log the scale weight automatically. Requiring manual weight entry produces bad data.

async function onDockIntake(trackingNumber: string, scaleGrams: number, scannedSkus: string[]) {
  const rma = await db.returns.findByTracking(trackingNumber);
  await transition(rma, 'RECEIVED_AT_DOCK', { scaleGrams });

  const skuOk = sameMultiset(scannedSkus, rma.skus);
  const weightOk = within(scaleGrams, rma.expectedShippedWeightGrams, 0.15);

  if (skuOk && weightOk) await transition(rma, 'INSPECTED');
  else await transition(rma, 'HELD_FOR_REVIEW', { skuOk, weightOk });
}

Decision table for the refund trigger

Carrier findings	Dock intake	Customer risk	Action
None	Not yet	Low, established history	Optional provisional refund, with clawback flag
None	Not yet	New or elevated	Wait for intake
Any `warn`	Not yet	Any	Wait for intake
Any `block`	Not yet	Any	Hold, alert fraud queue, do not refund
Any	Passed (SKU + weight)	Any	Refund
Any	Failed	Any	Hold for manual review
'Delivered' but no intake after N business days	—	Any	Investigate: search the dock, open a carrier trace

The last row matters. A DELIVERED event with no matching dock scan is a strong FTID indicator on its own. It means the carrier claims delivery to you and your building has no record of the package.

Worked example

A customer returns headphones. The RMA expects about 900 g shipped weight from postal code 30301, delivered to your facility at 75201.

Events received:

PICKED_UP at 30301. Weight is reported as 0.12 lb.
IN_TRANSIT through a regional hub.
DELIVERED at postal code 75204.

Evaluator output:

DEST_MISMATCH (block): 75204 is not one of your facility codes.
WEIGHT_LOW (block): 0.12 lb is about 54 g, roughly 6% of the expected weight.

The naive handler would have refunded at step 3. With the evaluator, the return goes to HELD_FOR_REVIEW, the fraud queue gets the tracking history, and no dock intake arrives. You have evidence ready if the customer escalates or files a dispute.

Common mistakes

Mixing units. Carriers report weight in pounds, ounces, or kilograms, sometimes depending on the service. Normalize at ingestion. A unit bug can mark every legitimate return as an empty envelope.

Comparing against item weight instead of shipped weight. Packaging adds mass. Store an expected shipped weight per SKU or per outbound shipment. Your outbound label data is often the best source.

Using billed weight as actual weight. Dimensional weight can be much larger than the real mass. Treat carrier weight as a soft signal unless you know which field you are reading.

Trusting event order. Webhooks arrive late, duplicated, or out of order. Sort by the carrier's event timestamp and dedupe on event ID.

Refunding inside the webhook transaction. If the refund call succeeds and the DB write fails, the retry can refund twice. Use an outbox pattern and an idempotency key on the payment request.

Hard-coding a single facility postal code. Large facilities may span several codes, and you may add 3PL locations later. Make the list configurable.

Testing it

Build a set of fixture event streams and run them through the evaluator in CI:

Clean return: all signals match.
Edited destination: the delivery postal code differs.
Decoy envelope: correct destination with a very low weight.
Out-of-order duplicates: DELIVERED arrives before IN_TRANSIT, twice.
Delivered, never received: no intake event after the timeout.

Assert both the findings and the resulting state. Then replay several months of your real historical returns through the evaluator in shadow mode. Use that run to tune thresholds before any of them can block a refund. The aim is to catch decoys without holding refunds for every customer who used a heavier box.

Detecting Mastercard 2-Series Cards: BIN Range Logic That Doesn't Break

Jarrod Wright — Fri, 23 Oct 2026 15:19:40 +0000

The bug that never shows up in your logs

Most card-brand detection code is old. Someone wrote if (/^5[1-5]/.test(pan)) return 'mastercard' years ago and it shipped. It still works for most cards. It also rejects a valid class of Mastercard numbers, and you will probably never see an error for it.

Since 2017, Mastercard has issued cards in the 222100–272099 range in addition to the classic 51–55 prefixes. If your checkout form, gateway plugin, fraud rules, or analytics pipeline classifies brands by leading digits, it needs to handle both ranges. For the business background, including the official range, the 2017 acceptance assessments, and an end-to-end test plan, see Mastercard 2-Series BINs: The Official Range, What the Fines Were & How to Test Your Checkout.

This article covers one narrow piece: the classification logic itself. It walks through how to write it, how it typically goes wrong, and how to test it so it can't regress.

Why this failure is silent

Trace the data flow for a card that starts with 2223:

The user types the number into the card field.
Client-side code runs Luhn, then brand detection.
Brand detection returns unknown.
The form shows "Invalid card number" and disables submit.
Nothing is sent to the server. There is no authorization request and no decline code. The processor dashboard shows nothing.

The same pattern repeats further down the stack. A fraud rule that treats unknown brand as high risk blocks the order. An analytics job that buckets cards by first digit puts these transactions in an "other" category. Each layer fails locally and reports nothing upstream.

That is why the fix has two parts: correct classification, and instrumentation on rejection paths.

Use numeric ranges, not regex

The 2-series range is a contiguous numeric interval. Regex is a poor fit for intervals, which is how most bugs get in. Compare the leading digits as an integer against explicit bounds instead.

type Brand = 'visa' | 'mastercard' | 'amex' | 'unknown';

interface PrefixRange {
  brand: Brand;
  length: number; // how many leading digits to compare
  min: number;
  max: number;    // inclusive
}

// Ordered most-specific first. Extend for the brands you accept.
const RANGES: PrefixRange[] = [
  { brand: 'mastercard', length: 4, min: 2221, max: 2720 },
  { brand: 'mastercard', length: 2, min: 51,   max: 55   },
  { brand: 'amex',       length: 2, min: 34,   max: 34   },
  { brand: 'amex',       length: 2, min: 37,   max: 37   },
  { brand: 'visa',       length: 1, min: 4,    max: 4    },
];

export function detectBrand(rawPan: string): Brand {
  const pan = rawPan.replace(/[\s-]/g, '');
  if (!/^\d+$/.test(pan)) return 'unknown';

  for (const r of RANGES) {
    if (pan.length < r.length) continue;
    const prefix = Number(pan.slice(0, r.length));
    if (prefix >= r.min && prefix <= r.max) return r.brand;
  }
  return 'unknown';
}

Note the 4-digit bounds. A 6-digit range of 222100–272099 is equivalent to a 4-digit range of 2221–2720, because every 6-digit value from 272000 to 272099 starts with 2720. Using four digits means the brand resolves earlier while the user is typing, so the card icon appears sooner.

The range table is data, not code. You can load it from config, version it, and review changes in a diff without parsing a regex in your head.

If you must use regex

Some form libraries only accept a pattern. The correct regex for 2221–2720 is:

^(222[1-9]|22[3-9]\d|2[3-6]\d{2}|27[01]\d|2720)

Combined with the classic range:

^(5[1-5]|222[1-9]|22[3-9]\d|2[3-6]\d{2}|27[01]\d|2720)

It is easy to get one alternation wrong here. That is the main argument for range comparison.

Common mistakes and how to catch them

Mistake	Symptom	How to catch it
`^5[1-5]` only	All 2-series cards rejected	Boundary test at 2221 and 2720
`^2[2-7]` (too broad)	Non-Mastercard numbers starting 22xx/27xx labeled Mastercard	Negative tests at 2220 and 2721
`^2[2-7][0-9]{2}` with an off-by-one	Either 2221 or 2720 misclassified	Explicit min/max boundary cases
Lexicographic string compare (`pan >= '2221'`)	`'3'` > `'2720'` is true, so unrelated prefixes match	Compare fixed-length numeric slices only
Brand derived from first digit in analytics	2-series counted as "other" or "airline"	Reconcile brand counts against processor reports
`unknown` brand mapped to decline in fraud rules	Valid cards blocked post-submit	Rule review plus a 2-series test transaction
BIN column stored as 6 digits	Lookups break after 8-digit BIN adoption	Schema check: BIN fields should hold 8 digits

The too-broad case matters. The prefix 22 is not Mastercard's alone. Other networks have been allocated ranges that start with 2. If your code labels anything starting with 22 as Mastercard, you will send the wrong brand to downstream systems. Match the exact interval.

Don't forget the 8-digit BIN change

The ISO/IEC 7812-1 standard extended the issuer identification number from six digits to eight, and card networks adopted it in 2022. Brand detection still works on the shorter 2- or 4-digit prefixes above. BIN lookup tables are a different matter. A table keyed on 6 digits can still resolve a brand, but it may return the wrong issuer, product, or country for an 8-digit range.

Check these:

Database columns and API fields that store a "BIN": are they at least 8 characters?
Lookup code: does it try 8 digits first, then fall back to 6?
Data retention: can you legally store 8 leading digits? PCI DSS guidance on truncation changed alongside 8-digit BINs. Confirm the current rules with your QSA before you widen a stored field.

Testing: generate boundary numbers instead of hardcoding them

Processor sandboxes publish 2-series test cards. Stripe's, for example, is 2223003122003222. Use them for integration tests against that processor. For unit tests on your own classifier, generate Luhn-valid numbers at each boundary so the suite covers the edges directly.

function luhnCheckDigit(partial: string): number {
  let sum = 0;
  // Walk right-to-left; the check digit will be appended, so
  // the rightmost digit of `partial` is doubled.
  for (let i = 0; i < partial.length; i++) {
    let d = Number(partial[partial.length - 1 - i]);
    if (i % 2 === 0) {
      d *= 2;
      if (d > 9) d -= 9;
    }
    sum += d;
  }
  return (10 - (sum % 10)) % 10;
}

function makePan(prefix: string, length = 16): string {
  const body = prefix.padEnd(length - 1, '0');
  return body + luhnCheckDigit(body);
}

describe('detectBrand: Mastercard 2-series boundaries', () => {
  const cases: [string, string][] = [
    ['2220', 'unknown'],     // just below range
    ['2221', 'mastercard'],  // lower bound
    ['2500', 'mastercard'],  // interior
    ['2720', 'mastercard'],  // upper bound
    ['2721', 'unknown'],     // just above range
    ['50',   'unknown'],
    ['51',   'mastercard'],
    ['55',   'mastercard'],
    ['56',   'unknown'],
  ];

  test.each(cases)('prefix %s -> %s', (prefix, expected) => {
    const pan = makePan(prefix);
    expect(isLuhnValid(pan)).toBe(true); // sanity check
    expect(detectBrand(pan)).toBe(expected);
  });

  test('known sandbox card', () => {
    expect(detectBrand('2223 0031 2200 3222')).toBe('mastercard');
  });
});

A 'unknown' expectation only holds if no other range in your table covers that prefix. If you add brands, update the negative cases.

For broader coverage, add a property-based test. Generate random integers in [2221, 2720], build Luhn-valid PANs, and assert they always classify as Mastercard. Then do the same just outside the bounds.

Test every layer that classifies

Unit tests only cover the function you wrote. List every component that reads leading digits and give each one its own check:

Client form or hosted fields: run the boundary cases in an end-to-end browser test that types each number and asserts submit is enabled.
Gateway plugin: if it does its own validation, test it separately. It may not call your function.
Server-side validation: the same boundary suite, run against the API.
Fraud and routing rules: feed a 2-series test PAN through rule evaluation and assert it isn't routed to unknown.
Analytics and reporting: assert that brand derivation in your ETL produces mastercard for a 2-series fixture.

The whole path still needs a real transaction in production. Sandbox and unit tests can't prove that your acquirer configuration accepts the card.

Instrument the rejection path

Because client-side rejections never reach a server, add a lightweight event:

if (brand === 'unknown' && isLuhnValid(pan)) {
  track('card_brand_unrecognized', {
    prefix4: pan.slice(0, 4), // never send the full PAN
    length: pan.length,
  });
}

A Luhn-valid number with an unrecognized brand is a strong signal that your range table is incomplete. Alert when this event's rate rises. Review your data-handling policy before logging any part of a PAN, and keep the prefix as short as is useful.

Checklist

[ ] Brand detection uses explicit numeric ranges, including 2221–2720
[ ] Boundary tests cover 2220, 2221, 2720, 2721, 50, 51, 55, 56
[ ] Gateway plugins and hosted fields tested independently
[ ] Fraud rules don't treat unknown brand as an automatic decline without review
[ ] BIN storage and lookup support 8 digits
[ ] Client-side rejections of Luhn-valid numbers are tracked
[ ] One live 2-series transaction has cleared through the full stack

Detecting Abnormal Keyed-Entry Rates from POS Entry Mode Data

Jarrod Wright — Wed, 14 Oct 2026 14:13:26 +0000

Every card authorization carries a small field that records how the card data reached the terminal: chip, contactless, magnetic stripe, fallback swipe, or typed in by hand. Most engineering teams never look at it. They should. A terminal or cashier that keys in far more sales than its peers usually points to a broken reader, a training gap, or someone deliberately bypassing the chip. Keyed sales also cost more and are harder to defend in disputes.

This article covers building a keyed-rate monitor: normalizing entry mode data, separating keyed-by-design traffic, scoring terminals and employees without drowning in small-sample noise, and triaging alerts. For the business side of why keyed sales cost more and how to document them, see Key-Entered Transactions: Why Manually Keyed Transactions Cost More & How to Reduce Them.

Where the signal lives

In ISO 8583-based messaging, the POS entry mode is carried in data element 22. Card networks define the values, and processors expose them in settlement files, reporting APIs, or webhook payloads, often renamed. Commonly seen values include:

Code	Meaning	Bucket
01	Manual key entry	`keyed`
05	Chip (contact EMV)	`chip`
07	Contactless chip	`contactless`
80	Chip failed, fell back to mag stripe	`fallback`
90	Full mag stripe read	`swipe`
91	Contactless mag stripe mode	`contactless`

Exact codes vary by network and processor, so build a mapping table rather than hard-coding them. Your processor's spec is the source of truth.

Two things matter for monitoring:

Keyed is the outcome you're measuring.
Fallback is the leading indicator. A chip reader that's dying usually produces fallback swipes before cashiers give up and start typing.

Step 1: Normalize into a clean fact table

Raw transaction feeds include refunds, voids, reversals, and declined attempts. Counting those inflates or distorts rates. Start with a view that keeps only approved sales and maps entry mode to a bucket.

CREATE VIEW sale_entry AS
SELECT
  t.txn_id,
  t.store_id,
  t.terminal_id,
  t.employee_id,
  t.channel,                 -- 'counter', 'moto', 'ecom'
  t.card_fingerprint,        -- processor token, never the PAN
  t.amount,
  t.created_at,
  COALESCE(m.bucket, 'unknown') AS entry_bucket
FROM transactions t
LEFT JOIN entry_mode_map m
  ON m.processor = t.processor
 AND m.raw_code  = t.entry_mode
WHERE t.txn_type = 'sale'
  AND t.status   = 'approved';

The LEFT JOIN plus 'unknown' matters. When a processor adds a new code or a firmware update starts sending blanks, you want those rows visible, not silently dropped.

Step 2: Exclude keyed-by-design traffic

Phone and mail orders are keyed every time. If a store's back-office terminal handles MOTO orders, it will dominate any keyed-rate ranking and hide the counter terminal that's actually broken.

Filter on channel, not on terminal ID. Terminal assignments change; channel flags (if your POS sets them correctly) travel with the transaction. Track MOTO volume as its own metric.

SELECT
  store_id,
  terminal_id,
  employee_id,
  COUNT(*)                                              AS n,
  COUNT(*) FILTER (WHERE entry_bucket = 'keyed')        AS keyed,
  COUNT(*) FILTER (WHERE entry_bucket = 'fallback')     AS fallback,
  COUNT(*) FILTER (WHERE entry_bucket = 'unknown')      AS unknown
FROM sale_entry
WHERE channel = 'counter'
  AND created_at >= now() - interval '14 days'
GROUP BY store_id, terminal_id, employee_id;

Roll this up separately by terminal and by employee. The two views answer different questions.

Step 3: Score without fooling yourself

The naive approach, ranking by keyed / n, fails immediately. A terminal with 2 keyed sales out of 40 shows 5%, while a busy one with 40 out of 900 shows 4.4%. The first looks worse but is almost certainly noise.

Use a confidence interval on the proportion and flag only when the lower bound exceeds the peer baseline. The Wilson score interval behaves well at small n and near zero, which is exactly where keyed rates live.

import math

def wilson_interval(k, n, z=1.96):
    if n == 0:
        return (0.0, 1.0)
    p = k / n
    denom = 1 + z * z / n
    center = (p + z * z / (2 * n)) / denom
    half = z * math.sqrt(p * (1 - p) / n + z * z / (4 * n * n)) / denom
    return center - half, center + half

def flag(k, n, baseline, min_n=30):
    if n < min_n:
        return False
    low, _ = wilson_interval(k, n)
    return low > baseline

Worked example

A store's counter terminals collectively key 1.5% of approved sales over 14 days. That's the baseline.

Terminal A: 40 keyed of 900. Raw rate 4.4%. Wilson 95% interval ≈ 3.3% to 6.0%. Lower bound 3.3% > 1.5%, so flag.
Terminal B: 2 keyed of 40. Raw rate 5.0%. Interval ≈ 1.4% to 16.5%. Lower bound 1.4% < 1.5%, so no flag yet.

Terminal B has the higher raw rate but not enough evidence. If it keeps keying at that pace, the interval tightens and it gets flagged within a week or two.

Choosing the baseline

Compare against a peer group, not a global number. A grocery store, a hardware store, and a bar have different card mixes and different damaged-card rates. Reasonable options:

Same store, other terminals (best for catching hardware faults)
Same store format across the chain (best for catching a whole store's habits)
The entity's own trailing 90 days (best for catching sudden change)

Run more than one. A terminal that's normal for its store but the store is 3x the chain baseline is a different problem than one bad terminal.

Step 4: Triage with the terminal × employee matrix

Once something is flagged, cross-reference both dimensions. The pattern usually tells you the cause before anyone visits the store.

Pattern	Likely cause	First action
One terminal high across all employees; fallback rose first	Failing or dirty chip reader	Swap or service the device
One terminal high across all employees; fallback normal	Reader disabled, misconfigured, or physically obstructed	Check terminal config and setup
One employee high across every terminal they use	Training gap or habit of skipping the chip	Retrain; review receipts and imprints
One employee high, keyed sales cluster on a few card fingerprints	Possible misuse of stolen card numbers	Escalate to loss prevention
Whole store high, all terminals and staff	Store-level practice, or MOTO traffic tagged as counter	Audit channel tagging, then store procedures
`unknown` bucket spikes	Processor code change or firmware bug	Update `entry_mode_map`; check release notes

The fallback-then-keyed sequence is worth automating. A simple rule: alert when a terminal's fallback rate crosses its threshold, even if keyed is still normal. That catches hardware decay early.

Step 5: Add card-level checks for keyed sales

Rates catch systemic problems. Some abuse only shows at the card level. Two cheap queries:

Multiple keyed sales on one card, same store, same day. This can indicate an improperly split purchase, which card network rules generally prohibit, or repeated use of a compromised number.

SELECT store_id, card_fingerprint, created_at::date AS day,
       COUNT(*) AS keyed_count, SUM(amount) AS total
FROM sale_entry
WHERE entry_bucket = 'keyed' AND channel = 'counter'
GROUP BY store_id, card_fingerprint, created_at::date
HAVING COUNT(*) >= 2;

Keyed sale on a card previously read by chip. If the same fingerprint was dipped successfully last week and keyed today, the card is probably fine. Today's keyed entry needs an explanation.

Both rely on a stable card fingerprint from your processor's tokenization. Never store or join on raw card numbers.

Common mistakes

Counting declines. A cashier who tries the chip three times and gets three declines before keying produces four rows. Only count approved sales, and track failed attempts separately if you want reader-health data.

Mixing channels. If MOTO traffic is mislabeled as counter, your top offender is a phone-order desk. Validate channel tagging before trusting any ranking.

Alerting on day-level data. Keyed sales are rare. Daily windows produce mostly noise. Use rolling 7 to 14 day windows with a minimum transaction count.

Ignoring shared logins. If employees share POS credentials, employee-level analysis is meaningless. Detecting a login used across simultaneous terminals is a useful data quality check on its own.

Treating every flag as fraud. Most high keyed rates come from hardware and training. Design the alert to route to operations first and loss prevention only when card-level signals point that way.

Logging sensitive fields. Keyed card-not-present flows often collect the card security code. PCI DSS prohibits storing it after authorization, including in debug logs, analytics events, or call recordings. Audit your pipeline so the monitor doesn't become a compliance problem.

Testing the monitor

Seed a staging dataset with known patterns: one terminal with elevated fallback followed by keyed, one employee keying across three terminals, a low-volume terminal with a high raw rate, and a batch of rows with an unmapped entry code. Assert that the first two flag, the third doesn't, and the fourth surfaces in the unknown metric. Run it whenever you change thresholds, baselines, or the mapping table.

The whole system is a view, a few aggregate queries, and a twenty-line scoring function. What makes it useful is the discipline around it: clean inputs, sensible peer groups, and a triage path that sends hardware problems to hardware people.

Building a VAMP Ratio Monitor: Merchant and Portfolio Math in Practice

Jarrod Wright — Tue, 13 Oct 2026 17:45:00 +0000

The Visa Acquirer Monitoring Program (VAMP) ratio fits on a napkin: fraud reports plus disputes, divided by transactions. It is easy to get the formula right and the number wrong. A monitor that is off by a few basis points can show an acquirer as safe when it is not.

This article walks through how to compute the ratio correctly. It covers the merchant-level calculation, the portfolio rollup, a what-if model for remediation, and the mistakes that most often corrupt the number. For the business context, including why acquirers now carry this risk and how little many merchants know about it, see The VAMP Awareness Gap: Financial Institutions Need to Know About Major Changes to Visa Disputes.

The formula and what each term means

VAMP ratio = (TC40 count + TC15 count) / settled transaction count

TC40: an issuer-reported fraud notification. It does not have to lead to a chargeback. The cardholder may say "that wasn't me" and the issuer files a TC40 even if no dispute follows.
TC15: a dispute (chargeback) notification.
Denominator: settled transactions for the period. VAMP focuses on card-not-present activity, so the denominator should match that scope. Check the current Visa rules for the exact definition rather than assuming.

The key detail: one fraudulent transaction that is also charged back counts twice. It produces one TC40 and one TC15. Nobody made a mistake. That is how the metric works, and a pipeline that deduplicates across the two types will understate the ratio.

Worked example: one merchant, one month

Event	TC40	TC15
40 fraud reports, no chargeback	40	0
60 fraud reports that became chargebacks	60	60
50 non-fraud disputes (e.g., item not received)	0	50
Total	100	110

With 20,000 settled CNP transactions, the ratio is 210 / 20,000 = 1.05%.

If you count unique problem transactions instead (150), you get 0.75%. That is a 30-basis-point understatement, enough to hide a merchant that is drifting toward trouble.

The portfolio rollup

Acquirers are measured on the whole portfolio, not on any single merchant. The portfolio ratio is a volume-weighted sum. It is not the average of the merchant ratios.

portfolio_ratio = SUM(tc40 + tc15) / SUM(settled_txns)

Worked example: four merchants

Merchant	Settled txns	Ratio	TC40+TC15
A (low-risk retail)	2,000,000	0.10%	2,000
B	500,000	0.30%	1,500
C (subscription)	300,000	1.20%	3,600
D (marketplace)	200,000	1.40%	2,800
Portfolio	3,000,000	0.33%	9,900

No merchant breaches the 1.5% merchant threshold. Yet the portfolio sits at 0.33%, above the 0.3% level that acquirer tiers can start at.

Merchants C and D account for 16.7% of volume but 64.6% of the counts. This concentration is the normal pattern, and your tooling should surface it directly.

Data model and pipeline

You need three feeds, each keyed to a merchant and a reporting period:

Settled transactions: merchant ID, settlement date, card-present/CNP flag, network.
TC40 records: merchant ID, report date, ARN (acquirer reference number), fraud type.
TC15 records: merchant ID, dispute date, ARN, reason code.

The pipeline flows like this:

raw feeds -> normalize merchant IDs -> dedupe within type -> bucket by period
          -> merchant_month aggregates -> portfolio_month aggregate -> alerts

Dedupe within a type, never across types

Network files sometimes resend the same record. Deduplicate TC40s against other TC40s, and TC15s against other TC15s, using the ARN plus a type-specific key. A TC40 and a TC15 that share an ARN are both legitimate counts.

WITH tc40 AS (
  SELECT DISTINCT ON (arn, fraud_report_id)
         merchant_id, date_trunc('month', report_date) AS period
  FROM raw_tc40
),
tc15 AS (
  SELECT DISTINCT ON (arn, dispute_case_id)
         merchant_id, date_trunc('month', dispute_date) AS period
  FROM raw_tc15
  WHERE NOT excluded_from_vamp   -- flag set per current Visa rules
),
counts AS (
  SELECT merchant_id, period, COUNT(*) AS n FROM tc40 GROUP BY 1, 2
  UNION ALL
  SELECT merchant_id, period, COUNT(*) FROM tc15 GROUP BY 1, 2
),
txns AS (
  SELECT merchant_id, date_trunc('month', settle_date) AS period,
         COUNT(*) AS settled
  FROM settlements
  WHERE network = 'VISA' AND channel = 'CNP'
  GROUP BY 1, 2
)
SELECT t.merchant_id, t.period, t.settled,
       COALESCE(SUM(c.n), 0) AS vamp_count,
       COALESCE(SUM(c.n), 0)::numeric / NULLIF(t.settled, 0) AS vamp_ratio
FROM txns t
LEFT JOIN counts c USING (merchant_id, period)
GROUP BY t.merchant_id, t.period, t.settled;

Note the excluded_from_vamp flag. Some dispute resolution paths may be treated differently under current rules. Put that logic in one place and keep it configurable. Do not hardcode it into the query.

Modeling remediation: marginal impact

The most useful question a risk team can ask is: "If we fix or exit merchant X, where does the portfolio land?"

def portfolio_without(merchants, exclude_id):
    rest = [m for m in merchants if m["id"] != exclude_id]
    count = sum(m["vamp_count"] for m in rest)
    txns = sum(m["settled"] for m in rest)
    return count / txns

def ranked_impact(merchants):
    base = sum(m["vamp_count"] for m in merchants) / sum(m["settled"] for m in merchants)
    return sorted(
        ((m["id"], base - portfolio_without(merchants, m["id"])) for m in merchants),
        key=lambda x: x[1], reverse=True,
    )

Applied to the example:

Removing D moves the portfolio from 0.33% to 7,100 / 2,800,000 = 0.254%.
Removing C gives 6,300 / 2,700,000 = 0.233%.

Removing merchant A would actually raise the ratio, because its clean volume dilutes everyone else's counts. Rank merchants by marginal impact, not by raw ratio. A small merchant with a terrible ratio may matter less than a mid-size one that is merely bad.

A more realistic model reduces a merchant's counts by an expected remediation rate instead of deleting the merchant. The same function works with adjusted counts.

Internal alert tiers

Visa's thresholds are a ceiling. Internal tiers give you time to act before you reach it. Keep every number in config, because the network adjusts thresholds over time.

merchant_tiers:
  watch:      { ratio: 0.0075, min_count: 100 }
  action:     { ratio: 0.0100, min_count: 300 }
  critical:   { ratio: 0.0130, min_count: 750 }
  visa_limit: { ratio: 0.0150, min_count: 1500 }
portfolio_tiers:
  watch:      { ratio: 0.0025 }
  action:     { ratio: 0.0030 }

Tier	Trigger	Typical response
Watch	Ratio and count over watch values, 1 month	Notify merchant, expose ratio in dashboard
Action	Over action values, or watch for 2+ months	Remediation plan, increased reserve or pricing review
Critical	Over critical values	Weekly review, volume caps
Visa limit	Over network threshold	Formal program handling; consider exit if no progress

The min_count gate matters. Without it, a merchant with 50 transactions and 2 disputes trips a 4% alarm every month and buries real signals. Visa applies a similar count minimum at the merchant level, so a ratio-only alert does not match how the program works.

Projecting mid-month

Waiting for month-end means alerting after the damage is done. Project forward instead.

def projected_ratio(count_mtd, settled_mtd, day, days_in_month, lag_factor=1.0):
    # lag_factor > 1 compensates for TC40/TC15 that arrive after the transaction
    return (count_mtd * lag_factor) / settled_mtd

Fraud reports and disputes trail the original transaction, often by weeks. Early in the month the counts look artificially low. Calibrate lag_factor per merchant category from your own history: compare day-N counts to the final monthly count across past periods.

Common mistakes and how to catch them

1. Deduping across TC40 and TC15. Write a test fixture with a single fraud chargeback and assert that it counts as 2.

2. Wrong denominator. Including card-present transactions, other networks, or authorizations instead of settlements all inflate the denominator and deflate the ratio. Reconcile your settled-transaction count against acquirer settlement reports every month.

3. Averaging ratios. AVG(vamp_ratio) across merchants is meaningless at portfolio level. Add a test where one large clean merchant and one small dirty merchant produce different weighted and unweighted results, and assert you return the weighted one.

4. Merchant ID fragmentation. One business with several MIDs can look healthy across each MID individually. Maintain a merchant-entity mapping and compute ratios at both levels.

5. Period misalignment. Counts are bucketed by report date, while transactions are bucketed by settlement date. That mismatch is inherent to the metric, but your periods must use the same timezone and cutoff as the network's reporting. Off-by-one-day bucketing at month boundaries is a frequent source of discrepancies.

6. Silent feed gaps. A missing TC40 file produces a beautiful ratio. Alert on volume anomalies in the inputs, such as zero records for a merchant that normally has dozens, before trusting the output.

Testing checklist

Fraud chargeback counts as 2
Duplicate TC40 resent in a later file counts as 1
Card-present transactions are excluded from the denominator
Portfolio ratio equals the summed numerator over the summed denominator
Merchants below min_count never raise merchant-tier alerts
Excluded dispute paths are removed only via the config flag
Reconciliation diff against the network's monthly figures stays within tolerance

The formula is trivial. The value is in matching the network's definitions exactly and getting the number early enough to act on it.

Designing Account Holds for Chargebacks

Jarrod Wright — Tue, 13 Oct 2026 15:09:57 +0000

A State Machine for Digital Goods

When a bank reverses a payment for a digital purchase, your system has to decide what happens to the account that made it. Most platforms treat that as a binary choice: do nothing, or lock the account. Sony's handling on PlayStation Network is a well-known example of the second option. A reversed PlayStation Store charge suspends the account, the player sees error WS-37368-7 at sign-in, and access comes back once the debt is repaid. The policy, and how players have reacted to it, is covered in PlayStation Chargebacks: Sony's Chargeback Policy & the Hard Choices Behind the Ruleset.

The interesting engineering problem is the one that article raises near the end. A single dispute event can come from three very different customers. If your system treats all three the same way, you either leak revenue or punish fraud victims. This post walks through modeling that difference in code.

The three customers behind one webhook

Your payment processor sends you the same event in every case (Stripe, for example, emits charge.dispute.created). Behind it is one of these people:

The friendly fraudster. They made the purchase, used it, and disputed it anyway.
The account takeover victim. Someone else got into the account and spent on the stored card.
The false positive. The issuer's fraud system flagged a legitimate order without the cardholder asking.

Only the first should end in a debt hold. The second needs account recovery. The third needs the order defended and the customer left alone.

Model account access as a state machine

Instead of a boolean is_banned, give accounts explicit states with defined transitions:

ACTIVE        --dispute received------------------> UNDER_REVIEW
UNDER_REVIEW  --takeover signals------------------> RECOVERY
UNDER_REVIEW  --issuer-initiated, low risk--------> ACTIVE   (defend the charge, no customer impact)
UNDER_REVIEW  --friendly fraud signals------------> DEBT_HOLD
DEBT_HOLD     --balance repaid--------------------> ACTIVE
DEBT_HOLD     --dispute resolved for merchant-----> ACTIVE
RECOVERY      --credentials reset and verified----> ACTIVE

The key design choice is making UNDER_REVIEW a real state with its own permissions. A reasonable default: the customer can sign in and use content they already own, but can't make new purchases or move stored value until the review finishes. That limits further exposure without locking a possible victim out of their library on day one.

Classifying the dispute

The routing decision out of UNDER_REVIEW comes from signals you almost certainly already collect.

Signals that point to account takeover

Password, email, or 2FA changed shortly before the disputed purchases
A new device or new IP region at the time of purchase
A purchase pattern unlike the account's history, such as bulk wallet top-ups or items that resell easily
The customer contacted support about unauthorized activity before or alongside the dispute

Signals that point to friendly fraud

The purchase came from the account's established device and location
The content was downloaded and used after purchase (playtime, consumption logs)
Prior disputes on the same account or card
The customer never contacted support first

Signals that point to an issuer false positive

A fraud reason code with no customer contact on your side
A long, clean account history and normal purchase behavior

The reason code helps but doesn't decide the outcome. Fraud-category codes like Visa 10.4 and Mastercard 4837 cover both real takeovers and friendly fraud, so consumption and device evidence carry most of the weight.

A minimal implementation

def route_dispute(account, dispute, signals):
    if signals.recent_credential_change or signals.new_device_at_purchase:
        return "RECOVERY"
    if signals.content_consumed and signals.known_device and not signals.support_contact:
        return "DEBT_HOLD"
    if account.prior_disputes == 0 and account.age_days > 365:
        return "ACTIVE"        # defend the charge, leave the customer alone
    return "UNDER_REVIEW"      # ambiguous: send to a human

Keep the thresholds in config, log every transition along with the signals that drove it, and send ambiguous cases to a person. A wrong DEBT_HOLD means a fraud victim locked out of games they paid for, which is exactly the outcome that generates angry forum threads.

Edge cases worth handling

Recurring billing during a hold. Sony doesn't bill suspended accounts, so a PlayStation Plus renewal simply lapses. Decide explicitly whether subscriptions pause, lapse, or keep billing, and tell the customer which.
Family and child accounts. A parent disputing a child's purchase is common. Check for linked accounts and spending limits before you classify anything.
Dispute outcome events. When a dispute is won or lost, your processor sends another event. Wire it to your transitions so holds lift automatically instead of waiting on a support ticket.
Communication. Show a specific message and a clear path back (pay the balance, verify identity, or contact support) instead of a bare error code.

The takeaway

An account lockout changes what a customer stands to lose. It doesn't recover the money, and it doesn't prevent the next dispute. Treat the lockout as one possible output of a classification step rather than the default response to every chargeback, and your system can protect revenue without punishing the people fraud already hurt.