/

15 minute read

September 4, 2020

Velocity Controls

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 window 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.

Note
See Controlling Spending for a tutorial that walks you through the creation of a spend control.

Create velocity control

Action: POST
Endpoint: /velocitycontrols

Develop Now!

Sign in and use your sandbox to access the API Explorer

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).

Note
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.

Body field details

Fields Description

token

string
Optional

The unique identifier of the velocity control.

If you do not include a token, the system will generate one automatically. This token is necessary for use in other API calls, so we recommend that rather than let the system generate one, you use a simple string that is easy to remember. This value cannot be updated.

Allowable Values:

36 char max

name

string
Required

A description of how the velocity control restricts spending, for example, "Max spend of $500 per day" or "Max spend of $5000 per month for non-exempt employees".

Ensure that the description you provide here adequately captures the kind of 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 gives you more contextual information when debugging or monitoring declined authorization attempts.

Allowable Values:

255 char max

amount_limit

decimal
Required

The maximum monetary sum that can be cleared within the time period defined by the velocity_window field.

Allowable Values:

Format: 0.00

usage_limit

decimal
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:

0-100

velocity_window

string
Required

Defines the time period to which the amount_limit and usage_limit fields apply:

  • DAY – one day; days begin at 00:00:00.

  • WEEK – one week; weeks begin Mondays at 00:00:00.

  • MONTH – one month; months begin on the first day of month at 00:00:00.

  • LIFETIME – forever; time period never expires.

  • 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 first period is counted toward the limits.

Note

Editing any of the following fields on a velocity control resets its usage and amount count to 0:

  • merchant_scope.mcc

  • merchant_scope.mid

  • merchant_scope.mcc_group

  • association.user_token

  • association.card_product_token

  • velocity_window

Allowable Values:

DAY, WEEK, MONTH, LIFETIME, TRANSACTION

currency_code

string
Required

The three-character ISO 4217 currency code.

Allowable Values:

USD, CAD

active

boolean
Optional

Indicates whether the velocity control is active. If the control will be used for Commando Mode, set to false and then enable it using commando_mode_enables. See Update Commando Mode control set.

Allowable Values:

true, false

Default value:
true

approvals_only

boolean
Optional

If set to true, only approved transactions are subject to control.

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

include_transfers

boolean
Optional

If set to true, transfers are subject to control.

Allowable Values:

true, false

Default value:
true

include_purchases

boolean
Optional

If set to true, purchases are subject to control.

Allowable Values:

true, false

Default value:
true

include_cashback

boolean
Optional

If set to true, cashbacks are subject to control.

Allowable Values:

true, false

Default value:
true

include_credits

boolean
Optional

If set to true, original credit transactions are subject to control.

Allowable Values:

true, false

Default value:
false

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:

Existing merchant_scope object or null

Default value:
null

association

object
Optional

Defines the group of users to which the velocity control applies.

Only Program Managers are permitted to create velocity controls whose association field is null.

Allowable Values:

Existing association object or null

Default value:
null

The merchant_scope object

Fields Description

mid

string
Optional

MID (Merchant ID). The unique identification number of a merchant.

Enter a value to control spending with a particular merchant.

Allowable Values:

36 char max

mcc

string
Optional

MCC (Merchant Category Code). Identifies the type of goods or services provided by the merchant.

Enter a value to control spending on a particular type of product or service.

Allowable Values:

4 char max

mcc_group

string
Optional

Token identifying a group of MCCs.

Enter a value to control spending on a group of product or service types.

Allowable Values:

Existing MCC group token.

Send a GET request to /mccgroups to retrieve MCC group tokens.

The association object

Fields Description

card_product_token

OR

user_token

string
Required

Token identifying either a card product or user.

Specify a card product token in the card_product_token field to apply the velocity control to all users holding active cards associated with the card product. Specify a user token in the user_token field to apply the velocity control to a single user.

Pass either card_product_token or user_token, not both.

Allowable Values:

Existing card product or user token.

Send a GET request to /cardproducts to retrieve card product tokens or to /users to retrieve user tokens.

Sample request body

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

Is this helpful?

Sample response body

{
    "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,
    "velocity_window": "DAY",
    "active": true
}

Is this helpful?

Retrieve velocity control

Action: GET
Endpoint: /velocitycontrols/{token}

Develop Now!

Sign in and use your sandbox to access the API Explorer

Retrieves a specific velocity control.

URL path parameters

Fields Description

token

string
Required

Identifies the velocity control to retrieve.

Allowable Values:

Existing velocity control token.

Send a GET request to /velocitycontrols to retrieve velocity controls tokens.

Sample response body

{
    "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,
    "velocity_window": "DAY",
    "active": true
}

Is this helpful?

Update velocity control

Action: PUT
Endpoint: /velocitycontrols/{token}

Develop Now!

Sign in and use your sandbox to access the API Explorer

Updates a specific velocity control.

URL path parameters

Fields Description

token

string
Required

Identifies the velocity control to update.

Allowable Values:

Existing velocity control token.

Send a GET request to /velocitycontrol to retrieve velocity control tokens.

Body field details

Fields Description

name

string
Required

A description of how the velocity control restricts spending, for example, "Max spend of $500 per day" or "Max spend of $5000 per month for non-exempt employees".

Ensure that the description you provide here adequately captures the kind of 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 gives you more contextual information when debugging or monitoring declined authorization attempts.

Allowable Values:

255 char max

amount_limit

decimal
Required

The maximum monetary sum that can be cleared within the time period defined by the velocity_window field.

Allowable Values:

Format: 0.00

usage_limit

decimal
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:

0-100

velocity_window

string
Required

Defines the time period to which the amount_limit and usage_limit fields apply:

  • DAY – one day; days begin at 00:00:00.

  • WEEK – one week; weeks begin Mondays at 00:00:00.

  • MONTH – one month; months begin on the first day of month at 00:00:00.

  • LIFETIME – forever; time period never expires.

  • 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 first period is counted toward the limits.

Note

Editing any of the following fields on a velocity control resets its usage and amount count to 0:

  • merchant_scope.mcc

  • merchant_scope.mid

  • merchant_scope.mcc_group

  • association.user_token

  • association.card_product_token

  • velocity_window

Allowable Values:

DAY, WEEK, MONTH, LIFETIME, TRANSACTION

currency_code

string
Required

The three-character ISO 4217 currency code.

Allowable Values:

USD, CAD

active

boolean
Optional

Indicates whether the velocity control is active.

Allowable Values:

true, false

Default value:
true

approvals_only

boolean
Optional

If set to true, only approved transactions are subject to control.

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

include_transfers

boolean
Optional

If set to true, transfers are subject to control.

Allowable Values:

true, false

Default value:
true

include_purchases

boolean
Optional

If set to true, purchases are subject to control.

Allowable Values:

true, false

Default value:
true

include_cashback

boolean
Optional

If set to true, cashbacks are subject to control.

Allowable Values:

true, false

Default value:
true

include_credits

boolean
Optional

If set to true, original credit transactions are subject to control.

Allowable Values:

true, false

Default value:
false

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:

Existing merchant_scope object or null

Default value:
null

association

object
Optional

Defines the group of users to which the velocity control applies.

Only Program Managers are permitted to modify velocity controls whose association field is null.

Allowable Values:

Existing association object or null

Default value:
null

The merchant_scope object

Fields Description

mid

string
Optional

MID (Merchant ID). The unique identification number of a merchant.

Enter a value to control spending with a particular merchant.

Allowable Values:

36 char max

mcc

string
Optional

MCC (Merchant Category Code). Identifies the type of goods or services provided by the merchant.

Enter a value to control spending on a particular type of product or service.

Allowable Values:

4 char max

mcc_group

string
Optional

Token identifying a group of MCCs.

Enter a value to control spending on a group of product or service types.

Allowable Values:

Existing MCC group token.

Send a GET request to /mccgroups to retrieve MCC group tokens.

The association object

Fields Description

card_product_token

OR

user_token

string
Required

Token identifying either a card product or user.

Specify a card product token in the card_product_token field to apply the velocity control to all users holding active cards associated with the card product. Specify a user token in the user_token field to apply the velocity control to a single user.

Pass either card_product_token or user_token, not both.

Allowable Values:

Existing card product or user token.

Send a GET request to /cardproducts to retrieve card product tokens or to /users to retrieve user tokens.

Sample request body

{
  "usage_limit": 20,
  "amount_limit": 1000
}

Is this helpful?

Sample response body

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

Is this helpful?

List velocity controls

Action: GET
Endpoint: /velocitycontrols

Develop Now!

Sign in and use your sandbox to access the API Explorer

Lists all velocity controls associated with a specific user or card product, or list all 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.

Query parameters

Fields Description

user

string
Optional

The token identifying the user whose velocity controls you want to retrieve.

Enter the string "null" to list velocity controls that are not associated with a user.

Allowable Values:

Existing user token.

Send a GET request to /users to retrieve user tokens.

card_product

string
Optional

The token identifying the card product whose velocity controls you want to retrieve.

Enter the string "null" to list velocity controls that are not associated with a card product.

Allowable Values:

Existing card product token.

Send a GET request to /cardproducts to retrieve card product tokens.

Sample response body

{
  "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,
        "velocity_window": "DAY",
        "active": true
    }
  ]
}

Is this helpful?

List user velocity control balances

Action: GET
Endpoint: /velocitycontrols/user/{user_token}/available

Develop Now!

Sign in and use your sandbox to access the API Explorer

Lists the available balances of velocity controls associated with a user.

Depending on the control, the balance can include an available monetary amount, the number of transactions remaining, and the number of days remaining in the time window.

This endpoint supports field filtering and pagination.

URL path parameters

Fields Description

user_token

string
Required

Identifies the user whose velocity control balances you want to list.

Allowable Values:

Existing user token.

Send a GET request to /users to retrieve user tokens.

Sample response body

{
  "count": 2,
  "start_index": 0,
  "end_index": 1,
  "is_more": false,
  "data": [
    {
      "token": "card_3_4",
      "name": "foo bar",
      "association": {},
      "merchant_scope": {
        "mcc": "3058"
      },
      "usage_limit": 1,
      "approvals_only": true,
      "include_purchases": true,
      "include_withdrawals": true,
      "include_transfers": true,
      "include_cashback": true,
      "include_credits": false,
      "currency_code": "USD",
      "amount_limit": 296,
      "velocity_window": "DAY",
      "active": true,
      "available": {
        "uses": 1,
        "amount": 296,
        "days_remaining": 1
      }
    },
    {
      "token": "fb12c301-e5b7-4916-9ec8-7066d957fd34",
      "association": {},
      "merchant_scope": {
        "mcc": "1234567890"
      },
      "usage_limit": 1000,
      "approvals_only": true,
      "include_purchases": true,
      "include_withdrawals": true,
      "include_transfers": true,
      "include_cashback": true,
      "include_credits": false,
      "currency_code": "840",
      "amount_limit": 500.5,
      "velocity_window": "DAY",
      "active": true,
      "available": {
        "uses": 1000,
        "amount": 500.5,
        "days_remaining": 1
      }
    }
  ]
}

Is this helpful?

Have any feedback on this page?

If you feel we can do anything better, please let our team know.

We strive for the best possible developer experience.