openapi: 3.0.3
info:
contact:
email: support@marqeta.com
name: Marqeta
description: Marqeta's Core API endpoints, conveniently annotated to enable code generation (including SDKs), test cases, and documentation. Currently in beta.
termsOfService: https://www.marqeta.com/api-terms
title: Core accepted countries Velocity Controls API
version: 3.0.39
servers:
- url: /v3
security:
- mqAppAndAccessToken: []
tags:
- description: '// Conditional snippet for beta or internal content
include::../../maturity-admonition-banner.adoc[]
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 span 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.
See <</developer-guides/controlling-spending, Controlling Spending>> for a tutorial that walks you through the creation of a spend control.
[NOTE]
Each program supports a maximum of 90 spend controls (velocity controls and <</core-api/authorization-controls, authorization controls>> combined).
The limit of 90 spend controls applies at the program level only; it does not affect the number of user-level spend controls you can use.'
name: Velocity Controls
paths:
/velocitycontrols:
get:
description: 'Retrieves a list of all the velocity controls associated with a specific user or card product, or lists all the 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 <</core-api/field-filtering, field filtering>> and <</core-api/sorting-and-pagination, pagination>>.'
operationId: getVelocitycontrols
parameters:
- description: 'Unique identifier of the card product.
Enter the string `null` to retrieve velocity controls that are not associated with any card product.'
explode: true
in: query
name: card_product
required: false
schema:
type: string
style: form
- description: 'Unique identifier of the user.
Enter the string `null` to retrieve velocity controls that are not associated with any user.'
explode: true
in: query
name: user
required: false
schema:
type: string
style: form
- description: Number of velocity control resources to retrieve.
explode: true
in: query
name: count
required: false
schema:
default: 5
format: int32
type: integer
style: form
- description: Sort order index of the first resource in the returned array.
explode: true
in: query
name: start_index
required: false
schema:
default: 0
format: int32
type: integer
style: form
- description: 'Comma-delimited list of fields to return (`field_1,field_2`, and so on).
Leave blank to return all fields.'
explode: true
in: query
name: fields
required: false
schema:
type: string
style: form
- description: 'Field on which to sort.
Use any field in the resource model, or one of the system fields `lastModifiedTime` or `createdTime`.
Prefix the field name with a hyphen (`-`) to sort in descending order.
Omit the hyphen to sort in ascending order.'
explode: true
in: query
name: sort_by
required: false
schema:
default: -lastModifiedTime
type: string
style: form
responses:
'200':
content:
application/json:
example:
count: 1
data:
- active: true
amount_limit: 500.25
approvals_only: true
association:
user_token: my_user_04
currency_code: USD
include_cashback: true
include_credits: false
include_purchases: true
include_transfers: true
include_withdrawals: true
merchant_scope: {}
token: my_velocitycontrol_01
usage_limit: 10
velocity_window: DAY
end_index: 0
is_more: false
start_index: 0
schema:
$ref: '#/components/schemas/VelocityControlListResponse'
description: Success
'400':
content: {}
description: Bad request
'500':
content: {}
description: Server error
summary: List velocity controls
tags:
- Velocity Controls
post:
description: '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.'
operationId: postVelocitycontrols
requestBody:
content:
application/json:
example:
amount_limit: 500.25
association:
user_token: my_user_04
currency_code: USD
token: my_velocitycontrol_01
usage_limit: 10
velocity_window: DAY
schema:
$ref: '#/components/schemas/velocity_control_request'
description: Velocity control object
required: true
responses:
'201':
content:
application/json:
example:
active: true
amount_limit: 500.25
approvals_only: true
association:
user_token: my_user_04
currency_code: USD
include_cashback: true
include_credits: false
include_purchases: true
include_transfers: true
include_withdrawals: true
merchant_scope: {}
token: my_velocitycontrol_01
usage_limit: 10
velocity_window: DAY
schema:
$ref: '#/components/schemas/velocity_control_response'
description: Created
'400':
content: {}
description: Bad request
'409':
content: {}
description: Token already associated with a different payload
'500':
content: {}
description: Server error
summary: Create velocity control
tags:
- Velocity Controls
/velocitycontrols/user/{user_token}/available:
get:
description: 'Retrieves a list of the available balances of the velocity controls associated with a user.
This operation is unavailable for velocity controls with a window of `TRANSACTION`, because available balances do not apply to single-transaction velocity windows.
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 <</core-api/field-filtering, field filtering>> and <</core-api/sorting-and-pagination, pagination>>.'
operationId: getVelocitycontrolsUserUsertokenAvailable
parameters:
- description: Unique identifier of the cardholder.
explode: false
in: path
name: user_token
required: true
schema:
type: string
style: simple
- description: Number of available balance resources to retrieve.
explode: true
in: query
name: count
required: false
schema:
default: 5
format: int32
type: integer
style: form
- description: The sort order index of the first resource in the returned array.
explode: true
in: query
name: start_index
required: false
schema:
default: 0
format: int32
type: integer
style: form
- description: 'Comma-delimited list of fields to return (`field_1,field_2`, and so on).
Leave blank to return all fields.'
explode: true
in: query
name: fields
required: false
schema:
type: string
style: form
- description: 'Field on which to sort.
Use any field in the resource model, or one of the system fields `lastModifiedTime` or `createdTime`.
Prefix the field name with a hyphen (`-`) to sort in descending order.
Omit the hyphen to sort in ascending order.'
explode: true
in: query
name: sort_by
required: false
schema:
default: -lastModifiedTime
type: string
style: form
responses:
'200':
content:
application/json:
example:
count: 2
data:
- active: true
amount_limit: 296.25
approvals_only: true
association: {}
available:
amount: 296.0
days_remaining: 1
uses: 1
currency_code: USD
include_cashback: true
include_credits: false
include_purchases: true
include_transfers: true
include_withdrawals: true
merchant_scope:
mcc: '3058'
name: Jane Doe
token: card_3
usage_limit: 1
velocity_window: DAY
- active: true
amount_limit: 500.25
approvals_only: true
association: {}
available:
amount: 500.5
days_remaining: 1
uses: 1000
currency_code: '840'
include_cashback: true
include_credits: false
include_purchases: true
include_transfers: true
include_withdrawals: true
merchant_scope:
mcc: '1234'
token: card_4
usage_limit: 1000
velocity_window: DAY
end_index: 1
is_more: false
start_index: 0
schema:
$ref: '#/components/schemas/VelocityControlBalanceListResponse'
description: Success
'400':
content: {}
description: Bad request
'500':
content: {}
description: Server error
summary: List user velocity control balances
tags:
- Velocity Controls
/velocitycontrols/{token}:
get:
description: Retrieves a specific velocity control.
operationId: getVelocitycontrolsToken
parameters:
- description: Unique identifier of the velocity control resource.
explode: false
in: path
name: token
required: true
schema:
type: string
style: simple
- description: 'Comma-delimited list of fields to return (`field_1,field_2`, and so on).
Leave blank to return all fields.'
explode: true
in: query
name: fields
required: false
schema:
type: string
style: form
responses:
'200':
content:
application/json:
example:
active: true
amount_limit: 500.25
approvals_only: true
association:
user_token: my_user_04
currency_code: USD
include_cashback: true
include_credits: false
include_purchases: true
include_transfers: true
include_withdrawals: true
merchant_scope: {}
token: my_velocitycontrol_01
usage_limit: 10
velocity_window: DAY
schema:
$ref: '#/components/schemas/velocity_control_response'
description: Success
'400':
content: {}
description: Bad request
'404':
content: {}
description: Velocity control not found
'500':
content: {}
description: Server error
summary: Returns a specific velocity control
tags:
- Velocity Controls
put:
description: Updates a specific velocity control.
operationId: putVelocitycontrolsToken
parameters:
- description: Unique identifier of the velocity control resource.
explode: false
in: path
name: token
required: true
schema:
type: string
style: simple
requestBody:
content:
application/json:
example:
amount_limit: 1000.25
token: my_velocitycontrol_01
usage_limit: 20
schema:
$ref: '#/components/schemas/velocity_control_update_request'
description: Velocity control object
required: true
responses:
'200':
content:
application/json:
example:
active: true
amount_limit: 1000.25
approvals_only: true
association:
user_token: my_user_04
currency_code: USD
include_cashback: true
include_credits: false
include_purchases: true
include_transfers: true
include_withdrawals: true
merchant_scope: {}
token: my_velocitycontrol_01
usage_limit: 20
velocity_window: DAY
schema:
$ref: '#/components/schemas/velocity_control_response'
description: Success
'400':
content: {}
description: Bad request
'500':
content: {}
description: Server error
summary: Update velocity control
tags:
- Velocity Controls
delete:
operationId: deleteVelocitycontrolsToken
parameters:
- description: Velocity control token
explode: false
in: path
name: token
required: true
schema:
type: string
style: simple
responses:
'200':
content:
application/json:
schema:
$ref: '#/components/schemas/velocity_control_response'
description: Success
'404':
content: {}
description: Velocity control not found
'500':
content: {}
description: Server error
summary: Sets a specific velocity control to inactive to soft delete it
tags:
- Velocity Controls
/velocitycontrols/account/{account_token}/available:
get:
operationId: getVelocitycontrolsAccountAccountTokenAvailable
parameters:
- description: Account token
explode: false
in: path
name: account_token
required: true
schema:
type: string
style: simple
responses:
'200':
content:
application/json:
schema:
$ref: '#/components/schemas/VelocityControlBalanceListResponse'
description: Success
'400':
content: {}
description: Bad request
'500':
content: {}
description: Server error
summary: Retrieve velocity control available balances for an account token
tags:
- Velocity Controls
components:
schemas:
VelocityControlListResponse:
properties:
count:
description: 'Number of resources retrieved.
This field is returned if there are resources in your returned array.'
format: int32
type: integer
data:
description: 'Array of velocity control objects.
Objects are returned as appropriate to your query.'
items:
$ref: '#/components/schemas/velocity_control_response'
type: array
end_index:
description: 'Sort order index of the last resource in the returned array.
This field is returned if there are resources in your returned array.'
format: int32
type: integer
is_more:
default: false
description: 'A value of `true` indicates that more unreturned resources exist.
A value of `false` indicates that no more unreturned resources exist.
This field is returned if there are resources in your returned array.'
type: boolean
start_index:
description: 'The sort order index of the last resource in the returned array.
This field is returned if there are resources in your returned array.'
format: int32
type: integer
type: object
spend_control_association:
description: Defines the group of users to which the velocity control applies.
properties:
account_template_token:
maxLength: 36
minLength: 1
type: string
card_product_token:
description: 'Unique identifier of the card product.
Pass either `card_product_token` or `user_token`, not both.'
maxLength: 36
minLength: 1
type: string
user_token:
description: 'Unique identifier of the cardholder.
Pass either `card_product_token` or `user_token`, not both.'
maxLength: 36
minLength: 1
type: string
type: object
money_in_transaction:
description: 'Defines the original credit transaction (OCT) types that are subject to velocity control.
Your request can contain either a `money_in_transaction` object or the `include_credits` field, not both.'
properties:
include_credits_types:
description: Specifies the types of credits to include in the original credit transaction (OCT).
items:
type: string
type: array
include_network_load_types:
description: Indicates whether or not cash and check network load transactions will be subject to velocity control.
items:
type: string
type: array
type: object
velocity_control_balance_response:
properties:
active:
description: Indicates whether the velocity control is active.
type: boolean
amount_limit:
description: 'Maximum monetary sum that can be cleared within the time period defined by the `velocity_window` field.
Refunds and reversals cannot exceed this limit.'
exclusiveMinimum: false
minimum: 0
type: number
approvals_only:
description: 'If set to `true`, only approved transactions are subject to control.
If set to `false`, only declined transactions are subject to control.'
type: boolean
association:
$ref: '#/components/schemas/spend_control_association'
available:
$ref: '#/components/schemas/available'
currency_code:
description: Three-character ISO 4217 currency code.
type: string
include_cashback:
description: If set to `true`, the cashback components of point-of-sale transactions are subject to control.
type: boolean
include_credits:
description: If set to `true`, original credit transactions (OCT) are subject to control.
type: boolean
include_purchases:
description: '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 <</developer-guides/controlling-spending#_controls_to_limit_amount_and_frequency_of_spending, Controls to limit amount and frequency of spending>> for more information)
* *Reversals:* All reversal transactions'
type: boolean
include_transfers:
description: 'If set to `true`, account-to-account transfers are subject to control.
Account-to-account transfers are not currently supported.'
type: boolean
include_withdrawals:
description: If set to `true`, ATM withdrawals are subject to control.
type: boolean
merchant_scope:
$ref: '#/components/schemas/merchant_scope'
money_in_transaction:
$ref: '#/components/schemas/money_in_transaction'
name:
description: 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".
maxLength: 255
minLength: 0
type: string
token:
description: Unique identifier of the velocity control.
maxLength: 36
minLength: 1
type: string
usage_limit:
description: Maximum number of times a card can be used within the time period defined by the `velocity_window` field.
format: int32
minimum: -1
type: integer
velocity_window:
description: '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.
* *LIFETIME* – forever; time period never expires.
* *TRANSACTION* – a single transaction.'
enum:
- DAY
- WEEK
- MONTH
- LIFETIME
- TRANSACTION
type: string
required:
- amount_limit
- available
- currency_code
- velocity_window
type: object
VelocityControlBalanceListResponse:
properties:
count:
description: 'Number of velocity control resources retrieved.
This field is returned if there are resources in your returned array.'
format: int32
type: integer
data:
description: 'Array of velocity control objects that include available balances.
Objects are returned as appropriate to your query.'
items:
$ref: '#/components/schemas/velocity_control_balance_response'
type: array
end_index:
description: 'Sort order index of the last resource in the returned array.
This field is returned if there are resources in your returned array.'
format: int32
type: integer
is_more:
default: false
description: 'A value of `true` indicates that more unreturned resources exist.
A value of `false` indicates that no more unreturned resources exist.
This field is returned if there are resources in your returned array.'
type: boolean
start_index:
description: 'Sort order index of the last resource in the returned array.
This field is returned if there are resources in your returned array.'
format: int32
type: integer
type: object
available:
description: 'Specifies the available balances of the velocity controls associated with a user.
This object is not returned if the velocity control window is `TRANSACTION`, because available balances do not apply to single-transaction velocity windows.'
properties:
amount:
description: Total amount of spend remaining in the velocity control.
exclusiveMinimum: false
minimum: 0
type: number
days_remaining:
description: Number of days remaining in the velocity control time window.
format: int32
type: integer
uses:
default: 0
description: Number of uses remaining in the velocity control.
format: int32
type: integer
required:
- amount
- uses
type: object
merchant_scope:
description: '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.'
properties:
mcc:
description: '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.'
maxLength: 4
minLength: 1
type: string
mcc_group:
description: '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.'
maxLength: 36
minLength: 1
type: string
mid:
description: 'Merchant identifier (MID).
Identifies a specific merchant.
Enter a value to control spending with a particular merchant.'
maxLength: 36
minLength: 1
type: string
type: object
velocity_control_request:
properties:
active:
description: Indicates whether the velocity control is active.
type: boolean
amount_limit:
description: 'Maximum monetary sum that can be cleared within the time period defined by the `velocity_window` field.
Refunds and reversals cannot exceed this limit.'
exclusiveMinimum: false
minimum: 0
type: number
approvals_only:
description: 'If set to `true`, only approved transactions are subject to control.
If set to `false`, only declined transactions are subject to control.'
type: boolean
association:
$ref: '#/components/schemas/spend_control_association'
currency_code:
description: Three-character ISO 4217 currency code.
type: string
include_cashback:
description: If set to `true`, the cashback components of point-of-sale transactions are subject to control.
type: boolean
include_credits:
description: '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.'
type: boolean
include_purchases:
description: '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 <</developer-guides/controlling-spending#_controls_to_limit_amount_and_frequency_of_spending, Controls to limit amount and frequency of spending>> for more information)
* *Reversals:* All reversal transactions'
type: boolean
include_transfers:
description: 'If set to `true`, account-to-account transfers are subject to control.
Account-to-account transfers are not currently supported.'
type: boolean
include_withdrawals:
description: If set to `true`, ATM withdrawals are subject to control.
type: boolean
merchant_scope:
$ref: '#/components/schemas/merchant_scope'
money_in_transaction:
$ref: '#/components/schemas/money_in_transaction'
name:
description: '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.'
maxLength: 255
minLength: 0
type: string
token:
description: '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.'
maxLength: 36
minLength: 1
type: string
usage_limit:
description: '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.'
format: int32
minimum: -1
type: integer
velocity_window:
description: '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.
* *LIFETIME* – forever; time period never expires.
* *TRANSACTION* – a single transaction.
// (2023-05-03): This statement was validated by Processing, as part of a customer inquiry.
*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 cont
# --- truncated at 32 KB (42 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/marqeta/refs/heads/main/openapi/marqeta-velocity-controls-api-openapi.yml