Velocity Controls

Velocity Control

A velocity control limits how much users can spend. You can configure velocity controls to limit how much users can spend and the number of transactions they can make in a given span of time. You can apply velocity controls to a single user, to all users associated with a particular card product, or to all users in your program. Only Program Managers can create or modify program-wide velocity controls. A POST or PUT call from a role that does not have Program Manager permissions will receive a 403 error if its association field is null, or if it includes all of the fields in the request body. Avoid this by passing a valid user_token or card_product_token in the velocity control’s association object, indicating that the request is specific to a user or card product, and not program-wide. You should also only include the specific fields you want to update, because a PUT or POST with values for all fields is interpreted as a change that requires Program Manager permissions. See Controlling Spending for a tutorial that walks you through the creation of a spend control.

Note Each program supports a maximum of 90 spend controls (velocity controls and authorization controls combined). The limit of 90 spend controls applies at the program level only; it does not affect the number of user-level spend controls you can use.

Create Velocity Control

Action: POST Endpoint: /velocitycontrols Limits how much and how frequently a user can spend funds. If multiple velocity controls apply to the same user, the user cannot exceed any of the defined spending limits.

Tip You can create program-level controls in the sandbox environment. However, you must work with your Marqeta representative to create program-level controls in a production environment.

Request Body

Velocity control object

• Account funding: All account funding transactions
  
• Cashback: Only the purchase component of cashback transactions
  
• Purchase transactions: All authorizations, PIN debit transactions, and incremental transactions
  
• Quasi-cash: All quasi-cash transactions
  
• Refunds: All refund transactions
  
• Reversals: All reversal transactions
  Allowable Values:
  true, false
  Default value:
  true | | include_transfers
  boolean
  Optional | If set to true, account-to-account transfers are subject to control. Account-to-account transfers are not currently supported.
  Allowable Values:
  true, false
  Default value:
  true | | include_withdrawals
  boolean
  Optional | If set to true, ATM withdrawals are subject to control.
  Allowable Values:
  true, false
  Default value:
  true | | merchant_scope
  object
  Optional | Defines the group of merchants to which the velocity control applies.
  Populate no more than one field of the merchant_scope object. If no fields are populated, the velocity control applies to all merchants.
  Allowable Values:
  mcc, mcc_group, mid, or null (no value) | | merchant_scope. mcc
  string
  Optional | Merchant Category Code (MCC). Identifies the type of products or services provided by the merchant.
  Enter a value to control spending on a particular type of product or service.
  Allowable Values:
  1–4 chars | | merchant_scope. mcc_group
  string
  Optional | Token identifying a group of MCCs. Enter a value to control spending on a group of product or service types.
  Send a GET request to /mccgroups to retrieve MCC group tokens.
  Allowable Values:
  1–36 chars | | merchant_scope. mid
  string
  Optional | Merchant identifier (MID). Identifies a specific merchant.
  Enter a value to control spending with a particular merchant.
  Allowable Values:
  1–36 chars | | name
  string
  Optional | Description of how the velocity control restricts spending, for example, “Max spend of 500 per day”.
  Ensure that the description you provide here adequately captures the restriction exerted by this velocity control, because the Marqeta platform will send this information to you in a webhook in the event that the transaction authorization attempt is declined by the velocity control.
  NOTE: This field is very important. If your program has multiple velocity controls in place, it is not always clear which one prevented the transaction from being approved. Adding specific details to this field provides more contextual information during debugging or monitoring declined authorization attempts.
  Allowable Values:
  255 char max | | token
  string
  Optional | Unique identifier of the velocity control.
  If you do not include a token, the system will generate one automatically. This value cannot be updated.
  Allowable Values:
  1–36 chars | | usage_limit
  integer
  Optional | Maximum number of times a card can be used within the time period defined by the velocity_window field.
  If velocity_window is set to TRANSACTION, do not include a usage_limit in your request.
  Allowable Values:
  -1 min
  -1 to 100 | | velocity_window
  string
  Required | Defines the time period to which the amount_limit and usage_limit fields apply:
  
• DAY – one day
  
• WEEK – one week
  
• MONTH – one month
  
• LIFETIME – forever
  
• TRANSACTION – a single transaction.
  NOTE: If set to DAY, WEEK, or MONTH, the velocity control takes effect retroactively from the beginning of the specified period. The amount and usage data already collected within the specified period are counted toward the limits. If set to LIFETIME, the velocity control only applies to transactions on or after the date and time that the velocity control was created. LIFETIME velocity controls are not retroactively applied to historical transactions.
  Allowable Values:
  DAY, WEEK, MONTH, LIFETIME, TRANSACTION |

Sample Request Body

JSON

{
  "usage_limit": 10,
  "amount_limit": 500.25,
  "velocity_window": "DAY",
  "association": {
    "user_token": "my_user_04"
  },
  "currency_code": "USD",
  "token": "my_velocitycontrol_01"
}

Response Body

• Account funding: All account funding transactions
  
• Cashback: Only the purchase component of cashback transactions
  
• Purchase transactions: All authorizations, PIN debit transactions, and incremental transactions
  
• Quasi-cash: All quasi-cash transactions
  
• Refunds: All refund transactions
  
• Reversals: All reversal transactions
  Allowable Values:
  true, false | | include_transfers
  boolean
  Conditionally returned | If set to true, account-to-account transfers are subject to control. Account-to-account transfers are not currently supported.
  Allowable Values:
  true, false | | include_withdrawals
  boolean
  Conditionally returned | If set to true, ATM withdrawals are subject to control.
  Allowable Values:
  true, false | | merchant_scope
  object
  Conditionally returned | Defines the group of merchants to which the velocity control applies.
  Populate no more than one field of the merchant_scope object. If no fields are populated, the velocity control applies to all merchants.
  Allowable Values:
  mcc, mcc_group, mid, or null (no value) | | merchant_scope. mcc
  string
  Conditionally returned | Merchant Category Code (MCC). Identifies the type of products or services provided by the merchant.
  Enter a value to control spending on a particular type of product or service.
  Allowable Values:
  1–4 chars | | merchant_scope. mcc_group
  string
  Conditionally returned | Token identifying a group of MCCs. Enter a value to control spending on a group of product or service types.
  Send a GET request to /mccgroups to retrieve MCC group tokens.
  Allowable Values:
  1–36 chars | | merchant_scope. mid
  string
  Conditionally returned | Merchant identifier (MID). Identifies a specific merchant.
  Enter a value to control spending with a particular merchant.
  Allowable Values:
  1–36 chars | | name
  string
  Conditionally returned | Description of how the velocity control restricts spending. For example, “Max spend of 500 per day”.
  Allowable Values:
  255 char max | | token
  string
  Conditionally returned | Unique identifier of the velocity control.
  Allowable Values:
  1–36 chars | | usage_limit
  integer
  Conditionally returned | Maximum number of times a card can be used within the time period defined by the velocity_window field.
  Allowable Values:
  -1 min
  -1 to 100, where -1 indicates unlimited uses | | velocity_window
  string
  Returned | Defines the time period to which the amount_limit and usage_limit fields apply:
  
• DAY – one day
  
• WEEK – one week
  
• MONTH – one month
  
• LIFETIME – forever
  
• TRANSACTION – a single transaction.
  Allowable Values:
  DAY, WEEK, MONTH, LIFETIME, TRANSACTION |

Sample Response Body

JSON

{
  "token": "my_velocitycontrol_01",
  "association": {
    "user_token": "my_user_04"
  },
  "merchant_scope": {},
  "usage_limit": 10,
  "approvals_only": true,
  "include_purchases": true,
  "include_withdrawals": true,
  "include_transfers": true,
  "include_cashback": true,
  "include_credits": false,
  "currency_code": "USD",
  "amount_limit": 500.25,
  "velocity_window": "DAY",
  "active": true
}

List Velocity Controls

Action: GET Endpoint: /velocitycontrols Retrieves a list of all the velocity controls associated with a specific user or card product, or lists all the velocity controls defined for your program. Include either a user or a card_product query parameter to indicate the user or card product whose associated velocity controls you want to retrieve (do not include both). To list all velocity controls for your program, omit the user and card_product query parameters from your request. This endpoint supports field filtering and pagination.

URL Query Parameters

Response Body

• Account funding: All account funding transactions
  
• Cashback: Only the purchase component of cashback transactions
  
• Purchase transactions: All authorizations, PIN debit transactions, and incremental transactions
  
• Quasi-cash: All quasi-cash transactions
  
• Refunds: All refund transactions
  
• Reversals: All reversal transactions
  Allowable Values:
  true, false | | data[]. include_transfers
  boolean
  Conditionally returned | If set to true, account-to-account transfers are subject to control. Account-to-account transfers are not currently supported.
  Allowable Values:
  true, false | | data[]. include_withdrawals
  boolean
  Conditionally returned | If set to true, ATM withdrawals are subject to control.
  Allowable Values:
  true, false | | data[]. merchant_scope
  object
  Conditionally returned | Defines the group of merchants to which the velocity control applies.
  Populate no more than one field of the merchant_scope object. If no fields are populated, the velocity control applies to all merchants.
  Allowable Values:
  mcc, mcc_group, mid, or null (no value) | | data[].merchant_scope. mcc
  string
  Conditionally returned | Merchant Category Code (MCC). Identifies the type of products or services provided by the merchant.
  Enter a value to control spending on a particular type of product or service.
  Allowable Values:
  1–4 chars | | data[].merchant_scope. mcc_group
  string
  Conditionally returned | Token identifying a group of MCCs. Enter a value to control spending on a group of product or service types.
  Send a GET request to /mccgroups to retrieve MCC group tokens.
  Allowable Values:
  1–36 chars | | data[].merchant_scope. mid
  string
  Conditionally returned | Merchant identifier (MID). Identifies a specific merchant.
  Enter a value to control spending with a particular merchant.
  Allowable Values:
  1–36 chars | | data[]. name
  string
  Conditionally returned | Description of how the velocity control restricts spending. For example, “Max spend of 500 per day”.
  Allowable Values:
  255 char max | | data[]. token
  string
  Conditionally returned | Unique identifier of the velocity control.
  Allowable Values:
  1–36 chars | | data[]. usage_limit
  integer
  Conditionally returned | Maximum number of times a card can be used within the time period defined by the velocity_window field.
  Allowable Values:
  -1 min
  -1 to 100, where -1 indicates unlimited uses | | data[]. velocity_window
  string
  Returned | Defines the time period to which the amount_limit and usage_limit fields apply:
  
• DAY – one day
  
• WEEK – one week
  
• MONTH – one month
  
• LIFETIME – forever
  
• TRANSACTION – a single transaction.
  Allowable Values:
  DAY, WEEK, MONTH, LIFETIME, TRANSACTION |

Sample Response Body

JSON

{
  "count": 1,
  "start_index": 0,
  "end_index": 0,
  "is_more": false,
  "data": [
    {
      "token": "my_velocitycontrol_01",
      "association": {
        "user_token": "my_user_04"
      },
      "merchant_scope": {},
      "usage_limit": 10,
      "approvals_only": true,
      "include_purchases": true,
      "include_withdrawals": true,
      "include_transfers": true,
      "include_cashback": true,
      "include_credits": false,
      "currency_code": "USD",
      "amount_limit": 500.25,
      "velocity_window": "DAY",
      "active": true
    }
  ]
}

Get Specific Velocity Control

Action: GET Endpoint: /velocitycontrols/{token} Retrieves a specific velocity control.