POST/
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| Fields | Description |
|---|---|
| active boolean Optional | Indicates whether the velocity control is active. Allowable Values: true, falseDefault value: true |
| amount_limit decimal Required | Maximum monetary sum that can be cleared within the time period defined by the velocity_window field. Refunds and reversals cannot exceed this limit.Allowable Values: 0 min Format: 0.00 |
| approvals_only boolean Optional | If set to true, only approved transactions are subject to control. If set to false, only declined transactions are subject to control.Allowable Values: true, falseDefault value: true |
| association object Optional | Defines the group of users to which the velocity control applies. Allowable Values: card_product_token, user_token |
| association.card_product_token string Optional | Unique identifier of the card product. Pass either card_product_token or user_token, not both.Allowable Values: 1–36 chars |
| association.user_token string Optional | Unique identifier of the cardholder. Pass either card_product_token or user_token, not both.Allowable Values: 1–36 chars |
| currency_code string Required | Three-character ISO 4217 currency code. Allowable Values: Valid three-character ISO 4217 currency code |
| include_cashback boolean Optional | If set to true, the cashback components of point-of-sale transactions are subject to control.Allowable Values: true, falseDefault value: true |
| include_credits boolean Optional | If set to true, original credit transactions (OCT) are subject to control. Your request can contain either a money_in_transaction object or the include_credits field, not both.Allowable Values: true, falseDefault value: false |
| include_purchases boolean Optional | If set to true, the following transactions are subject to control:- 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 (see Controls to limit amount and frequency of spending for more information) - Reversals: All reversal transactions Allowable Values: true, falseDefault 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, falseDefault value: true |
| include_withdrawals boolean Optional | If set to true, ATM withdrawals are subject to control.Allowable Values: true, falseDefault 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. Use the exact MID value as it appears in the card_acceptor.mid field of your Gateway JIT Funding request or transaction webhook. Marqeta performs an exact match on this value — no normalization or formatting is applied.Allowable Values: 1–36 chars |
| name string Optional | 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 |
| token string Optional | 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: 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.Set to -1 to indicate that the card can be used an unlimited number of times.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; days begin at 00:00:00 UTC. - WEEK – one week; weeks begin Sundays at 00:00:00 UTC. - MONTH – one month; months begin on the first day of month at 00:00:00 UTC. - QUARTER – one calendar quarter; quarters begin on the first day of the quarter (January 1, April 1, July 1, or October 1). - YEAR – one calendar year; years begin on January 1. - 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. 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, QUARTER, YEAR, 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
| Fields | Description |
|---|---|
| active boolean Conditionally returned | Indicates whether the velocity control is active. Allowable Values: true, false |
| amount_limit decimal Returned | Maximum monetary sum that can be cleared within the time period defined by the velocity_window field. Refunds and reversals cannot exceed this limit.Allowable Values: 0 min Format: 0.00 |
| approvals_only boolean Conditionally returned | If set to true, only approved transactions are subject to control. If set to false, only declined transactions are subject to control.Allowable Values: true, false |
| association object Conditionally returned | Defines the group of users to which the velocity control applies. Allowable Values: card_product_token, user_token |
| association.card_product_token string Conditionally returned | Unique identifier of the card product. Pass either card_product_token or user_token, not both.Allowable Values: 1–36 chars |
| association.user_token string Conditionally returned | Unique identifier of the cardholder. Pass either card_product_token or user_token, not both.Allowable Values: 1–36 chars |
| currency_code string Returned | Three-character ISO 4217 currency code. Allowable Values: Valid three-character ISO 4217 currency code |
| include_cashback boolean Conditionally returned | If set to true, the cashback components of point-of-sale transactions are subject to control.Allowable Values: true, false |
| include_credits boolean Conditionally returned | If set to true, original credit transactions (OCT) are subject to control.Allowable Values: true, false |
| include_purchases boolean Conditionally returned | If set to true, the following transactions are subject to control:- 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 (see Controls to limit amount and frequency of spending for more information) - 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. Use the exact MID value as it appears in the card_acceptor.mid field of your Gateway JIT Funding request or transaction webhook. Marqeta performs an exact match on this value — no normalization or formatting is applied.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” or “Max spend of $5000 per month for non-exempt employees”. 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; days begin at 00:00:00 UTC. - WEEK – one week; weeks begin Sundays at 00:00:00 UTC. - MONTH – one month; months begin on the first day of month at 00:00:00 UTC. - QUARTER – one calendar quarter; quarters begin on the first day of the quarter (January 1, April 1, July 1, or October 1). - YEAR – one calendar year; years begin on January 1. - LIFETIME – forever; time period never expires. - TRANSACTION – a single transaction. Allowable Values: DAY, WEEK, MONTH, QUARTER, YEAR, 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
}