Velocity Spend Rules

Spend rules that determine how much a card can spend in certain intervals.

Velocity rules allow you to set your own limits on how much a card can spend in specified time intervals. You can use them to configure logic like setting a maximum daily limit for cards, or in more complex use cases, setting merchant-specific limits like only allowing $100 in spend per month at Grocery Stores.

To create a Velocity rule, create a Spend Rule with the type "velocity".

General Principles

Velocity Rule Cycles

For Velocity Spend Rules, the main thing you have to think about are cycles - these are the time intervals that the rules are set against. There are 5 velocity cycles, each with their own reset criteria:

• all_time: This interval never resets - an all_time velocity rule means the card can never spend more than the associated VelocityValue.
• monthly: This is based on calendar month, where the interval resets on the 1st day of the calendar month at 00:00:00 in Pacific Time.
• weekly: This is based on the calendar week, where the interval resets every Monday at 00:00:00 in Pacific Time
• daily: This is based on the calendar day, where the interval resets every morning at 00:00:00 in Pacific Time
• single_transaction: The interval resets for every new transaction, so this cycle is basically just setting a spend limit on each individual transaction.

Note our use of calendar months for counting cycle intervals instead of using time-elapsed windows: we've found that this is far easier to explain to cardholders, and is much more predictable.

Velocity Rule Types

Currently, there is a VelocityType field on the SpendRule and the Restriction that is uneditable: at present, all velocity spend rules are of the velocity type "currency_amount" (i.e. the rule restrictions match based on the currency amount of a transaction in that cycle). In future, there will be other types of velocity rules, like "transaction_count", where the rule restrictions can match based on the number of unique transaction attempts in that cycle instead.

Velocity Rule Restrictions

Restrictions on Velocity Spend Rules work similarly to how they do for Merchant Spend Rules, with the difference being the fields we leverage. With velocity spend rules, the fields of importance would be: velocityValue and velocityCycle.

For example, If you wanted to set a card's maximum daily spending limit to be $100, you would set velocityValue: "100", and velocityCycle: "daily".

Examples

Example 1: Let's assume you have a commercial expense program and you're setting your velocity limits.

We'll need to call CreateSpendRuleV1 with the following:

JSON

{
	"name": "Commercial Expense Velocity Limits",
	"description": "This rule sets the spend limits for our commercial expense program",
	"type": "velocity",
	"applyTo": "program",
  "programId": "33c315e1-b20f-4d3c-beb6-07ac661121f9", // substitute with real programId
	"restrictions": [
		{
		  "type": "velocity",
		  "velocityValue": "2500",
  		"velocityCycle": "monthly"
		},
		{
		  "type": "velocity",
		  "velocityValue": "1000",
  		"velocityCycle": "weekly"
		},
		{
		  "type": "velocity",
		  "velocityValue": "500",
  		"velocityCycle": "daily"
		},
		{
		  "type": "velocity",
		  "velocityValue": "50",
  		"velocityCycle": "single_transaction"
		}
	]
}

Example 2: Let's say you have a more interesting use case: you want to limit spend to no more than $500 a month at ATMs or florists (i.e. the combined total of spend at either of those merchants cannot exceed $500/m). That's possible too! Note that in this case, the card has no limits at everywhere else - if you wanted to ensure that the cards also only worked at ATMs and Florists, pair this with a separate merchant_allow rule!

JSON

{
	"name": "Monthly ATM limit",
	"description": "This card can't spend more than $500/m at an ATM OR florists",
	"type": "velocity",
	"applyTo": "business",
  "velocityCycle": "monthly",
  "velocityValue": "500",
	"restrictions": [
		{
		  "type": "merchant_category",
  		"value": "AUTOMATED_CASH_DISBURSE"
		},
    {
		  "type": "merchant_category",
  		"value": "FLORISTS"
		}
	]
}

Example 3: Let's say you want to limit velocity with different amounts at different merchants. This sets the monthly limit to $500 at most merchants, except ATMs for which the limit is $150, and Florists for which it is $200.

JSON

{
	"name": "Monthly Merchant Velocity Limits",
	"description": "This sets our spend limits at different merchants",
	"type": "velocity",
	"applyTo": "business",
	"restrictions": [
		{
		  "type": "merchant_category",
  		"value": "AUTOMATED_CASH_DISBURSE",
      "velocityCycle": "monthly",
  		"velocityValue": "150"
		},
    {
		  "type": "merchant_category",
  		"value": "FLORISTS",
      "velocityCycle": "monthly",
  		"velocityValue": "200"
		},
    {
      "velocityCycle": "monthly",
  		"velocityValue": "500"
		}
	]
}