# Card controls
You can apply one or multiple [spending controls](https://www.checkout.com/docs/card-issuing/manage-controls.md) to a specific card to restrict spending to:
- Certain types of business, using the merchant category code (MCC)
- Specific merchants, using the merchant identifier (MID)
- A certain velocity – that is, how much the card can spend within a given timeframe
You can also add MCCs or MIDs to a velocity control. For example, to allow a card to spend a maximum of 500 EUR per month at food businesses.
---
## How it works
1. Retrieve the card ID you want to apply controls to.
2. Apply an MCC, MID, or velocity control.
You can then:
- View all controls applied to a card.
- Retrieve the details of a specific control.
- Update a control.
- Delete a control.
### Immutable controls
Checkout.com may apply certain controls to a card (or [card product](https://www.checkout.com/docs/card-issuing/manage-controls/card-product-controls.md#Immutable_controls)) that help protect you and us against fraud, and maintain a healthy spending budget.
You cannot update or delete immutable controls. However, you can apply stricter controls within the limits of the immutable control.
For example, if Checkout.com has applied an immutable maximum lifetime spending limit of 100 EUR to a card, you can apply a limit of 80 EUR but not 150 EUR.
To check if a specific control is immutable, [retrieve the control details](#Retrieve_control_details) via the API.
For more information about immutable controls applied to a card, contact your account manager or [request support](https://dashboard.checkout.com/support/new?topic=case_account_management_and_access&issue=issue_account_changes).
### Control hierarchy
If multiple controls apply to a card, the strictest control always overrides any others.
In the following example, the second control overrides the first control:
- Allow the card to spend up to 500 EUR per month at food MCCs.
- Limit the card's overall spending to 400 EUR per month.
### Cumulative allow controls
If multiple _Allow_ controls apply to a card, they are applied cumulatively. That is, they do not block each other in order to avoid declined transactions.
This applies:
- To MID and MCC controls
- When all the controls are created by the same owner – the owner can be you or Checkout.com
- Whether the controls are applied at card level, or inherited from a [control profile](https://www.checkout.com/docs/card-issuing/manage-controls/card-control-profiles.md) or card product
For example, you create a control targeting a control profile that allows spending at airline and hotel MCCs only.
You later apply another control to a specific card linked to that profile that allows spending for taxi MCCs only.
Both controls cumulatively apply to the card, so it can only spend at airline, hotel, and taxi MCCs.
### Control retroactivity
Controls are not retroactive. Transactions approved before a control is applied are not affected by the control.
---
## Retrieve card ID
To apply controls to a card, retrieve the card ID to set as the control target. For example, `crd_abcdef1ghijklmn23opq45r6st`. You can do this using the Dashboard and the API.
### Retrieve card ID in the Dashboard
1. Sign in to the [Dashboard](https://dashboard.checkout.com/).
2. Go to _Issuing_ > _Cards_.
3. Find the card you want to apply the control to by searching or using filters, and select it.
The _Card details_ page opens.
4. On the _About_ tab, under _About this card_, copy the card ID.
### Retrieve card ID using the API
If you've just [created a card](https://www.checkout.com/docs/card-issuing/issue-a-card.md), the card ID is returned in the response's `id` field.
Alternatively, to retrieve a list of cards issued to a specific cardholder, call the [Get a cardholder's cards](https://api-reference.checkout.com/tag/Cardholders/#operation/getCardholderCards) endpoint.
Provide the `{cardholderId}` in the path. For example, `crh_abcdef1ghijklmn23opq45r6st`.
> **Information**
>
> Your base URL's `{prefix}` value is unique to your account and environment. To learn how to retrieve your base URLs for the sandbox and production environments, see [API endpoints](https://www.checkout.com/docs/developer-resources/api/api-endpoints.md).
**Production**
`GET` `https://{prefix}.api.checkout.com/issuing/cardholders/{cardholderId}/cards`
**Sandbox**
`GET` `https://{prefix}.api.sandbox.checkout.com/issuing/cardholders/{cardholderId}/cards`
### Response example
The response returns a list of all the cardholder's cards.
Make a note of the card `id` you want to apply controls to.
```json
{
"cards":[
{
"id":"crd_fa6psq242dcd6fdn5gifcq1491",
"cardholder_id":"crh_d3ozhf43pcq2xbldn2g45qnb44",
"card_product_id":"pro_7syjig3jq3mezlc3vjrdpfitl4",
"client_id":"cli_vkuhvk4vjn2edkps7dfsq6emqm",
"last_four":1234,
"expiry_month":5,
"expiry_year":2025,
"status":"active",
"display_name":"John Smith",
"type":"virtual",
"billing_currency":"USD",
"issuing_country":"US",
"reference":"X-123456-N11",
"created_date":"2021-09-09T19:41:39Z",
"last_modified_date":"2021-09-09T19:41:39Z"
}
]
}
```
---
## Apply MCC controls
MCC controls restrict the types of business the card can spend at, by providing a list of [merchant category codes](https://www.checkout.com/docs/developer-resources/codes/merchant-category-codes.md) (MCCs) to either allow or block.
For example, you can block all authorization requests from gambling institutions. You can apply them using the Dashboard and the API.
### Apply MCC controls in the Dashboard
1. Sign in to the [Dashboard](https://dashboard.checkout.com/).
2. Go to _Issuing_ > _Cards_.
3. Find the card you want to apply the control to by searching or using filters, and select it.
4. In the _Card details_ page that appears, go to the _Controls_ tab.
5. Select _Add control_ > _Allow or block categories_.
6. In the _Restrict categories_ window that opens:
- To block specific MCCs, select _Allow all except_, and under _Allowed categories_, select one or multiple MCCs.
- To allow specific MCCs, select _Block all except_, and under _Allowed categories_, select one or multiple MCCs.
7. Select _Confirm_ to save.
### Apply MCC controls using the API
Call the [Create a control](https://api-reference.checkout.com/tag/Controls/#operation/createControl) endpoint:
- Optionally, provide a description for the control.
- Set the `control_type` field to `mcc_limit`.
- Set the `target_id` field to the card `id` to apply the control to.
- In the `mcc_limit` object:
- Set the `type` field to the `allow` or `block` the MCCs.
- In the `mcc_list` field, list the relevant MCCs.
> **Information**
>
> While you can use multiple rules to specify which MCCs to block, you can only use one rule to specify which MCCs to allow.
> If you need to update an MCC control's allowlist, [update the control](#Update_controls) itself.
> **Information**
>
> Your base URL's `{prefix}` value is unique to your account and environment. To learn how to retrieve your base URLs for the sandbox and production environments, see [API endpoints](https://www.checkout.com/docs/developer-resources/api/api-endpoints.md).
**Production**
`POST` `https://{prefix}.api.checkout.com/issuing/controls`
**Sandbox**
`POST` `https://{prefix}.api.sandbox.checkout.com/issuing/controls`
### Request example
```json
{
"description":"Block all gambling transactions",
"control_type":"mcc_limit",
"target_id":"crd_fa6psq42dcdd6fdn5gifcq1491",
"mcc_limit":{
"type":"block",
"mcc_list":[
"7994",
"7995"
]
}
}
```
### Response example
The response returns the control details and the control ID. For example, `ctr_abcdef1ghijklmn23opq45r6st`.
```json
{
"mcc_limit":{
"type":"block",
"mcc_list":[
"7994",
"7995"
]
},
"id":"ctr_ixy6g5hndwuudmuz5tsgct36ae",
"description":"Block all gambling transactions",
"control_type":"mcc_limit",
"target_id":"crd_fa6psq42dcdd6fdn5gifcq1491",
"created_date":"2023-03-15T07:02:15.840206Z",
"last_modified_date":"2023-03-15T07:02:15.840206Z"
}
```
---
## Apply MID controls
MID controls restrict the card to only spend at specific merchants, by providing a list of merchant IDs (MIDs) to either allow or block.
For example, you can block all authorization requests coming from an unapproved supplier.
You can apply MID controls using the API. Call the [Create a control](https://api-reference.checkout.com/tag/Controls/#operation/createControl) endpoint:
- Optionally, provide a description for the control.
- Set the `control_type` field to `mid_limit`.
- Set the `target_id` field to the card `id` to apply the control to.
- In the `mid_limit` object:
- Set the `type` field to the `allow` or `block` the MIDs.
- In the `mid_list` field, list the relevant MIDs.
> **Information**
>
> Your base URL's `{prefix}` value is unique to your account and environment. To learn how to retrieve your base URLs for the sandbox and production environments, see [API endpoints](https://www.checkout.com/docs/developer-resources/api/api-endpoints.md).
**Production**
`POST` `https://{prefix}.api.checkout.com/issuing/controls`
**Sandbox**
`POST` `https://{prefix}.api.sandbox.checkout.com/issuing/controls`
### Request example
```json
{
"description":"Allow the card to be used only in AZ Pizza",
"control_type":"mid_limit",
"target_id":"crd_fa6psq42dcdd6fdn5gifcq1491",
"mid_limit":{
"type":"allow",
"mid_list":[
"593278",
"541114"
]
}
}
```
### Response example
The response returns the control details and the control ID. For example, `ctr_abcdef1ghijklmn23opq45r6st`.
```json
{
"id": "ctr_gp7vkmxayztufjz6top5bjcdra",
"description": "Allow the card to be used only in AZ Pizza",
"control_type": "mid_limit",
"target_id": "crd_fa6psq42dcdd6fdn5gifcq1491",
"created_date": "2023-03-12T18:20:12Z",
"last_modified_date": "2023-03-12T18:20:12Z",
"mid_limit": {
"type": "allow",
"mid_list": [
"593278",
"541114"
]
}
}
```
---
## Apply velocity controls
A velocity control limits how much a card can spend within a given timeframe. You can apply them using the Dashboard and the API.
> **Note**
>
> After you create a velocity control, you cannot change the timeframe.
> **Information**
>
> For information about velocity controls at the card-product level, see [Card-product controls](https://www.checkout.com/docs/card-issuing/manage-controls/card-product-controls.md).
### Velocity by MCC and MID
You can also add specific MCCs and MIDs to a velocity control. The control is then applied separately to each MCC or MID listed.
For example, if a control applies a limit of 500 EUR per month for MCCs `7995` and `7994`, the card's total spending limit is 1000 EUR.
That is, 500 EUR for `7995` and 500 EUR for `7994`.
### Replacement velocity controls
If you delete a velocity control from a card and then apply a new one, the remaining spend amount is reset and tracked according to the new control.
### Refunds and velocity controls
Velocity limits are not reset when a refund is processed.
For example, if a card has a velocity limit of 100 EUR per month and spends 60 EUR, the remaining limit is 40 EUR.
The 60 EUR is refunded, but the remaining limit is still 40 EUR.
### Apply velocity controls in the Dashboard
1. Sign in to the [Dashboard](https://dashboard.checkout.com/).
2. Go to _Issuing_ > _Cards_.
3. Find the card you want to apply the control to by searching or using filters, and select it.
4. In the _Card details_ page that appears, go to the _Controls_ tab.
5. Select _Add control_ > _Add a velocity control_.
6. In the _Velocity control_ window that opens:
- In the _Amount limit_ box, enter the amount the card can spend.
- From the _Time period_ dropdown, select the timeframe for spending the amount: `All time`, `Daily`, `Weekly`, or `Monthly`.
7. Under _Applies to_, select one of the following:
- _All spending_ – Apply the control to all business types.
- _Specific categories_ – From the dropdown, select one or multiple MCCs to apply the control to.
8. Select _Confirm_ to save.
### Apply velocity controls using the API
Call the [Create a control](https://api-reference.checkout.com/tag/Controls/#operation/createControl) endpoint:
- Optionally, provide a description for the control.
- Set the `control_type` field to `velocity_limit`.
- Set the `target_id` field to the card `id` to apply the control to.
- In the `velocity_limit` object:
- Set the `amount_limit` field to the amount the card can spend.
- Set the `velocity_window.type` field to the timeframe for spending the amount: `all_time` for no specific timeframe, or `daily`, `monthly`, or `weekly`.
- Optionally, apply the velocity control either to specific merchant category codes in the `mcc_list` field, or to specific merchant IDs in the `mid_list` field (but not both).
> **Information**
>
> Your base URL's `{prefix}` value is unique to your account and environment. To learn how to retrieve your base URLs for the sandbox and production environments, see [API endpoints](https://www.checkout.com/docs/developer-resources/api/api-endpoints.md).
**Production**
`POST` `https://{prefix}.api.checkout.com/issuing/controls`
**Sandbox**
`POST` `https://{prefix}.api.sandbox.checkout.com/issuing/controls`
### Request example
```json
{
"description":"Limit food spend to €500 per month",
"control_type":"velocity_limit",
"target_id":"crd_fa6psq42dcdd6fdn5gifcq1491",
"velocity_limit":{
"amount_limit":500,
"velocity_window":{
"type":"monthly"
},
"mcc_list":[
"5812",
"5814"
]
}
}
```
### Response example
The response returns the control details and the control ID. For example, `ctr_abcdef1ghijklmn23opq45r6st`.
```json
{
"id":"ctr_gp7vkmxayztufjz6top5bjcdra",
"description":"Limit food spend to €500 per month",
"control_type":"velocity_limit",
"target_id":"crd_fa6psq42dcdd6fdn5gifcq1491",
"created_date":"2023-03-12T18:20:12Z",
"last_modified_date":"2023-03-12T18:20:12Z",
"velocity_limit":{
"amount_limit":500,
"velocity_window":{
"type":"monthly"
},
"mcc_list":[
"5812",
"5814"
]
}
}
```
---
## View card controls
You can view all controls applied to a card using the Dashboard and the API.
### View card controls in the Dashboard
1. Sign in to the [Dashboard](https://dashboard.checkout.com/).
2. Ensure you have the [Admin](https://www.checkout.com/docs/business-operations/use-the-dashboard/manage-users/user-permissions.md#Pre-defined_roles) role, or ask an Admin to [give you permissions](https://www.checkout.com/docs/card-issuing/manage-cards/display-card-details.md#Grant_user_permissions_to_view_card_details).
3. Go to _Issuing_ > _Cards_.
4. Find the card you want to view by searching or using filters, and select it.
5. On the _Card details_ page, go to the _Controls_ tab to view the card's controls.
> **Information**
>
> [Immutable controls](https://www.checkout.com/docs/card-issuing/manage-controls/card-product-controls.md#Immutable_controls) are not displayed.
### View card controls using the API
Call the [Get controls by target](https://api-reference.checkout.com/tag/Controls/#operation/getControlByTarget) endpoint, and provide the card `id` as the `target_id` query parameter.
> **Information**
>
> Your base URL's `{prefix}` value is unique to your account and environment. To learn how to retrieve your base URLs for the sandbox and production environments, see [API endpoints](https://www.checkout.com/docs/developer-resources/api/api-endpoints.md).
**Production**
`GET` `https://{prefix}.api.checkout.com/issuing/controls?target_id=crd_abcdef1ghijklmn23opq45r6st`
**Sandbox**
`GET` `https://{prefix}.api.sandbox.checkout.com/issuing/controls?target_id=crd_abcdef1ghijklmn23opq45r6st`
### Response example
The response returns a JSON object for each control and its details.
For [velocity controls](#Apply_velocity_controls), it also returns the remaining amount available to spend.
```json
{
"controls":[
{
"id":"ctr_gp7vkmxayztufjz6top5bjcdra",
"target_id":"crd_fa6psq42dcdd6fdn5gifcq1491",
"description":"Maximum spend of 500€ per week for restaurants",
"control_type":"velocity_limit",
"created_date":"2021-09-09T19:41:39Z",
"last_modified_date":"2021-09-09T19:41:39Z",
"velocity_limit":{
"amount_remaining":45000,
"amount_limit":50000,
"velocity_window":{
"type":"weekly"
},
"mcc_list":[
"4121",
"4582"
]
}
}
]
}
```
---
## Retrieve control details
To retrieve the details of a specific control using the API, call the [Get control details](https://api-reference.checkout.com/tag/Controls/#operation/getControl) endpoint, and provide the `{controlId}` in the path.
> **Information**
>
> Your base URL's `{prefix}` value is unique to your account and environment. To learn how to retrieve your base URLs for the sandbox and production environments, see [API endpoints](https://www.checkout.com/docs/developer-resources/api/api-endpoints.md).
**Production**
`GET` `https://{prefix}.api.checkout.com/issuing/controls/{controlId}`
**Sandbox**
`GET` `https://{prefix}.api.sandbox.checkout.com/issuing/controls/{controlId}`
### Response example
The response returns the control details.
- For [velocity controls](#Apply_velocity_controls), it returns the remaining amount available to spend.
- If the `is_editable` boolean is set to:
- `false` – It's an [immutable control](#Immutable_controls) applied by Checkout.com.
- `true` – You applied the control and can update it.
```json
{
"id":"ctr_gp7vkmxayztufjz6top5bjcdra",
"target_id":"crd_fa6psq42dcdd6fdn5gifcq1491",
"description":"Maximum spend of 500€ per week for restaurants",
"control_type":"velocity_limit",
"created_date":"2021-09-09T19:41:39Z",
"last_modified_date":"2021-09-09T19:41:39Z",
"velocity_limit":{
"amount_remaining":45000,
"amount_limit":50000,
"velocity_window":{
"type":"weekly"
},
"mcc_list":[
"4121",
"4582"
],
"mid_list":null
},
"is_editable":false
}
```
---
## Update a control
You can update a specific control – For example, you can change the amount of a velocity control, or allow or block different MCCs or MIDs. You can do this using the Dashboard and the API.
> **Note**
>
> You cannot:
> - Change the timeframe of velocity controls after creation.
> - Make changes outside the limits of [immutable controls](https://www.checkout.com/docs/card-issuing/manage-controls/card-product-controls.md#Immutable_controls).
### Update a control in the Dashboard
1. Sign in to the [Dashboard](https://dashboard.checkout.com/).
2. Go to _Issuing_ > _Cards_.
3. Find the card you want to update the control for by searching or using filters, and select it.
4. On the _Card details_ page, go to the _Controls_ tab.
5. Find the control you want to update and select _Edit_.
6. Update the required details.
7. Select _Confirm_ to save.
### Update a control using the API
Call the [Update a control](https://api-reference.checkout.com/tag/Controls/#operation/updateControl) endpoint:
- Provide the `{control_id}` you want to update in the path.
- Optionally, update the control `description` field.
- Update the control in the `mcc_limit`, `mid_limit`, or `velocity_limit` object as needed.
> **Information**
>
> Your base URL's `{prefix}` value is unique to your account and environment. To learn how to retrieve your base URLs for the sandbox and production environments, see [API endpoints](https://www.checkout.com/docs/developer-resources/api/api-endpoints.md).
**Production**
`PUT` `https://{prefix}.api.checkout.com/issuing/controls/{control_id}`
**Sandbox**
`PUT` `https://{prefix}.api.sandbox.checkout.com/issuing/controls/{control_id}`
### Request example
```json
{
"description":"Max spend of 500€ per week for restaurants",
"velocity_limit":{
"amount_limit":50000,
"mcc_list":[
"4121",
"4582"
],
"mid_list":null
}
}
```
### Response example
The response returns the updated control details.
```json
{
"mcc_limit":{
"type":"block",
"mcc_list":[
"7995"
]
},
"id":"ctr_ixy6g5hndwuudmuz5tsgct36ae",
"control_type":"mcc_limit",
"target_id":"crd_fa6psq42dcdd6fdn5gifcq1491",
"created_date":"2023-03-15T07:02:15.84Z",
"last_modified_date":"2023-03-15T07:08:24.1761739Z"
}
```
---
## Delete a control
You can delete a control using the Dashboard and the API. To re-apply the same control to a card later, you must create a new control.
### Delete a control in the Dashboard
1. Sign in to the [Dashboard](https://dashboard.checkout.com/).
2. Go to _Issuing_ > _Cards_.
3. Find the card you want to delete the control from by searching or using filters, and select it.
4. On the _Card details_ page, go to the _Controls_ tab.
5. Find the control you want to delete and select _Edit_.
6. Select _Delete_.
7. In the _Delete control_ window that opens, select _Delete_ to confirm.
### Delete a control using the API
Call the [Delete a control](https://api-reference.checkout.com/tag/Controls/#operation/deleteControl) endpoint, and provide the `{control_id}` in the path.
> **Information**
>
> Your base URL's `{prefix}` value is unique to your account and environment. To learn how to retrieve your base URLs for the sandbox and production environments, see [API endpoints](https://www.checkout.com/docs/developer-resources/api/api-endpoints.md).
**Production**
`DELETE` `https://{prefix}.api.checkout.com/issuing/controls/{control_id}`
**Sandbox**
`DELETE` `https://{prefix}.api.sandbox.checkout.com/issuing/controls/{control_id}`
### Response example
The response confirms the `id` of the deleted control.
```json
{
"id": "ctr_ixy6g5hndwuudmuz5tsgct36ae"
}
```