Skip to main content
The Marqeta platform enables you to create controls for limiting user spending. A user represents the cardholder to whom one or more cards are associated. You can apply spend controls to one or more users. Use multiple controls to create robust rules for your users. You can control a user’s spending based on:
  • Where the user spends (individual merchants, merchant groups, or merchant categories).
  • How much the user spends (transaction amount and frequency of spending in a given time period).
  • How much the user spends at a specific merchant or category of merchants.
The platform also allows you to update and list existing controls. For a complete description of the /authcontrols endpoint, see the Authorization Controls API reference page. For a complete description of the /velocitycontrols endpoint, see the Velocity Controls API reference page. At the end of this guide, you should understand:
  • How to create new spend controls (authorization and velocity controls).
  • How controls are applied at the program, card product, and user levels.
  • How controls are evaluated at transaction time.

​
Prerequisites

  • Read the Core API Quick Start.
  • Obtain a card product token and a token for an active card that is associated with that card product.

​
Concepts

​
Levels of control

The Marqeta platform enables you to create controls that apply to an individual user or to a set of users associated with a specific card product. Marqeta can create additional program-level controls, which apply to all users. Multiple controls can be applied at each level to control how, when, and where your users spend with their cards. To define the level to which your control applies, your API request must include an association object. The association object requires one of the following:
  • Card product token – The card product to which the control applies.
  • User token – The user to which the control applies.
Tip
Program-level controls have an empty association object. While you can create controls of this type in the public/private sandbox, only Marqeta can create and update program-level controls in production. You can retrieve program-level controls in both production and in the sandbox.
Levels of control

​
Program-level controls

Program-level controls are global and apply to every card product and user in your environment. These controls cannot be created in production environments. You will work with Marqeta to define program-level controls for your program, often based on the requirements of the issuing bank. The controls you create must operate within the bounds of the controls created by Marqeta. Marqeta also helps you define other program-specific configurations based on technical and bank requirements specific to your implementation. To review configurations for your program, contact your Marqeta representative.

​
Card product-level controls

Card product-level controls apply to a collection of cards sharing the same properties. They apply to all users with cards associated with that card product. To define a control at the card product level, include a card product token in the association object. Marqeta also helps you define other card product-specific configurations based on technical and bank requirements specific to your implementation.
Note
Controls cannot be applied to individual cards.

​
User-level controls

User-level controls apply to a single user—the cardholder. To define a control at the user level, include a user token in the association object.

​
Controls to limit where users can spend

To limit where users can spend funds, use authorization controls. Authorization controls allow you to pick the merchants where users can (or cannot) spend their funds. In the API request, the merchant_scope object defines the merchant or group of merchants affected by the authorization control. The object requires one (and only one) of the following identifiers:
  • Merchant ID – A unique identifier for a single merchant.
  • Merchant Category Code (MCC) – A unique identifier for a type of goods or services provided by a set of merchants.
  • MCC Group – A unique identifier for a group of merchant category codes.
Note
For a comprehensive MCC listing, refer to page 24 of the Visa Merchant Data Standards Manual or page 36 of the Mastercard Quick Reference Booklet—Merchant Edition.
Your program’s default authorization behavior can block all merchants by default, requiring you to add allowable merchants to the allow list, or it can allow all merchants by default, requiring you to add blocked merchants to the deny list. Make sure you know your program’s default behavior before designing your controls. There is no distinction between a control that allows or blocks merchants—it is an exception to your program’s default behavior. For example, a control that includes the MCC for hotels (7011) in the merchant_scope object would block hotels under the deny list default behavior, but would allow hotels under the allow list default behavior. You can optionally configure start and end dates for your control to limit spending at merchants for predetermined periods of time. For example, a rewards card might limit a user’s ability to spend outside of specific promotional periods.

​
Best practices for configuring merchant identifiers (MIDs)

When you configure a merchant identifier (MID) in an authorization control, merchant group, or MID exemption, Marqeta performs an exact match between the MID in the incoming transaction and the MID you configured. Marqeta doesn’t normalize, pad, or format either value. To ensure reliable matching:
  • Use the exact MID from your Gateway JIT Funding request or transaction webhook. The mid value in the card_acceptor object of these payloads is the exact value Marqeta uses for authorization control matching. Copy this value exactly when you configure your authorization control, merchant group, or MID exemption.
  • Be aware that MID formats vary by card network and acquirer. The acquiring bank assigns and transmits the MID. Some acquirers left-pad numeric MIDs with zeros (for example, 000001234567890), while others send the MID at its natural length (for example, 1234567890). This means the same merchant can present different MID formats across transactions.
  • Include all observed MID formats in your merchant group. If a merchant sends multiple MID values across transactions (for example, both 1234567890 and 000001234567890), add all observed forms to your merchant group so the platform matches all transactions from that merchant.
Example A merchant’s MID can appear differently depending on the card network and acquirer:
Transaction webhook from Mastercard (acquirer A):
Transaction webhook from Mastercard (acquirer B, same merchant):
To match both transactions to the same merchant group, include both MID values:
JSON

​
Controls to limit amount and frequency of spending

To limit the amount or frequency of spending, use velocity controls. Velocity controls allow you to set how much users can spend and/or the number of transactions they can make within a given window of time. The configurable parameters for velocity controls include:
  • Amount limit – The maximum amount the user can spend in a given window of time (such as $200 per day, $1000 per month). This limit applies to the initial authorization. Refunds and reversals cannot exceed the limit set in the velocity window. In some circumstances, such as automated fuel dispenser (AFD) transactions, the final clearing amount might be higher than the initial authorization, exceeding your intended amount limit.
  • Usage limit – The maximum number of transactions the user can make in a given window of time (such as three transactions per day, ten transactions per month).
  • Velocity window – The window of time over which the control applies (such as per day, per week, per month, forever, per transaction).
  • Transaction types – The type of transactions to which the control applies (such as retail purchases, ATM withdrawals, bank transfers).
  • Merchant scope – The merchant or group of merchants to which the control applies (such as MID 12345).
Note
If a velocity-controlled transaction is refunded, the refunded amount is reinstated to the amount limit, but the transaction still counts against the usage limit. The refunded amount cannot exceed the velocity control amount limit.Consider the case where a cardholder has an amount limit of $100 per day and a usage limit of 3 transactions per day: if the cardholder spends $100 in a single transaction and that transaction is subsequently refunded $50, the cardholder’s amount limit is refreshed, but the usage limit is still decremented by 1. The cardholder can still spend another $50 that day, but can only perform 2 more transactions. If the cardholder gets another refund for $75 from a transaction the previous day, they can still only spend up to $100, not $125, because refunds cannot increase their velocity control limit above the specified amount.

​
Authorization controls vs. velocity controls

Authorization and velocity controls share some attributes and behaviors, but they serve distinct purposes.
  • Authorization controls block (or allow) transactions at one or more merchants, regardless of the amount or frequency of spending. For example, you can block your users from spending at a grocery store for all time or block them for a specific period of time, but you cannot limit the spending amount within that time period using an authorization control.
  • Velocity controls limit transactions at one or more merchants based on a velocity window. For example, you can limit spending at grocery stores to a maximum of $100 each week.

​
Controls at transaction time

When a user attempts to spend with a card, the Marqeta platform evaluates the transaction against all controls applied to that user, including controls applied at the program and card product levels. If the details of the transaction violate any of the controls, the transaction fails.
Controls at transactions time
The following transactions do not apply to the limits defined in a velocity control:
  • Declined authorizations
  • Account verification authorizations
The effects of all velocity controls are user specific. If a card product has a velocity control limiting users to $100 of spending each day, then each associated user can spend $100. They are not impacted by the spending of other users, even if they share a parent account. If a user owns multiple cards, spend controls apply in the following ways:
  • If a user has multiple cards associated with the same card product, then spending on any of those cards counts toward any velocity controls applied to that card product. In other words, all of the user’s cards share the card product’s velocity control.
  • If a user has multiple cards associated with different card products and you have implemented velocity controls at the program level, then spending on one card counts toward all the velocity controls applied across all the card products within your program. In other words, spending on a card associated with Card Product A affects the limits of a card associated with Card Product B.
  • A velocity control applied to a user always affects all of the user’s cards.
For more information about how many cards a user can own, see About Cards.
Note
When using a card funded using Just-in-Time (JIT) Funding, every spend event has a matching load event that returns the account balance to zero. Load controls operate similarly to spend controls—they limit the amount and frequency of funds that can be added to an account. To understand the load controls applied to your program, contact your Marqeta representative. To learn more about JIT Funding, see About Just-in-Time Funding.