--- title: Velocity controls slug: concepts/cards/issuing-models/integrated-issuing/issuer-processor/velocity-controls docTags: createdAt: 2026-03-16T09:41:44.421Z --- # 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](docId\:r_Cxcl0l2UoyWkuuJpaJ1) [GET /v1/cards/\{cardId}/controls](docId\:AT16WGXZGoV5cqFuFNPTP) ## 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:** :::BlockQuote \{ "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: - ATM - Over the counter bank branch withdrawals ## Action types ### ALLOW (whitelist) **Behavior:** Transactions are allowed UP TO the specified limits **Example:** :::BlockQuote \{ "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: :::BlockQuote \{ "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: :::BlockQuote \{ "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: :::BlockQuote \{ "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: :::BlockQuote \{ "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: :::BlockQuote \{ "type": "ecomm", "action": "ALLOW", "list": \[ \{ "period": "WEEK", "amount": 20000, "usage\_limit": null } ] } ::: **Example 6: combined transaction types** Separate limits for POS and e-commerce: :::BlockQuote \{ "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:** 1. Delete the velocity control 2. 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 1. Account level authorization controls (set by issuer) 2. Card level authorization controls (set by issuer/partner) 3. Account level velocity controls (set by issuer/partner as defaults) 4. 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** :::BlockQuote \{ "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** :::BlockQuote \{ "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** :::BlockQuote \{ "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** :::BlockQuote \{ "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** :::BlockQuote \{ "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: :::BlockQuote \{ "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: :::BlockQuote \{ "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: :::BlockQuote \{ "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: :::BlockQuote \{ "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: :::BlockQuote \{ "type": "pos", "cashback": "ALLOW" // Include cashback in velocity limit } ::: Or exclude cashback from limits: :::BlockQuote \{ "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: :::BlockQuote \{ "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** 1. Verify you set the control at the correct hierarchy level (account or card) 2. Check action is ALLOW not DENY 3. 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