/
40 minute read
March 24, 2022

Velocity Controls

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 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 authorization controls combined).

Create velocity control

Action: POST
Endpoint: /velocitycontrols

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
Fields Description

active

boolean
Optional

Indicates whether the velocity control is active. If the control will be used for Commando Mode, set to false and then enable it using commando_mode_enables. See Update Commando Mode control set.

Allowable Values:

true, false

Default value:
false

amount_limit

decimal
Required

Maximum monetary sum that can be cleared within the time period defined by the velocity_window field.

Allowable Values:

0 min

approvals_only

boolean
Optional

If set to true, only approved transactions are subject to control.

Allowable Values:

true, false

Default value:
false

association

object
Optional

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

Allowable Values:

Valid association object

association.card_product_token

string
Optional

The 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

The unique identifier of the cardholder.

Pass either card_product_token or user_token, not both.

Allowable Values:

1–36 chars

currency_code

string
Required

The three-character ISO 4217 currency code.

Allowable Values:

A valid three-character ISO 4217 currency code

include_cashback

boolean
Optional

If set to true, cashbacks from a point of sale are subject to control.

Allowable Values:

true, false

Default value:
false

include_credits

boolean
Optional

If set to true, original credit transactions are subject to control.

Allowable Values:

true, false

Default value:
false

include_purchases

boolean
Optional

If set to true, purchases are subject to control.

Allowable Values:

true, false

Default value:
false

include_transfers

boolean
Optional

If set to true, transfers are subject to control.

Allowable Values:

true, false

Default value:
false

include_withdrawals

boolean
Optional

If set to true, ATM withdrawals 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 of the merchant_scope object. If no fields are populated, the velocity control applies to all merchants.

Allowable Values:

Valid merchant_scope object or null

merchant_scope.mcc

string
Optional

MCC (Merchant Category Code). 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.merchant_group_token

string
Optional

Token identifying a group of merchants.

Send a GET request to /merchantgroups retrieve merchant group tokens.

Allowable Values:

1–36 chars

merchant_scope.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:

1–36 chars

name

string
Optional

A 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

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.

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

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

Sample request body
JSON
Copied

Is this helpful?

Yes
No
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.

Allowable Values:

0 min

approvals_only

boolean
Conditionally returned

If set to true, only approved 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:

Valid association object

association.card_product_token

string
Conditionally returned

The 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

The unique identifier of the cardholder.

Pass either card_product_token or user_token, not both.

Allowable Values:

1–36 chars

currency_code

string
Returned

The three-character ISO 4217 currency code.

Allowable Values:

A valid three-character ISO 4217 currency code

include_cashback

boolean
Conditionally returned

If set to true, cashbacks from a point of sale are subject to control.

Allowable Values:

true, false

include_credits

boolean
Conditionally returned

If set to true, original credit transactions are subject to control.

Allowable Values:

true, false

include_purchases

boolean
Conditionally returned

If set to true, purchases are subject to control.

Allowable Values:

true, false

include_transfers

boolean
Conditionally returned

If set to true, transfers are subject to control.

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:

Valid merchant_scope object or null

merchant_scope.mcc

string
Conditionally returned

MCC (Merchant Category Code). 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.merchant_group_token

string
Conditionally returned

Token identifying a group of merchants.

Send a GET request to /merchantgroups retrieve merchant group tokens.

Allowable Values:

1–36 chars

merchant_scope.mid

string
Conditionally returned

MID (Merchant ID). The unique identification number of a merchant.

Enter a value to control spending with a particular merchant.

Allowable Values:

1–36 chars

name

string
Conditionally returned

A 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

The 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 Mondays 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.

Allowable Values:

DAY, WEEK, MONTH, LIFETIME, TRANSACTION

Sample response body
JSON
Copied

Is this helpful?

Yes
No

List velocity controls

Action: GET
Endpoint: /velocitycontrols

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 field filtering and pagination.

URL query parameters
Fields Description

card_product

string
Optional

The unique identifier of the card product. Enter the string null to retrieve velocity controls that are not associated with any card product.

Allowable Values:

Existing card_product token

user

string
Optional

The unique identifier of the user. Enter the string null to retrieve velocity controls that are not associated with any user.

Allowable Values:

Existing user token

count

integer
Optional

The number of velocity control resources to retrieve.

Allowable Values:

1-10

start_index

integer
Optional

The sort order index of the first resource in the returned array.

Allowable Values:

Any integer

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

sort_by

string
Optional

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.

Allowable Values:

lastModifiedTime, createdTime, or any field in the resource model

Response body
Fields Description

count

integer
Conditionally returned

The number of velocity control resources retrieved.

Allowable Values:

1-10

data

array of objects
Conditionally returned

An array of velocity control objects.

Allowable Values:

Array of existing velocity control objects

data[].active

boolean
Conditionally returned

Indicates whether the velocity control is active.

Allowable Values:

true, false

data[].amount_limit

decimal
Returned

Maximum monetary sum that can be cleared within the time period defined by the velocity_window field.

Allowable Values:

0 min

data[].approvals_only

boolean
Conditionally returned

If set to true, only approved transactions are subject to control.

Allowable Values:

true, false

data[].association

object
Conditionally returned

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

Allowable Values:

Valid association object

data[].association.card_product_token

string
Conditionally returned

The unique identifier of the card product.

Pass either card_product_token or user_token, not both.

Allowable Values:

1–36 chars

data[].association.user_token

string
Conditionally returned

The unique identifier of the cardholder.

Pass either card_product_token or user_token, not both.

Allowable Values:

1–36 chars

data[].currency_code

string
Returned

The three-character ISO 4217 currency code.

Allowable Values:

A valid three-character ISO 4217 currency code

data[].include_cashback

boolean
Conditionally returned

If set to true, cashbacks from a point of sale are subject to control.

Allowable Values:

true, false

data[].include_credits

boolean
Conditionally returned

If set to true, original credit transactions are subject to control.

Allowable Values:

true, false

data[].include_purchases

boolean
Conditionally returned

If set to true, purchases are subject to control.

Allowable Values:

true, false

data[].include_transfers

boolean
Conditionally returned

If set to true, transfers are subject to control.

Allowable Values:

true, false

data[].include_withdrawals

boolean
Conditionally returned

If set to true, ATM withdrawals are subject to control.

Allowable Values:

true, false

data[].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:

Valid merchant_scope object or null

data[].merchant_scope.mcc

string
Conditionally returned

MCC (Merchant Category Code). 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

data[].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

data[].merchant_scope.merchant_group_token

string
Conditionally returned

Token identifying a group of merchants.

Send a GET request to /merchantgroups retrieve merchant group tokens.

Allowable Values:

1–36 chars

data[].merchant_scope.mid

string
Conditionally returned

MID (Merchant ID). The unique identification number of a merchant.

Enter a value to control spending with a particular merchant.

Allowable Values:

1–36 chars

data[].name

string
Conditionally returned

A 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

data[].token

string
Conditionally returned

The unique identifier of the velocity control.

Allowable Values:

1–36 chars

data[].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

data[].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 Mondays 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.

Allowable Values:

DAY, WEEK, MONTH, LIFETIME, TRANSACTION

end_index

integer
Conditionally returned

The sort order index of the last resource in the returned array.

Allowable Values:

Any integer

is_more

boolean
Conditionally returned

A value of true indicates that more unreturned resources exist.

Allowable Values:

true, false

start_index

integer
Conditionally returned

The sort order index of the last resource in the returned array.

Allowable Values:

Any integer

Sample response body
JSON
Copied

Is this helpful?

Yes
No

Returns a specific velocity control

Action: GET
Endpoint: /velocitycontrols/{token}

Retrieves a specific velocity control.

URL path parameters
Fields Description

token

string
Required

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

Allowable Values:

0 min

approvals_only

boolean
Conditionally returned

If set to true, only approved 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:

Valid association object

association.card_product_token

string
Conditionally returned

The 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

The unique identifier of the cardholder.

Pass either card_product_token or user_token, not both.

Allowable Values:

1–36 chars

currency_code

string
Returned

The three-character ISO 4217 currency code.

Allowable Values:

A valid three-character ISO 4217 currency code

include_cashback

boolean
Conditionally returned

If set to true, cashbacks from a point of sale are subject to control.

Allowable Values:

true, false

include_credits

boolean
Conditionally returned

If set to true, original credit transactions are subject to control.

Allowable Values:

true, false

include_purchases

boolean
Conditionally returned

If set to true, purchases are subject to control.

Allowable Values:

true, false

include_transfers

boolean
Conditionally returned

If set to true, transfers are subject to control.

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:

Valid merchant_scope object or null

merchant_scope.mcc

string
Conditionally returned

MCC (Merchant Category Code). 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.merchant_group_token

string
Conditionally returned

Token identifying a group of merchants.

Send a GET request to /merchantgroups retrieve merchant group tokens.

Allowable Values:

1–36 chars

merchant_scope.mid

string
Conditionally returned

MID (Merchant ID). The unique identification number of a merchant.

Enter a value to control spending with a particular merchant.

Allowable Values:

1–36 chars

name

string
Conditionally returned

A 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

The 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 Mondays 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.

Allowable Values:

DAY, WEEK, MONTH, LIFETIME, TRANSACTION

Sample response body
JSON
Copied

Is this helpful?

Yes
No

Update velocity control

Action: PUT
Endpoint: /velocitycontrols/{token}

Updates a specific velocity control.

URL path parameters
Fields Description

token

string
Required

The unique identifier of the velocity control resource.

Allowable Values:

Existing velocity control token

Request body
Fields Description

active

boolean
Optional

Indicates whether the velocity control is active.

Allowable Values:

true, false

Default value:
false

amount_limit

decimal
Optional

Maximum monetary sum that can be cleared within the time period defined by the velocity_window field.

Allowable Values:

0 min

approvals_only

boolean
Optional

If set to true, only approved transactions are subject to control.

Allowable Values:

true, false

Default value:
false

association

object
Optional

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

Allowable Values:

Valid association object

association.card_product_token

string
Optional

The 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

The unique identifier of the cardholder.

Pass either card_product_token or user_token, not both.

Allowable Values:

1–36 chars

currency_code

string
Optional

The three-character ISO 4217 currency code.

Allowable Values:

A valid three-character ISO 4217 currency code

include_cashback

boolean
Optional

If set to true, cashbacks from a point of sale are subject to control.

Allowable Values:

true, false

Default value:
false

include_credits

boolean
Optional

If set to true, original credit transactions are subject to control.

Allowable Values:

true, false

Default value:
false

include_purchases

boolean
Optional

If set to true, purchases are subject to control.

Allowable Values:

true, false

Default value:
false

include_transfers

boolean
Optional

If set to true, transfers are subject to control.

Allowable Values:

true, false

Default value:
false

include_withdrawals

boolean
Optional

If set to true, ATM withdrawals 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 of the merchant_scope object. If no fields are populated, the velocity control applies to all merchants.

Allowable Values:

Valid merchant_scope object or null

merchant_scope.mcc

string
Optional

MCC (Merchant Category Code). 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.merchant_group_token

string
Optional

Token identifying a group of merchants.

Send a GET request to /merchantgroups retrieve merchant group tokens.

Allowable Values:

1–36 chars

merchant_scope.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:

1–36 chars

name

string
Optional

A 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
Required

The unique identifier of the velocity control resource.

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.

Allowable Values:

-1 min

-1 to 100, where -1 indicates unlimited uses

velocity_window

string
Optional

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 Mondays at 00:00:00 UTC.

  • MONTH – one month; months begin on the first day of month at 00:00:00 UTC.

  • QUARTER - three months; quarters begin on January 1, April 1, July 1, and October 1 at 00:00:00 UTC.

  • YEAR - twelve months; years begin on January 1 at 00:00:00 UTC.

  • LIFETIME – forever; time period never expires.

  • TRANSACTION – a single transaction.

NOTE: If set to DAY, WEEK, MONTH, QUARTER, or YEAR, 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, QUARTER, YEAR, LIFETIME, TRANSACTION

Sample request body
JSON
Copied

Is this helpful?

Yes
No
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.

Allowable Values:

0 min

approvals_only

boolean
Conditionally returned

If set to true, only approved 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:

Valid association object

association.card_product_token

string
Conditionally returned

The 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

The unique identifier of the cardholder.

Pass either card_product_token or user_token, not both.

Allowable Values:

1–36 chars

currency_code

string
Returned

The three-character ISO 4217 currency code.

Allowable Values:

A valid three-character ISO 4217 currency code

include_cashback

boolean
Conditionally returned

If set to true, cashbacks from a point of sale are subject to control.

Allowable Values:

true, false

include_credits

boolean
Conditionally returned

If set to true, original credit transactions are subject to control.

Allowable Values:

true, false

include_purchases

boolean
Conditionally returned

If set to true, purchases are subject to control.

Allowable Values:

true, false

include_transfers

boolean
Conditionally returned

If set to true, transfers are subject to control.

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:

Valid merchant_scope object or null

merchant_scope.mcc

string
Conditionally returned

MCC (Merchant Category Code). 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.merchant_group_token

string
Conditionally returned

Token identifying a group of merchants.

Send a GET request to /merchantgroups retrieve merchant group tokens.

Allowable Values:

1–36 chars

merchant_scope.mid

string
Conditionally returned

MID (Merchant ID). The unique identification number of a merchant.

Enter a value to control spending with a particular merchant.

Allowable Values:

1–36 chars

name

string
Conditionally returned

A 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

The 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 Mondays 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.

Allowable Values:

DAY, WEEK, MONTH, LIFETIME, TRANSACTION

Sample response body
JSON
Copied

Is this helpful?

Yes
No

List user velocity control balances

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

Retrieves a list of the available balances of the 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

The unique identifier of the cardholder.

Allowable Values:

Existing user token

URL query parameters
Fields Description

count

integer
Optional

The number of available balance resources to retrieve.

Allowable Values:

1-10

start_index

integer
Optional

The sort order index of the first resource in the returned array.

Allowable Values:

Any integer

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

sort_by

string
Optional

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.

Allowable Values:

lastModifiedTime, createdTime, or any field in the resource model

Response body
Fields Description

count

integer
Conditionally returned

The number of velocity control resources retrieved.

Allowable Values:

1-10

data

array of objects
Conditionally returned

An array of velocity control resources that include available balances.

Allowable Values:

Array of existing velocity control objects

data[].active

boolean
Conditionally returned

Indicates whether the velocity control is active.

Allowable Values:

true, false

data[].amount_limit

decimal
Returned

Maximum monetary sum that can be cleared within the time period defined by the velocity_window field.

Allowable Values:

0 min

data[].approvals_only

boolean
Conditionally returned

If set to true, only approved transactions are subject to control.

Allowable Values:

true, false

data[].association

object
Conditionally returned

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

Allowable Values:

Valid association object

data[].association.card_product_token

string
Conditionally returned

The unique identifier of the card product.

Pass either card_product_token or user_token, not both.

Allowable Values:

1–36 chars

data[].association.user_token

string
Conditionally returned

The unique identifier of the cardholder.

Pass either card_product_token or user_token, not both.

Allowable Values:

1–36 chars

data[].available

object
Returned

Specifies the available balances of the velocity controls associated with a user.

Allowable Values:

Valid available object

data[].available.amount

decimal
Returned

The total amount of spend remaining in the velocity control.

Allowable Values:

0 min

data[].available.days_remaining

integer
Conditionally returned

The number of days remaining in the velocity control time window.

Allowable Values:

255 char max

data[].available.uses

integer
Returned

The number of uses remaining in the velocity control.

Allowable Values:

-1 to 100, where -1 indicates unlimited uses

data[].currency_code

string
Returned

The three-character ISO 4217 currency code.

Allowable Values:

A valid three-character ISO 4217 currency code

data[].include_cashback

boolean
Conditionally returned

If set to true, cashbacks from a point of sale are subject to control.

Allowable Values:

true, false

data[].include_credits

boolean
Conditionally returned

If set to true, original credit transactions are subject to control.

Allowable Values:

true, false

data[].include_purchases

boolean
Conditionally returned

If set to true, purchases are subject to control.

Allowable Values:

true, false

data[].include_transfers

boolean
Conditionally returned

If set to true, transfers are subject to control.

Allowable Values:

true, false

data[].include_withdrawals

boolean
Conditionally returned

If set to true, ATM withdrawals are subject to control.

Allowable Values:

true, false

data[].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:

Valid merchant_scope object or null

data[].merchant_scope.mcc

string
Conditionally returned

MCC (Merchant Category Code). 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

data[].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

data[].merchant_scope.merchant_group_token

string
Conditionally returned

Token identifying a group of merchants.

Send a GET request to /merchantgroups retrieve merchant group tokens.

Allowable Values:

1–36 chars

data[].merchant_scope.mid

string
Conditionally returned

MID (Merchant ID). The unique identification number of a merchant.

Enter a value to control spending with a particular merchant.

Allowable Values:

1–36 chars

data[].name

string
Conditionally returned

A 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

data[].token

string
Conditionally returned

The unique identifier of the velocity control.

Allowable Values:

1–36 chars

data[].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

data[].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 Mondays 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.

Allowable Values:

DAY, WEEK, MONTH, LIFETIME, TRANSACTION

end_index

integer
Conditionally returned

The sort order index of the last resource in the returned array.

Allowable Values:

Any integer

is_more

boolean
Conditionally returned

A value of true indicates that more unreturned resources exist.

Allowable Values:

true, false

start_index

integer
Conditionally returned

The sort order index of the last resource in the returned array.

Allowable Values:

Any integer

Sample response body
JSON
Copied

Is this helpful?

Yes
No
Join our developer newsletter