GET//
Retrieves a specific velocity control.
URL path parameters
| Fields | Description |
|---|---|
| token string Required | Unique identifier of the velocity control resource. Allowable Values: Existing velocity control token |
URL query parameters
| Fields | Description |
|---|---|
| fields string Optional | Comma-delimited list of fields to return (field_1,field_2, and so on). Leave blank to return all fields.Allowable Values: Comma-delimited list of fields, or blank |
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
}