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 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 { "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 { "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