DEV Community: Chargebacks911

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.