Skip to main content

Velocity Checks

Velocity checks are configurable security measures that help prevent potentially fraudulent transaction patterns. When implemented at the Tenant level, these checks can identify and block suspicious activity before it results in financial loss.

Common Use Cases​

Velocity Checks can detect patterns such as:

  • A card being tapped repeatedly within a short time period.
  • Multiple declined transactions from the same card.
  • Unusual transaction frequency for a specific terminal or merchant.

These patterns often indicate fraudulent activity and pose risks to both merchants and cardholders.

Configuring Velocity Check Thresholds​

A Velocity Check Threshold defines the specific parameters that trigger a security alert:

  • Pattern: The type of activity being monitored (e.g., card taps, declined transactions).
  • Frequency: How many times the activity can occur within a defined time period.
  • Time Window: The period during which occurrences are counted (e.g., 5 minutes, 24 hours).

For example, a threshold might be configured to detect "2 card taps in a 5-minute period" or "3 declined transactions from the same card within 10 minutes."

Velocity Check Thresholds can be configured using the create and update APIs.

For additional threshold management operations, see the complete Velocity Checks API documentation.

Understanding Velocity Check Breaches​

When a transaction pattern matches the criteria defined in a Velocity Check Threshold, it creates a "breach." Breaches are the system's way of flagging potentially suspicious activity.

Breach Notifications​

Breaches are communicated to Tenants through a Velocity Check breach webhook. Each breach notification includes:

  • A cardFingerprint - a unique hash of the card PAN generated by a Hardware Security Module (HSM).
  • The threshold that was breached.
  • Additional context about the breach.

Breach Statuses​

A breach notification will indicate one of three statuses:

  • Active breach - The threshold has been exceeded and includes an expiration time.
  • Expired breach - The previously active breach has reached its expiration time.
  • Cancelled breach - The breach was manually cancelled or automatically cancelled due to threshold changes.

Managing Breaches​

Active breaches for a particular cardFingerprint can be manually cancelled using the clear breach API operation. This might be appropriate after investigating and confirming that the flagged activity is legitimate.

Breaches are also automatically cancelled if you update or delete the associated Velocity Check Threshold.