Velocity Thresholds

Velocity thresholds are the numbers TrustLens uses to decide when a stream of declines from a single device fingerprint has crossed the line from “legitimate customer with bad cards” into “automated card-testing attack.” This page explains how the thresholds work, why the defaults are what they are, and how to tune them for your store.

---

The Velocity Window #

The base Card-Testing Defense module runs a single 60-second rolling window with two thresholds:

Counter	Default	Designed to Catch
60-second declines per fingerprint	3	Bursts of failed authorization attempts — the classic card-testing signature
60-second submissions per fingerprint	10	High overall checkout-submission volume from one fingerprint, even when many succeed

Either threshold being crossed triggers a 60-second lockout on the offending fingerprint. The two counters together catch both pure-decline bursts and high-volume submission bursts that mix successes with failures.

Attack-scale protection — catching attacks that spread across many fingerprints over a longer window — ships as Pro auto-escalation, which watches for distinct-fingerprint diversity in a 10-minute window and triggers Panic Freeze. See Auto-Escalation (Pro).

---

How Counts Are Accumulated #

Counters are keyed by device fingerprint, not by IP or by email. The Velocity Recorder runs on every authorization attempt:

1. Compute the fingerprint from the request
2. Count declines and submissions from this fingerprint within the last 60 seconds
3. If either count exceeds its threshold, set the lockout flag with a 60-second expiry
4. Persist the velocity event so future requests can read aggregated counts

Counts use a rolling 60-second window — only events from the last 60 seconds contribute. As time advances, older events drop out of the window naturally.

---

Default Threshold Rationale #

The default 3-decline / 60-second threshold was chosen against observed real-world patterns:

• Legitimate customer: 1–2 attempts to enter a card correctly, finishing within 30 seconds. Under the threshold.
• Worst-case slow customer: 2 attempts over a minute (entering wrong card, then correct one). Still under threshold.
• Burst-attack bot: many declines per second. Triggers the threshold within the first second.

The 3-decline default is tight — it catches attacks fast at the cost of occasional false positives on customers who genuinely fumble cards three times. The VIP bypass mitigates this for known-good customers; the allowlists (Pro) mitigate it for known-good devices.

---

When to Tighten Thresholds #

Lower the defaults if:

• You’ve observed an attack that slipped through at the default settings
• Your store has a very stable customer base with predictable checkout behavior
• Your payment gateway is reliable (declines are signal, not noise)

Reasonable tightened values:

Setting	Default	Aggressive
60-second decline threshold	3	2
60-second submission threshold	10	6

---

When to Loosen Thresholds #

Raise the defaults if:

• Your gateway is unreliable and produces legitimate decline noise
• You have high-frequency legitimate retry behavior (saved cards, B2B with multiple card attempts)
• You’ve observed false-positive lockouts on real customers

Reasonable loosened values:

Setting	Default	Loose
60-second decline threshold	3	5
60-second submission threshold	10	15

---

Configuring #

Settings live at TrustLens → Settings → Modules → Card Testing. Changes take effect immediately — no cache to flush, no scheduled job to run.

Setting	Range	Description
60-second decline threshold	1–20	Declines per fingerprint within 60s that trigger lockout
60-second submission threshold	3–50	Total submissions per fingerprint within 60s that trigger lockout
Lockout duration	30–600 seconds	How long the fingerprint stays blocked

---

Per-Fingerprint Overrides (Pro) #

Pro adds per-fingerprint threshold overrides. Useful when you have:

• A specific known device that legitimately produces high velocity (a test rig, an integration partner’s server)
• A device you want to enforce more strictly than the global default

Overrides are configured under TrustLens → Card Testing → Allowlists → Fingerprint Overrides.

---

Measuring Effectiveness #

After tuning, monitor:

• Card Testing dashboard widget — recent decline events and lockout count
• Customer complaints — false-positive lockouts produce complaints about “checkout error” or “card declined” on cards that work elsewhere
• Pro Attack History tab — 24-hour decline count trend; spikes indicate attacks slipping through; flatlines indicate stable defense

If you tune thresholds, give the change at least a week before re-evaluating — attack patterns aren’t daily.