How to configure spend controls

The following tutorial walks you through creating and testing a control in the public or private sandbox environment. You will create an authorization control that prevents users of your new card product from spending at liquor stores, which are represented by a single merchant category code. If you want to test these controls after you create them, make sure to track the user and card product tokens you specify throughout the tutorial.

Step 1 — List existing controls

Before creating a new control, consider any existing controls you might have at the program and card product levels. To view existing authorization controls, send a GET request to the /authcontrols endpoint. Make sure you understand your program’s default authorization behavior (allow vs. deny). In the public/private sandbox environment, the program’s default behavior is set to globally allow transactions at all merchants.

Step 2 — Design your controls

The business logic of the control you want to add determines the data you include in your request.

To block spending at all liquor stores, include the merchant category code in the merchant_scope object.
To apply the control to all users in your card product, include the card product token in the association object.

To avoid receiving an error, include all other necessary parameters.

Create a meaningful name for the control: e.g. Deny Liquor Stores.
Create a unique token for the control: e.g. deny_liquor_stores.

Warning
Do not use the example tokens shown in the tutorial while working in your public or private sandbox environment. If an object with the same token already exists, the system will handle the request as a duplicate, and your request will not take effect.

Step 3 — Set up the authorization controls

The following code block provides a JSON-formatted sample message body for creating your control. Copy the code sample and paste it into the body field of your POST /authcontrols request. Replace any placeholder text (**UNIQUE TOKEN**, **CARD PRODUCT TOKEN**) with your sample data, then submit the request. Review the response to ensure you successfully created the authorization control.

JSON

{
  "token": "**UNIQUE TOKEN**",
  "name": "Deny Liquor Stores",
  "association": {
    "card_product_token": "**CARD PRODUCT TOKEN**"
  },
  "merchant_scope": {
    "mcc": "5921"
  },
  "active": true
}

Alternatively, you can use the following sample cURL to create the same control.

cURL

curl \
-X POST \
--header 'Content-Type: application/json' \
--header 'Accept: application/json' \
--header 'Authorization: Basic **YOUR AUTHORIZATION STRING**' \
-d '{
  "token": "**UNIQUE TOKEN**",
  "name": "Deny Liquor Stores",
  "association": {
    "card_product_token": "**CARD PRODUCT TOKEN**"
  },
  "merchant_scope": {
    "mcc": "5921"
  },
  "active": true
}' \
'https://sandbox-api.marqeta.com/v3/authcontrols'

Step 4 — Confirm the new control exists

To confirm that you created the control, send a GET request to the /authcontrols endpoint using the card product token you used previously. Replace any placeholder text (**CARD PRODUCT TOKEN**) with your sample data. Your new control should be included in the returned list.

HTML

https://sandbox-api.marqeta.com/v3/authcontrols?card_product=**CARD PRODUCT TOKEN**&count=5&sort_by=-lastModifiedTime

Step 5 — Call the /simulations/cardtransactions endpoint

To test if the control functions properly, simulate an authorization transaction by sending a POST request to the /simulations/cardtransactions/authorization endpoint. Test several transactions that each force the Marqeta platform to allow or deny them. The following sample message body creates a transaction that the Marqeta platform denies because of the authorization control created in the tutorial. Replace any placeholder text (**YOUR CARD TOKEN**) with your sample data. Change the MCC and resubmit the request to simulate a transaction that Marqeta allows.

Tip
Ensure that the card token you enter in the message body references a sample card that is active and funded, otherwise the transaction will be declined due to lack of activation or insufficient funds.

JSON

{
  "amount": "100",
  "card_token": "**YOUR CARD TOKEN**",
  "card_acceptor": {
    "mid": "12345",
    "mcc": "5921"
  },
  "network": "VISA"
}

Tip
If the transaction result is unexpected, check the response body for details on what went wrong.

Samples

Use the following samples to help build your program’s spend controls. Each sample includes a description of the use case and sample JSON and cURL code snippets.

Allow user spending at a single merchant

You can limit a user’s spending to a single merchant. This is handy if you are creating a rewards card that should only be used at a specific retailer or service. (Depending on your program’s default authorization behavior, the same control could be used to block spending at a single merchant.)

JSON

{
  "token": "**UNIQUE TOKEN**",
  "name": "Only Dunkin Donuts",
  "association": {
    "user_token": "**USER TOKEN REQUIRED**"
  },
  "merchant_scope": {
    "mid": "252824676910001"
  },
  "active": true
}

cURL

curl \
-X POST \
--header 'Content-Type: application/json' \
--header 'Accept: application/json' \
--header 'Authorization: Basic **YOUR AUTHORIZATION STRING**' \
-d '{
  "token": "**UNIQUE TOKEN**",
  "name": "Only Dunkin Donuts",
  "association": {
    "user_token": "**USER TOKEN REQUIRED**"
  },
  "merchant_scope": {
    "mid": "252824676910001"
  },
  "active": true
}' \
'https://sandbox-api.marqeta.com/v3/authcontrols'

Limit spending to $100 per day

Using a velocity control, you can cap the amount a user spends in a given timeframe. If, for example, you know your cardholders shouldn’t spend more than $100 per day, you could use a velocity control to deny any transactions beyond that limit.

JSON

{
  "token": "**UNIQUE TOKEN**",
  "name": "100 Daily Spend Limit",
  "association": {
    "user_token": "**USER TOKEN**"
  },
  "usage_limit": 100,
  "currency_code": "USD",
  "amount_limit": 100,
  "velocity_window": "DAY",
  "active": true
}

cURL

curl \
-X POST \
--header 'Content-Type: application/json' \
--header 'Accept: application/json' \
--header 'Authorization: Basic **YOUR AUTHORIZATION STRING**' \
-d '{
  "token": "**UNIQUE TOKEN**",
  "name": "100 Daily Spend Limit",
  "association": {
    "user_token": "**USER TOKEN**"
  },
  "usage_limit": 100,
  "currency_code": "USD",
  "amount_limit": 100,
  "velocity_window": "DAY",
  "active": true
}' \
'https://sandbox-api.marqeta.com/v3/velocitycontrols'

Limit spending to $100 per transaction

You can limit a user’s per-transaction spending by creating a velocity control with the velocity_window field set to TRANSACTION.

JSON

{
  "token": "**UNIQUE TOKEN**",
  "name": "100 Per Transaction Limit",
  "association": {
    "user_token": "**USER TOKEN**"
  },
  "currency_code": "USD",
  "amount_limit": 100,
  "velocity_window": "TRANSACTION",
  "active": true
}

cURL

curl \
-X POST \
--header 'Content-Type: application/json' \
--header 'Accept: application/json' \
--header 'Authorization: Basic **YOUR AUTHORIZATION STRING**' \
-d '{
  "token": "**UNIQUE TOKEN**",
  "name": "100 Per Transaction Limit",
  "association": {
    "user_token": "**USER TOKEN**"
  },
  "currency_code": "USD",
  "amount_limit": 100,
  "velocity_window": "TRANSACTION",
  "active": true
}' \
'https://sandbox-api.marqeta.com/v3/velocitycontrols'

Limit users to one transaction per week at a category of merchants

You can limit a user’s maximum number of transactions for a given time period. For example, you can create a limited-use card product that prevents users from spending too frequently at a given merchant or category of merchants, such as hotels and motels. This is handy if you know how frequently a cardholder should be spending with their card.

JSON

{
  "token": "**UNIQUE TOKEN**",
  "name": "One Transaction Per Week at Hotels",
  "association": {
    "card_product_token": "**CARD PRODUCT TOKEN REQUIRED**"
  },
  "merchant_scope": {
    "mcc": "7011"
  },
  "usage_limit": "1",
  "currency_code": "USD",
  "amount_limit": 1000,
  "velocity_window": "WEEK",
  "active": true
}

cURL

curl \
-X POST \
--header 'Content-Type: application/json' \
--header 'Accept: application/json' \
--header 'Authorization: Basic **YOUR AUTHORIZATION STRING**' \
-d '{
  "token": "**UNIQUE TOKEN**",
  "name": "One Transaction Per Week At Hotels",
  "association": {
    "card_product_token": "**CARD PRODUCT TOKEN REQUIRED**"
  },
  "merchant_scope": { "mcc": "7011" },
  "usage_limit": 1,
  "currency_code": "USD",
  "amount_limit": 1000,
  "velocity_window": "WEEK",
  "active": true
}' \
'https://sandbox-api.marqeta.com/v3/velocitycontrols'

Limit users to a single purchase

You can add a velocity control that allows a user to spend exactly once. By setting the usage limit to one (a single transaction) and the velocity window to lifetime, users can spend up to the amount limit once. Any future attempts to spend are blocked.

JSON

{
  "token": "**UNIQUE TOKEN**",
  "name": "Single Use Card",
  "association": {
    "card_product_token": "**CARD PRODUCT TOKEN REQUIRED**"
  },
  "usage_limit": 1,
  "currency_code": "USD",
  "amount_limit": 1000,
  "velocity_window": "LIFETIME",
  "active": true
}

cURL

curl \
-X POST \
--header 'Content-Type: application/json' \
--header 'Accept: application/json' \
--header 'Authorization: Basic **YOUR AUTHORIZATION STRING**' \
-d '{
  "token": "**UNIQUE TOKEN**",
  "name": "Single Use Card",
  "association": {
    "card_product_token": "**CARD PRODUCT TOKEN**"
  },
  "usage_limit": 1,
  "currency_code": "USD",
  "amount_limit": 1000,
  "velocity_window": "LIFETIME",
  "active": true
}' \
'https://sandbox-api.marqeta.com/v3/velocitycontrols'

Limit ATM withdrawals and bank transfers

You can create a velocity control to limit the funds users can withdraw from ATMs or transfer from a bank. By setting the spending limit for ATMs and bank transfers to $0, the user can only make retail purchases.

JSON

{
  "token": "**UNIQUE TOKEN**",
  "name": "No ATMS or Bank Transfers",
  "association": {
    "user_token": "**USER TOKEN REQUIRED**"
  },
  "usage_limit": 100,
  "approvals_only": true,
  "include_purchases": false,
  "include_cashbacks": false,
  "include_withdrawals": true,
  "include_transfers": true,
  "currency_code": "USD",
  "amount_limit": 0,
  "velocity_window": "MONTH",
  "active": true
}

cURL

curl \
-X POST \
--header 'Content-Type: application/json' \
--header 'Accept: application/json' \
--header 'Authorization: Basic **YOUR AUTHORIZATION STRING**' \
-d '{
  "token": "**UNIQUE TOKEN**",
  "name": "No ATMS or Bank Transfers",
  "association": {
    "user_token": "**USER TOKEN**"
  }, "usage_limit": 100,
  "approvals_only": true,
  "include_purchases": false,
  "include_cashbacks": false,
  "include_withdrawals": true,
  "include_transfers": true,
  "currency_code": "USD",
  "amount_limit": 0,
  "velocity_window": "MONTH",
  "active": true
}' \
'https://sandbox-api.marqeta.com/v3/velocitycontrols'

List all velocity controls for a single user

You can retrieve a list of all velocity controls applied at the program level, or use a query parameter to filter the list of controls by user or card product.

HTML

https://sandbox-api.marqeta.com/v3/velocitycontrols?user=**USER TOKEN REQUIRED**

cURL

curl \
-X GET \
--header 'Accept: application/json' \
--header 'Authorization: Basic **YOUR AUTHORIZATION STRING**' \
'https://sandbox-api.marqeta.com/v3/velocitycontrols?user=**USER TOKEN REQUIRED**'

Platform Overview

Program Administration

Card Issuing

Card Processing

Data & Reporting

Accounts & Money Movement

Risk, Fraud, & Disputes

Cardholder User Experience

Marqeta in Europe

How to configure spend controls

Step 1 — List existing controls

Step 2 — Design your controls

Step 3 — Set up the authorization controls

Step 4 — Confirm the new control exists

Step 5 — Call the /simulations/cardtransactions endpoint

Samples

Allow user spending at a single merchant

Limit spending to $100 per day

Limit spending to $100 per transaction

Limit users to one transaction per week at a category of merchants

Limit users to a single purchase

Limit ATM withdrawals and bank transfers

List all velocity controls for a single user

​Step 1 — List existing controls

​Step 2 — Design your controls

​Step 3 — Set up the authorization controls

​Step 4 — Confirm the new control exists

​Step 5 — Call the /simulations/cardtransactions endpoint

​Samples

​Allow user spending at a single merchant

​Limit spending to $100 per day

​Limit spending to $100 per transaction

​Limit users to one transaction per week at a category of merchants

​Limit users to a single purchase

​Limit ATM withdrawals and bank transfers

​List all velocity controls for a single user

Step 1 — List existing controls

Step 2 — Design your controls

Step 3 — Set up the authorization controls

Step 4 — Confirm the new control exists

Step 5 — Call the /simulations/cardtransactions endpoint

Samples

Allow user spending at a single merchant

Limit spending to $100 per day

Limit spending to $100 per transaction

Limit users to one transaction per week at a category of merchants

Limit users to a single purchase

Limit ATM withdrawals and bank transfers

List all velocity controls for a single user