/
40 minute read
April 18, 2023

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

Velocity control object

Fields Description

active

boolean
Optional

Indicates whether the velocity control is active.

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:

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, 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 (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, false

Default value:
false

money_in_transaction

object
Optional

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.

Allowable Values:

include_credits_types, include_network_load_types

money_in_transaction.include_credits_types

array of strings
Optional

Specifies the types of credits to include in the original credit transaction (OCT).

Allowable Values:

CASH_DEPOSIT, ALL, NONE

money_in_transaction.include_network_load_types

array of strings
Optional

Indicates whether or not cash and check network load transactions will be subject to velocity control.

Allowable Values:

ALL, NONE

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:

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.

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.

  • 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:

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, 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 (OCT) are subject to control.

Allowable Values:

true, false

money_in_transaction

object
Conditionally returned

Defines the original credit transaction (OCT) types that are subject to velocity control.

Allowable Values:

include_credits_types, include_network_load_types

money_in_transaction.include_credits_types

array of strings
Conditionally returned

Specifies the types of credits to include in the original credit transaction (OCT).

Allowable Values:

CASH_DEPOSIT, ALL, NONE

money_in_transaction.include_network_load_types

array of strings
Conditionally returned

Indicates whether or not cash and check network load transactions will be subject to velocity control.

Allowable Values:

ALL, NONE

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:

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.

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.

  • 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

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

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

Number of velocity control resources to retrieve.

Allowable Values:

1-10

Default value:
5

start_index

integer
Optional

Sort order index of the first resource in the returned array.

Allowable Values:

Any integer

Default value:
0

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:

createdTime, lastModifiedTime, or any field in the resource model

Response body

Fields Description

count

integer
Conditionally returned

Number of resources retrieved.

This field is returned if there are resources in your returned array.

Allowable Values:

1-10

data

array of objects
Conditionally returned

Array of velocity control objects.

Objects are returned as appropriate to your query.

Allowable Values:

Valid array of one or more 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:

card_product_token, user_token

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

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

data[].currency_code

string
Returned

Three-character ISO 4217 currency code.

Allowable Values:

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 (OCT) are subject to control.

Allowable Values:

true, false

data[].money_in_transaction

object
Conditionally returned

Defines the original credit transaction (OCT) types that are subject to velocity control.

Allowable Values:

include_credits_types, include_network_load_types

data[].money_in_transaction.include_credits_types

array of strings
Conditionally returned

Specifies the types of credits to include in the original credit transaction (OCT).

Allowable Values:

CASH_DEPOSIT, ALL, NONE

data[].money_in_transaction.include_network_load_types

array of strings
Conditionally returned

Indicates whether or not cash and check network load transactions will be subject to velocity control.

Allowable Values:

ALL, NONE

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:

mcc, mcc_group, mid, or null (no value)

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

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

string
Conditionally returned

Merchant identifier (MID). Identifies a specific merchant.

Enter a value to control spending with a particular merchant.

Allowable Values:

1–36 chars

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

data[].token

string
Conditionally returned

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

Allowable Values:

DAY, WEEK, MONTH, LIFETIME, TRANSACTION

end_index

integer
Conditionally returned

Sort order index of the last resource in the returned array.

This field is returned if there are resources in your returned array.

Allowable Values:

Any integer

is_more

boolean
Conditionally returned

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.

Allowable Values:

true, false

start_index

integer
Conditionally returned

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

This field is returned if there are resources in your 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

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:

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, 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 (OCT) are subject to control.

Allowable Values:

true, false

money_in_transaction

object
Conditionally returned

Defines the original credit transaction (OCT) types that are subject to velocity control.

Allowable Values:

include_credits_types, include_network_load_types

money_in_transaction.include_credits_types

array of strings
Conditionally returned

Specifies the types of credits to include in the original credit transaction (OCT).

Allowable Values:

CASH_DEPOSIT, ALL, NONE

money_in_transaction.include_network_load_types

array of strings
Conditionally returned

Indicates whether or not cash and check network load transactions will be subject to velocity control.

Allowable Values:

ALL, NONE

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:

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.

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.

  • 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

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:

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
Optional

Three-character ISO 4217 currency code.

Allowable Values:

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. Your request can contain either a money_in_transaction object or the include_credits field, not both.

Allowable Values:

true, false

Default value:
false

money_in_transaction

object
Optional

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.

Allowable Values:

include_credits_types, include_network_load_types

money_in_transaction.include_credits_types

array of strings
Optional

Specifies the types of credits to include in the original credit transaction (OCT).

Allowable Values:

CASH_DEPOSIT, ALL, NONE

money_in_transaction.include_network_load_types

array of strings
Optional

Indicates whether or not cash and check network load transactions will be subject to velocity control.

Allowable Values:

ALL, NONE

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:

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.

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
Required

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 Sundays 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:

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, 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 (OCT) are subject to control.

Allowable Values:

true, false

money_in_transaction

object
Conditionally returned

Defines the original credit transaction (OCT) types that are subject to velocity control.

Allowable Values:

include_credits_types, include_network_load_types

money_in_transaction.include_credits_types

array of strings
Conditionally returned

Specifies the types of credits to include in the original credit transaction (OCT).

Allowable Values:

CASH_DEPOSIT, ALL, NONE

money_in_transaction.include_network_load_types

array of strings
Conditionally returned

Indicates whether or not cash and check network load transactions will be subject to velocity control.

Allowable Values:

ALL, NONE

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:

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.

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.

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

URL path parameters

Fields Description

user_token

string
Required

Unique identifier of the cardholder.

Allowable Values:

Existing user token

URL query parameters

Fields Description

count

integer
Optional

Number of available balance resources to retrieve.

Allowable Values:

1-10

Default value:
5

start_index

integer
Optional

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

Allowable Values:

Any integer

Default value:
0

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:

createdTime, lastModifiedTime, or any field in the resource model

Response body

Fields Description

count

integer
Conditionally returned

Number of velocity control resources retrieved.

This field is returned if there are resources in your returned array.

Allowable Values:

1-10

data

array of objects
Conditionally returned

Array of velocity control objects that include available balances.

Objects are returned as appropriate to your query.

Allowable Values:

Valid array of one or more 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:

card_product_token, user_token

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

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

data[].available

object
Returned

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.

Allowable Values:

amount, days_remaining, uses

data[].available.amount

decimal
Returned

Total amount of spend remaining in the velocity control.

Allowable Values:

0 min

Format: 0.00

data[].available.days_remaining

integer
Conditionally returned

Number of days remaining in the velocity control time window.

Allowable Values:

255 char max

data[].available.uses

integer
Returned

Number of uses remaining in the velocity control.

Allowable Values:

-1 to 100, where -1 indicates unlimited uses

data[].currency_code

string
Returned

Three-character ISO 4217 currency code.

Allowable Values:

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 (OCT) are subject to control.

Allowable Values:

true, false

data[].money_in_transaction

object
Conditionally returned

Defines the original credit transaction (OCT) types that are subject to velocity control.

Allowable Values:

include_credits_types, include_network_load_types

data[].money_in_transaction.include_credits_types

array of strings
Conditionally returned

Specifies the types of credits to include in the original credit transaction (OCT).

Allowable Values:

CASH_DEPOSIT, ALL, NONE

data[].money_in_transaction.include_network_load_types

array of strings
Conditionally returned

Indicates whether or not cash and check network load transactions will be subject to velocity control.

Allowable Values:

ALL, NONE

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:

mcc, mcc_group, mid, or null (no value)

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

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

string
Conditionally returned

Merchant identifier (MID). Identifies a specific merchant.

Enter a value to control spending with a particular merchant.

Allowable Values:

1–36 chars

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

data[].token

string
Conditionally returned

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

Allowable Values:

DAY, WEEK, MONTH, LIFETIME, TRANSACTION

end_index

integer
Conditionally returned

Sort order index of the last resource in the returned array.

This field is returned if there are resources in your returned array.

Allowable Values:

Any integer

is_more

boolean
Conditionally returned

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.

Allowable Values:

true, false

start_index

integer
Conditionally returned

Sort order index of the last resource in the returned array.

This field is returned if there are resources in your returned array.

Allowable Values:

Any integer

Sample response body

JSON
Copied

Is this helpful?

Yes
No

Subscribe to our developer newsletter