DEV Community: Jarrod Wright

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.