Card controls

Last updated: October 30, 2024

You can apply one or multiple card spending controls 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.

Retrieve the card ID you want to apply controls to.
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.

Checkout.com may apply certain controls to a card (or card product) 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 via the API.

For more information about immutable controls applied to a card, contact your Account Manager or [email protected].

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 businesses
Limit the card's overall spending to 400 EUR per month

Controls are not retroactive. Transactions approved before a control is applied are not affected by the control.

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.

Sign in to the Dashboard.
Go to Issuing > Cards.
Find the card you want to apply the control to by searching or using filters, and select it.
The Card details page opens.
On the About tab, under About this card, copy the card ID.

If you've just created a card, 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 endpoint. Provide the {cardholderId} in the path. For example, crh_abcdef1ghijklmn23opq45r6st.

get

https://api.checkout.com/issuing/cardholders/{cardholderId}/cards

The response returns a list of all the cardholder's cards. Make a note of the card id you want to apply controls to.


1{
2  "cards": [
3    {
4      "id": "crd_fa6psq242dcd6fdn5gifcq1491",
5      "cardholder_id": "crh_d3ozhf43pcq2xbldn2g45qnb44",
6      "card_product_id": "pro_7syjig3jq3mezlc3vjrdpfitl4",
7      "client_id": "cli_vkuhvk4vjn2edkps7dfsq6emqm",
8      "last_four": 1234,
9      "expiry_month": 5,
10      "expiry_year": 2025,
11      "status": "active",
12      "display_name": "John Smith",
13      "type": "virtual",
14      "billing_currency": "USD",
15      "issuing_country": "US",
16      "reference": "X-123456-N11",
17      "created_date": "2021-09-09T19:41:39Z",
18      "last_modified_date": "2021-09-09T19:41:39Z"
19    }
20  ]
21}

MCC controls restrict the types of business the card can spend at, by providing a list of merchant category codes (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.

Sign in to the Dashboard.
Go to Issuing > Cards.
Find the card you want to apply the control to by searching or using filters, and select it.
In the Card details screen that appears, go to the Controls tab.
Select Add control > Allow or block categories.
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.
Select Confirm to save.

Call the Create a control 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 itself.

post

https://api.checkout.com/issuing/controls


1{
2  "description": "Block all gambling transactions",
3  "control_type": "mcc_limit",
4  "target_id": "crd_fa6psq42dcdd6fdn5gifcq1491",
5  "mcc_limit": {
6    "type": "block",
7    "mcc_list": ["7994", "7995"]
8  }
9}

The response returns the control details and the control ID. For example, ctr_abcdef1ghijklmn23opq45r6st.


1{
2  "mcc_limit": {
3    "type": "block",
4    "mcc_list": ["7994", "7995"]
5  },
6  "id": "ctr_ixy6g5hndwuudmuz5tsgct36ae",
7  "description": "Block all gambling transactions",
8  "control_type": "mcc_limit",
9  "target_id": "crd_fa6psq42dcdd6fdn5gifcq1491",
10  "created_date": "2023-03-15T07:02:15.840206Z",
11  "last_modified_date": "2023-03-15T07:02:15.840206Z"
12}

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

post

https://api.checkout.com/issuing/controls


1{
2   "description": "Allow the card to be used only in AZ Pizza",
3   "control_type": "mid_limit",
4   "target_id": "crd_fa6psq42dcdd6fdn5gifcq1491",
5   "mid_limit": {
6      "type": "allow",
7      "mid_list": [
8         "593278",
9         "541114"
10      ]
11   }
12}

The response returns the control details and the control ID. For example, ctr_abcdef1ghijklmn23opq45r6st.


1{
2   "id": "ctr_gp7vkmxayztufjz6top5bjcdra",
3   "description": "Allow the card to be used only in AZ Pizza",
4   "control_type": "mid_limit",
5   "target_id": "crd_fa6psq42dcdd6fdn5gifcq1491",
6   "created_date": "2023-03-12T18:20:12Z",
7   "last_modified_date": "2023-03-12T18:20:12Z",
8   "mid_limit": {
9      "type": "allow",
10      "mid_list": [
11         "593278",
12         "541114"
13      ]
14   }
15}

A velocity control limits how much a card can spend within a given timeframe. You can apply them using the Dashboard and the API.

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.

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.

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.

Sign in to the Dashboard.
Go to Issuing > Cards.
Find the card you want to apply the control to by searching or using filters, and select it.
In the Card details screen that appears, go to the Controls tab.
Select Add control > Add a velocity control.
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.
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.
Select Confirm to save.

Call the Create a control 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).

post

https://api.checkout.com/issuing/controls


1{
2  "description": "Limit food spend to €500 per month",
3  "control_type": "velocity_limit",
4  "target_id": "crd_fa6psq42dcdd6fdn5gifcq1491",
5  "velocity_limit": {
6    "amount_limit": 500,
7    "velocity_window": {
8      "type": "monthly"
9    },
10    "mcc_list": ["5812", "5814"]
11  }
12}

The response returns the control details and the control ID. For example, ctr_abcdef1ghijklmn23opq45r6st.


1{
2  "id": "ctr_gp7vkmxayztufjz6top5bjcdra",
3  "description": "Limit food spend to €500 per month",
4  "control_type": "velocity_limit",
5  "target_id": "crd_fa6psq42dcdd6fdn5gifcq1491",
6  "created_date": "2023-03-12T18:20:12Z",
7  "last_modified_date": "2023-03-12T18:20:12Z",
8  "velocity_limit": {
9    "amount_limit": 500,
10    "velocity_window": {
11      "type": "monthly"
12    },
13    "mcc_list": ["5812", "5814"]
14  }
15}

You can view all controls applied to a card using the Dashboard and the API.

Sign in to the Dashboard.
Ensure you have the Admin role, or ask an Admin to give you permissions.
Go to Issuing > Cards.
Find the card you want to view by searching or using filters, and select it.
On the Card details page, go to the Controls tab to view the card's controls.

Information

Immutable controls are not displayed.

Call the Get controls by target endpoint, and provide the card id as the target_id query parameter.

get

https://api.checkout.com/issuing/controls?target_id=crd_abcdef1ghijklmn23opq45r6st

The response returns a JSON object for each control and its details. For velocity controls, it also returns the remaining amount available to spend.


1{
2  "controls": [
3    {
4      "id": "ctr_gp7vkmxayztufjz6top5bjcdra",
5      "target_id": "crd_fa6psq42dcdd6fdn5gifcq1491",
6      "description": "Maximum spend of 500€ per week for restaurants",
7      "control_type": "velocity_limit",
8      "created_date": "2021-09-09T19:41:39Z",
9      "last_modified_date": "2021-09-09T19:41:39Z",
10      "velocity_limit": {
11        "amount_remaining": 45000,
12        "amount_limit": 50000,
13        "velocity_window": {
14          "type": "weekly"
15        },
16        "mcc_list": [
17          "4121",
18          "4582"
19        ]
20      }
21    }
22  ]
23}

To retrieve the details of a specific control using the API, call the Get control details endpoint, and provide the {controlId} in the path.

get

https://api.checkout.com/issuing/controls/{controlId}

The response returns the control details.

For velocity controls, it returns the remaining amount available to spend.
If the is_editable boolean is set to:
- false – It's an immutable control applied by Checkout.com.
- true – You applied the control and can update it.


1{
2  "id": "ctr_gp7vkmxayztufjz6top5bjcdra",
3  "target_id": "crd_fa6psq42dcdd6fdn5gifcq1491",
4  "description": "Maximum spend of 500€ per week for restaurants",
5  "control_type": "velocity_limit",
6  "created_date": "2021-09-09T19:41:39Z",
7  "last_modified_date": "2021-09-09T19:41:39Z",
8  "velocity_limit": {
9    "amount_remaining": 45000,
10    "amount_limit": 50000,
11    "velocity_window": {
12      "type": "weekly"
13    },
14    "mcc_list": [
15      "4121",
16      "4582"
17    ],
18    "mid_list": null
19  },
20  "is_editable": false
21}

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.

Sign in to the Dashboard.
Go to Issuing > Cards.
Find the card you want to update the control for by searching or using filters, and select it.
On the Card details page, go to the Controls tab.
Find the control you want to update and select Edit.
Update the required details.
Select Confirm to save.

Call the Update a control 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.

put

https://api.checkout.com/issuing/controls/{control_id}


1{
2    "description": "Max spend of 500€ per week for restaurants",
3    "velocity_limit": {
4      "amount_limit": 50000,
5      "mcc_list": [
6        "4121",
7        "4582"
8      ],
9      "mid_list": null
10    }
11  }

The response returns the updated control details.


1{
2  "mcc_limit": {
3    "type": "block",
4    "mcc_list": ["7995"]
5  },
6  "id": "ctr_ixy6g5hndwuudmuz5tsgct36ae",
7  "control_type": "mcc_limit",
8  "target_id": "crd_fa6psq42dcdd6fdn5gifcq1491",
9  "created_date": "2023-03-15T07:02:15.84Z",
10  "last_modified_date": "2023-03-15T07:08:24.1761739Z"
11}

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.

Sign in to the Dashboard.
Go to Issuing > Cards.
Find the card you want to delete the control from by searching or using filters, and select it.
On the Card details page, go to the Controls tab.
Find the control you want to delete and select Edit.
Select Delete.
In the Delete control window that opens, select Delete to confirm.

Call the Delete a control endpoint, and provide the {control_id} in the path.

delete

https://api.checkout.com/issuing/controls/{control_id}

The response confirms the id of the deleted control.


1{
2  "id": "ctr_ixy6g5hndwuudmuz5tsgct36ae"
3}

How it works

Immutable controls

Control hierarchy

Control applicability

Retrieve card ID

Retrieve card ID in the Dashboard

Retrieve card ID using the API

Request example

Response example

Apply MCC controls

Apply MCC controls in the Dashboard

Apply MCC controls using the API

Information

Request example

Response example

Apply MID controls

Request example

Response example

Apply velocity controls

Information

Apply velocity controls in the Dashboard

Apply velocity controls using the API

Request example

Response example

View card controls

View card controls in the Dashboard

Information

View card controls using the API

Request example

Response example

Retrieve control details

Request example

Response example

Update a control

Note

Update a control in the Dashboard

Update a control using the API

Request example

Response example

Delete a control

Delete a control in the Dashboard

Delete a control using the API

Request example

Response example