Create velocity control

Action: POST
Endpoint: /velocitycontrols

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 Customer Success representative to create program-level controls in a production environment.

Body field details

Name Type Required? Description Allowable Values
token string No 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.
36 char max
name string No The name of the velocity control. 255 char max
amount_limit decimal Yes The maximum monetary sum that can be cleared within the time period defined by the velocity_window field. 0.00
usage_limit decimal No 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.
0-100
velocity_window string Yes 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.

Notes:

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.

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
DAY | WEEK | MONTH | LIFETIME | TRANSACTION
currency_code string Yes The currency code. The 3-character ISO 4217 currency code.

"USD" currently supported.
active boolean No Indicates whether the velocity control is active. true | false

Default: true
approvals_only boolean No If set to true, only approved transactions are subject to control. true | false

Default: true
include_withdrawals boolean No If set to true, ATM withdrawals are subject to control. true | false

Default: true
include_transfers boolean No If set to true, transfers are subject to control. true | false

Default: true
include_purchases boolean No If set to true, purchases are subject to control. true | false

Default: true
merchant_scope object No 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.
association object Yes Defines the group of users to which the velocity control applies.

You must populate one, and only one, field.

The merchant_scope object

Name Type Required? Description Allowable Values
mid string No MID (Merchant ID). The unique identification number of a merchant.

Enter a value to control spending with a particular merchant.
36 char max
mcc string No 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.
4 char max
mcc_group string No Token indentifying a group of MCCs.

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

Issue a GET to /mccgroups to retrieve MCC group tokens.

The association object

Name Type Required? Description Allowable Values
card_product_token

OR

user_token
string Yes 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.
Existing card product or user token.

Issue a GET 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"
}

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,
"currency_code": "USD",
"amount_limit": 500,
"velocity_window": "DAY",
"active": true
}


Retrieve velocity control

Action: GET
Endpoint: /velocitycontrols/{token}

Retrieve a specific velocity control.

URL path parameters

Name Type Required? Description Allowable Values
token string Yes Identifies the velocity control to retrieve. Existing velocity control token.

Issue a GET 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,
"currency_code": "USD",
"amount_limit": 500,
"velocity_window": "DAY",
"active": true
}


Update velocity control

Action: PUT
Endpoint: /velocitycontrols/{token}

Update a specific velocity control.

URL path parameters

Name Type Required? Description Allowable Values
token string Yes Identifies the velocity control to update. Existing velocity control token.

Issue a GET to /velocitycontrol to retrieve velocity control tokens.

Body field details

Name Type Required? Description Allowable Values
name string No The name of the velocity control. 255 char max
amount_limit decimal Yes The maximum monetary sum that can be cleared within the time period defined by the velocity_window field. 0.00
usage_limit decimal No 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.
0-100
velocity_window string Yes 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.

Notes:

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.

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
DAY | WEEK | MONTH | LIFETIME | TRANSACTION
currency_code string Yes The currency code. The 3-character ISO 4217 currency code.

"USD" currently supported.
active boolean No Indicates whether the velocity control is active. true | false

Default: true
approvals_only boolean No If set to true, only approved transactions are subject to control. true | false

Default: true
include_withdrawals boolean No If set to true, ATM withdrawals are subject to control. true | false

Default: true
include_transfers boolean No If set to true, transfers are subject to control. true | false

Default: true
include_purchases boolean No If set to true, purchases are subject to control. true | false

Default: true
merchant_scope object No 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.
association object No Defines the group of users to which the velocity control applies.

You must populate one, and only one, field.

Note: You must include this object in your request even if you don't intend to update its values.

The merchant_scope object

Name Type Required? Description Allowable Values
mid string No MID (Merchant ID). The unique identification number of a merchant.

Enter a value to control spending with a particular merchant.
36 char max
mcc string No 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.
4 char max
mcc_group string No Token indentifying a group of MCCs.

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

Issue a GET to /mccgroups to retrieve MCC group tokens.

The association object

Name Type Required? Description Allowable Values
card_product_token

OR

user_token
string Yes 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.
Existing card product or user token.

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

Sample request body

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

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,
"currency_code": "USD",
"amount_limit": 1000,
"velocity_window": "DAY",
"active": true
}


List velocity controls

Action: GET
Endpoint: /velocitycontrols

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

Name Type Required? Description Allowable Values
user string No 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.
Existing user token.

Issue a GET to /users to retrieve user tokens.
card_product string No 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.
Existing card product token.

Issue a GET 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,
"currency_code": "USD",
"amount_limit": 500,
"velocity_window": "DAY",
"active": true
}
]
}


List user velocity control balances

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

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

Name Type Required? Description Allowable Values
user_token string Yes Identifies the user whose velocity control balances you want to list. Existing user token.

Issue a GET 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,
"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,
"currency_code": "840",
"amount_limit": 500.5,
"velocity_window": "DAY",
"active": true,
"available": {
"uses": 1000,
"amount": 500.5,
"days_remaining": 1
}
}
]
}