DOCS

New!

/

15 minute read

August 3, 2019

Velocity Controls

A velocity control is a type of spend control that limits how much users can spend. You can configure velocity controls to limit how much users can spend and/or the number of transactions they can make within a given window of time. Velocity controls can apply to a single user, all users associated with a particular card product, or all users in your program.

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

Create velocity control

Action: POST
Endpoint: /velocitycontrols

Get started now!

Sign up today and get access to Marqeta's API Explorer

Limit how much and how frequently a user can spend funds. If multiple velocity controls apply to the same user, the limits of all the controls are combined (the user cannot exceed any of the defined spending limits).

Note
You can create program-level controls in the shared sandbox. 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 veloc-ity 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, optional

The name of the velocity control.

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:

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 currency code.

Allowable Values:

The three-character ISO 4217 currency code.

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, cash backs 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. If no fields are populated, the velocity control applies to all merchants.

Allowable Values:

association

object, required

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

You must populate one, and only one, field.

Allowable Values:

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

A single 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 indentifying 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}

Get started now!

Sign up today and get access to Marqeta's API Explorer

Retrieve 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}

Get started now!

Sign up today and get access to Marqeta's API Explorer

Update 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, optional

The name of the velocity control.

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:

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 currency code.

Allowable Values:

The three-character ISO 4217 currency code.

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, cash backs 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 only one field. If no fields are populated, the velocity control applies to all merchants.

Allowable Values:

association

object, optional

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

You must populate one, and only one, field.

Allowable Values:

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

A single 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 indentifying 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

Get started now!

Sign up today and get access to Marqeta's API Explorer

List 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 parameter 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

Get started now!

Sign up today and get access to Marqeta's API Explorer

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