Velocity Thresholds
2 min read
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 90-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:
- Compute the fingerprint from the request
- Count declines and submissions from this fingerprint within the last 60 seconds
- If either count exceeds its threshold, set the lockout flag with a 90-second expiry
- 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 → Card-Testing Defense. Changes take effect immediately — no cache to flush, no scheduled job to run.
| Setting | Range | Description |
|---|---|---|
| 60-second decline threshold | 1–100 (default 3) | Declines per fingerprint within 60s that trigger lockout |
| 60-second submission threshold | 1–200 (default 10) | Total submissions per fingerprint within 60s that trigger lockout |
The lockout duration itself isn’t a configurable setting — a tripped fingerprint is held for a fixed 90 seconds. What you tune here is how many declines or submissions it takes to trip that lockout.
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 Defense → 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.
