Velocity controls

What velocity controls do

Overview

Use velocity controls as card-level spending limits and budget management tools. They enable your customers (cardholders) to set their own spending restrictions. Velocity controls allow cardholders to:

Set personal spending budgets (daily, weekly, monthly, yearly, lifetime)

Control their own transaction frequency (maximum number of transactions)

Use general spending limits across all transaction types OR set different limits per type (POS, e-commerce, ATM)

Self-service spending control without requiring issuer intervention

Who Sets Controls:

Cardholders/end users: Set card-level controls for their own spending management

Partners (via API): Can programmatically set controls for their customers cards

Issuers: May set account-level defaults or maximums

Secondary benefit: Velocity controls also provide fraud mitigation by limiting the potential loss if a card is compromised.

Core function

Primary purpose: Spending control and budget management.

Secondary purpose: Limit fraud exposure by capping potential losses.

How it works:

Tracks cumulative transaction amounts over defined time periods

Counts transaction frequency (usage limits)

Automatically declines transactions that exceed configured spending limits

Resets counters based on period definitions (rolling or fixed windows)

API endpoints

For a full description of the APIs used to configure velocityControls refer to the following API endpoints:

PUT /v1/cards/{cardId}/controls

GET /v1/cards/{cardId}/controls

Control types

Velocity controls support five transaction types:

1. General spend

Description: Overall card spending limit across all transaction types.

Characteristics:

Applies to ALL enums transaction types (POS, e-commerce, general_spend, withdrawals)

Single spending limit regardless of how the card is used

Simplest control type for basic spending limits

Use case: Set a total daily/monthly spending limit without distinguishing between POS, online, or ATM usage.

Example:

{ "type": "general_spend", "action": "ALLOW", "list": [ { "period": "DAY", "amount": 100000, "usage_limit": 10 } ] }

Result: Card can spend up to $1,000/day across any combination of POS, e-commerce or ATM transactions.

2. POS (Point of Sale)

Description: Card-present transactions at physical terminals.

Characteristics:

Physical card swipe, chip, or contactless payment

Only control type supporting the cashback parameter

Cashback setting controls whether cashback amounts are included in velocity limit calculations

cashback: "ALLOW" includes cashback in spending limit

cashback: "DENY" excludes cashback from spending limit

3. E-commerce (ecomm)

Description: Card-not-present online purchases.

Characteristics:

Online shopping, mobile app purchases

Remote/digital transactions

No physical card presentation

4. Withdrawal

Description: Cash withdrawals at ATMs and bank branches.

Characteristics:

ATM cash withdrawals

Over-the-counter cash advances

Balance inquiries and PIN changes are exempt

How withdrawal limits work

There is a combined withdrawal pool. All cash withdrawals transactions contribute to the same velocity limit, regardless of the type of cash withdrawals, such as:

Over the counter bank branch withdrawals

Action types

ALLOW (whitelist)

Behavior: Transactions are allowed UP TO the specified limits

Example:

{ "type": "pos", "action": "ALLOW", "list": [{"period": "DAY", "amount": 50000}] }

Result: Allows up to $500/day, declines any transaction that would exceed this limit.

DENY (blacklist)

Behavior: Blocks transaction types that exceed specified limits

Use Case: Less common for velocity controls, more useful for authorization controls

Period types

Velocity controls can be set for five time periods:

Period	Description	Behavior
DAY	24-hour rolling	Rolling 24-hour window from current time
WEEK	7-day rolling	Rolling 7-day window from current time
MONTH	Monthly threshold	Calendar month or rolling 30-day period
YEAR	Annual spending cap	Calendar year or rolling 365-day period
TOTAL	Lifetime/card limit	Cumulative since card activation or control creation

Rolling windows: Most periods use rolling time windows (e.g., last 24 hours, last 7 days)

Limit parameters

Currency handling in velocity controls: Velocity control limits always use the account currency, which is the currency in which you hold the card account.

Key principle: Visa and Mastercard convert all transaction amounts to the account currency.

This applies to the amount and cashback fields below.

Attribute name	Information
amount	Description: Maximum cumulative transaction amount allowed within the period. Tracks sum of all approved transactions in the period Automatically declines when limit is reached Resets based on period type Examples: $500.00 = 50000 €100.00 = 10000 £250.50 = 25050
usage_limit	Description: Maximum number of transactions allowed within the period. Example: Allow max 5 transactions per day regardless of amount Purpose: Block high-frequency fraud attempts, even when each transaction is small. Behavior: Counts all approved transactions in the period Automatically declines when count is reached Can be combined with amount limits
cashback	Description: Controls whether cashback amounts are included in velocity control amount calculations. Availability: POS transactions only Behavior: "ALLOW" - Cashback amount is included in the velocity control limit calculation "DENY" - Cashback amount is excluded from the velocity control limit calculation Important: This setting does NOT deny cashback transactions. It only determines whether cashback amounts count toward the spending limit. Default: If not specified, cashback behavior follows card defaults Example: POS transaction: $50.00 purchase + $20.00 cashback = $70.00 total If cashback: "ALLOW" → velocity control tracks $70.00 If cashback: "DENY" → velocity control tracks $50.00 only

Configuration examples

Example 1: Daily spending limit

Restrict POS transactions to $500 per day:

{ "type": "pos", "action": "ALLOW", "list": [ { "period": "DAY", "amount": 50000, "usage_limit": null } ], "cashback": "DENY" }

Example 2: multi-period limits

Daily $500 limit AND lifetime $1000 limit:

{ "type": "pos", "action": "ALLOW", "list": [ { "period": "DAY", "amount": 50000, "usage_limit": null }, { "period": "TOTAL", "amount": 100000, "usage_limit": null } ], "cashback": "ALLOW" }

Behavior: Both limits must pass for approval. Card stops working after $1000 total spend, regardless of remaining daily limit.

Example 3: transaction frequency limit

Maximum 5 POS transactions per day, up to $500:

{ "type": "pos", "action": "ALLOW", "list": [ { "period": "DAY", "amount": 50000, "usage_limit": 5 } ] }

Behavior: Declines after 5 transactions OR $500 total, whichever comes first.

Example 4: ATM withdrawal limits

Restrict ATM withdrawals to $200 per day, $1000 per month:

{ "type": "withdrawal", "action": "ALLOW", "list": [ { "period": "DAY", "amount": 20000, "usage_limit": 3 }, { "period": "MONTH", "amount": 100000, "usage_limit": null } ] }

Example 5: E-commerce controls

Limit online purchases to $200 per week:

{ "type": "ecomm", "action": "ALLOW", "list": [ { "period": "WEEK", "amount": 20000, "usage_limit": null } ] }

Example 6: combined transaction types

Separate limits for POS and e-commerce:

{ "velocityControls": [ { "type": "pos", "action": "ALLOW", "list": [ { "period": "DAY", "amount": 100000, "usage_limit": 10 } ], "cashback": "ALLOW" }, { "type": "ecomm", "action": "ALLOW", "list": [ { "period": "DAY", "amount": 50000, "usage_limit": 5 } ] } ] }

Transaction processing

MTI messages that trigger velocity controls

Increase counters:

0100 - Authorization Request

0200 - Financial Authorization Request

0120 - Authorization Advice (approved transactions only)

Decrease counters (reversals):

0400 - Reversal

0420 - Reversal Advice

Approval requirement:

Only transactions with DE 39 = 00 (approved) increment counters

Only approved transactions count toward limits

Exemptions

ATM withdrawal controls exempt:

Balance inquiries

PIN changes

Mini statements

Other non-cash ATM transactions

Counter reset behavior

Automatic resets

DAY: Rolling 24-hour window, continuous reset

WEEK: Rolling 7-day window, continuous reset

MONTH: Reset at month boundary or rolling 30 days

YEAR: Reset at year boundary or rolling 365 days

TOTAL: Never resets automatically

Manual reset

To reset spend counter:

Delete the velocity control

Recreate the velocity control

Note: This is the only way to reset TOTAL period counters.

Control hierarchy

Velocity controls work alongside authorization controls:

Evaluation order

Account level authorization controls (set by issuer)

Card level authorization controls (set by issuer/partner)

Account level velocity controls (set by issuer/partner as defaults)

Card level velocity controls (set by cardholder/end user)

All controls must pass for transaction approval.

Control management

Account level: Typically set by issuer or partner as program-wide defaults

Card level: Set by individual cardholders through partner's application or API

Self-service: End users can update their own card-level velocity controls in real-time

Use cases

Basic consumer card - general spending limit

{ "velocityControls": [ { "type": "general_spend", "action": "ALLOW", "list": [ {"period": "DAY", "amount": 50000}, {"period": "MONTH", "amount": 300000} ] } ] }

Purpose: Simple daily and monthly spending limits across all transaction types Who sets: End user through partner's mobile app Result: $500/day and $3,000/month total spending regardless of POS, e-commerce, or ATM usage

Consumer self-service spending control

{ "velocityControls": [ { "type": "ecomm", "action": "ALLOW", "list": [ {"period": "DAY", "amount": 20000}, {"period": "MONTH", "amount": 100000} ] } ] }

Purpose: Cardholder sets their own online shopping limit: $200/day, $1,000/month Who sets: End user through partner's mobile app or web portal

Fleet card - driver-set daily limit

{ "velocityControls": [ { "type": "pos", "action": "ALLOW", "list": [{"period": "DAY", "amount": 15000}], "cashback": "DENY" } ] }

Purpose: Fleet driver sets their own daily fuel spending limit of $150. Who sets: Driver through fleet management app or fleet manager sets for driver.

Wholesale travel agency - B2B supplier payments

{ "velocityControls": [ { "type": "general_spend", "action": "ALLOW", "list": [ {"period": "DAY", "amount": 10000000}, {"period": "MONTH", "amount": 500000000} ] } ] }

Purpose: Travel agency virtual card for paying travel suppliers (airlines, hotels). Who sets: Travel agency or platform (requires wholesale program enrollment). Use case: OTA or TMC using virtual cards to pay third-party travel suppliers under special commercial agreement with Visa/Mastercard and Cross River.

Teen debit card - self-set limits

{ "velocityControls": [ { "type": "pos", "action": "ALLOW", "list": [ {"period": "DAY", "amount": 5000, "usage_limit": 3} ], "cashback": "DENY" }, { "type": "withdrawal", "action": "ALLOW", "list": [ {"period": "DAY", "amount": 2000, "usage_limit": 1} ] } ] }

Purpose: Teen (or parent) sets their own daily spending limit of $50 (max 3 purchases) and $20 ATM limit (1 withdrawal/day). Who sets: Cardholder through mobile app or parent through parental control interface.

Best practices

1. Layer multiple periods

Combine daily, monthly, and lifetime limits for comprehensive spending control:

{ "list": [ {"period": "DAY", "amount": 50000}, {"period": "MONTH", "amount": 150000}, {"period": "TOTAL", "amount": 500000} ] }

Use Case: Employee expense cards with daily, monthly, and annual budgets.

2. Use transaction frequency limits

Add usage_limit to control spending patterns and reduce fraud exposure:

{ "period": "DAY", "amount": 50000, "usage_limit": 10 }

Use case: Prevent excessive transaction activity even within spending limits.

3. Choose between general vs specific controls

Option A - Simple general limit:

{ "type": "general_spend", "action": "ALLOW", "list": [{"period": "DAY", "amount": 100000}] }

Use case: Basic consumer cards where transaction type doesn't matter.

Option B - Separate transaction type limits:

{ "velocityControls": [ {"type": "pos", "action": "ALLOW", "list": [{"period": "DAY", "amount": 50000}]}, {"type": "ecomm", "action": "ALLOW", "list": [{"period": "DAY", "amount": 30000}]}, {"type": "withdrawal", "action": "ALLOW", "list": [{"period": "DAY", "amount": 20000}]} ] }

Use case: Advanced controls where spending patterns differ by channel (e.g., fleet cards, corporate cards).

4. Control cashback calculation

For POS controls, explicitly set whether cashback counts toward limits:

{ "type": "pos", "cashback": "ALLOW" // Include cashback in velocity limit }

Or exclude cashback from limits:

{ "type": "pos", "cashback": "DENY" // Exclude cashback from velocity limit }

Use case: Set cashback: "DENY" when you want to allow cashback without it counting toward daily/weekly spending limits.

5. Set appropriate ATM withdrawal limits

Control cash access with daily and frequency limits:

{ "type": "withdrawal", "action": "ALLOW", "list": [ {"period": "DAY", "amount": 20000, "usage_limit": 2} ] }

Use case: Limit cash exposure and provide budget control for ATM usage.

Limitations & constraints

Control scope

Applies to authorization messages (0100, 0200, 0120)

Applies to reversals (0400, 0420)

Does NOT apply to clearing messages (0220)

Period constraints

Maximum list items per control: Check with Cross River P1

TOTAL period never auto-resets (requires manual deletion/recreation)

Transaction types

Cashback: Only available for POS type

Withdrawal: Excludes balance inquiries and PIN changes

Counter behavior

Counters increment only for approved transactions (DE 39 = 00)

Reversals decrement counters

Manual reset requires control deletion and recreation

Troubleshooting

Control not working

Verify you set the control at the correct hierarchy level (account or card)

Check action is ALLOW not DENY

Confirm transaction type matches control type

Counter not resetting

Rolling periods reset automatically

TOTAL period requires manual reset (delete + recreate)

Cashback amount not counted in velocity control

Verify you set cashback: "ALLOW" to include cashback in velocity limit calculations

Set cashback: "DENY" to exclude cashback from velocity limit calculations

Confirm control type is pos (only type supporting cashback parameter)

Note: This setting does NOT block cashback transactions, only controls whether cashback counts toward spending limits