Control card spending
Last updated: October 9, 2024
Card spending controls help you manage your card spending budget and prevent fraud. Controls act as rules that restrict cards to spending:
- At certain types of business, using the merchant category code (MCC)
- At specific merchants, using the merchant identifier (MID)
- At a certain velocity – that is, how much the card can spend within a given time frame
You can also add MCCs or MIDs to a velocity control. For example, allow a card to spend a maximum of 500 EUR per month at food businesses.
You can apply one or multiple controls to a specific card, or use control profiles that apply a set of controls to multiple cards. There is no limit on the number of cards you can add to a control profile, and each card is assessed individually against the profile.
- Retrieve the identifier for the card or control profile you want to apply controls to.
- Apply an MCC, MID, or velocity control.
- View, update, and delete controls as needed.
When a card or control profile has multiple controls, 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.
When setting up your card program, Checkout.com may apply certain controls at account level. This helps protect you and us against fraud, and maintain a healthy spending budget. These controls apply to every card product and card you create.
You cannot remove or change immutable controls, but you can make changes within their limits. For example, if Checkout.com applied an immutable maximum lifetime spending limit of 100 EUR to a card, you can change this to 80 EUR but not to 150 EUR.
For more information, contact your Account Manager or [email protected].
To apply controls to a specific card, retrieve the card ID in the Dashboard or via the API to set as the target for the control.
- In your Dashboard, go to Card 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. For example, crd_abcdef1ghijklmn23opq45r6st
.
Alternatively, you can retrieve a list of cards issued to a specific cardholder using the Get a cardholder's cards endpoint, providing the cardholderId
. 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 id
for the card 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}
To apply controls to an existing control profile, retrieve the control profile ID via the API to set as the target for the control. Call the Get all control profiles endpoint.
get
https://api.checkout.com/issuing/controls/control-profiles
The response returns a JSON object for each of your control profiles, with the profile ID in the id
field. For example, cpr_abcdef1ghijklmn23opq45r6st
.
Make a note of the profile id
you want to apply controls to.
1{2"control_profiles": [3{4"id": "cpr_j4mvlui5qotufgvaeqwhvlbfna",5"name": "Low Risk MCC Profile",6"created_date": "2024-03-12T18:13:45.7155085Z",7"last_modified_date": "2024-03-13T15:44:56.7155085Z"8},9{10"id": "cpr_53mkhdc4jjlu5jcryx76bjbrgm",11"name": "Medium Risk MCC Profile",12"created_date": "2024-05-05T10:43:13.7155085Z",13"last_modified_date": "2024-06-17T06:32:18.7155085Z"14},15{16"id": "cpr_j4ma3rclvgcu3pn5tsdgb3e3a4",17"name": "High Risk MCC Profile",18"created_date": "2024-02-29T12:55:55.7155085Z",19"last_modified_date": "2024-03-01T10:12:12.7155085Z"20}21]22}
You can restrict the types of business a 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.
- In your Dashboard, go to Card 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.
To restrict MCCs for a specific card or a control profile, call the Create a control endpoint:
- Optionally, provide a description for the control.
- Set the
control_type
field tomcc_limit
. - Set the
target_id
field to the card or control profileid
to apply the control to. - In the
mcc_limit
object:- Set the
type
field to theallow
orblock
the MCCs. - In the
mcc_list
field, list the relevant MCCs.
- Set the
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}
You can restrict a specific card or card profile to only spend at specific merchants using the API, 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.
Call the Create a control endpoint:
- Optionally, provide a description for the control.
- Set the
control_type
field tomid_limit
. - Set the
target_id
field to the card or control profileid
to apply the control to. - In the
mid_limit
object:- Set the
type
field to theallow
orblock
the MIDs. - In the
mid_list
field, list the relevant MIDs.
- Set the
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}
You can apply a velocity control that limits how much a card can spend within a given time frame in the Dashboard or using the API.
- If you delete and then reapply a velocity control, the remaining spend amount is reset and tracked according to the new control.
- After you create a velocity control, you cannot change the time frame.
- If you also add MCCs and MIDs to your velocity control, the limit is applied separately to each MCC or MID listed.
For example, if a control applies a limit of 500 EUR per month for MCCs
7995
and7994
, the card's total spending limit is 1000 EUR. That is, 500 EUR for7995
and 500 EUR for7994
.
- In the Dashboard, go to Card 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 time frame for spending the amount:
All time
,Daily
,Weekly
, orMonthly
.
- 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.
To apply a velocity control to a specific card, call the Create a control endpoint:
- Optionally, provide a description for the control.
- Set the
control_type
field tovelocity_limit
. - Set the
target_id
field to the cardid
to apply the control to.Control profile IDs are not supported. - 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 time frame for spending the amount:all_time
for no specific time frame, ordaily
,monthly
, orweekly
. - Optionally, apply the velocity control either to specific merchant category codes in the
mcc_list
field, or to specific merchant IDs in themid_list
field (but not both).
- Set the
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 the controls and control profiles applied to a card in the Dashboard or via the API.
To view a card's controls in the Dashboard, you must have the administrator role or an administrator must give you permission.
- Go to Card 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
To retrieve the controls for a card using the API, call the Get controls by target endpoint, providing the card or control profile id
as a 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.
If you provided the card id
as the target_id
, the response only returns controls applied to the card directly.
It does not return controls applied through a control profile.
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 via the API, call the Get control details endpoint, providing 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 you applied the control:
- The
owner
field value isclient
. - The
is_editable
boolean is set totrue
.
- The
- If it's an immutable control applied by Checkout.com:
- The
owner
field value ischeckout
. - The
is_editable
boolean is set tofalse
.
- The
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": null19},20"is_editable": false,21"owner" : "checkout"22}
To view the control profiles applied to a card in the Dashboard, you must have the administrator role or an administrator must give you permission.
- Go to Card 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.
- Select Card control profiles, which also displays the number of profiles.
The control profiles are listed in the pop-up window. - To view the profile details, select View all card control profiles.
The Card control profiles page appears, listing the details of each profile.
To retrieve a list of control profiles that apply to a card, call the Get all control profiles endpoint, and provide the card id
as the target_id
query parameter.
get
https://api.checkout.com/issuing/controls/control-profiles?target_id=crd_abcdef1ghijklmn23opq45r6st
The response returns a JSON object for each control profile that applies to the card, with the profile's identifier in the id
field. For example, cpr_abcdef1ghijklmn23opq45r6st
.
1{2"control_profiles": [3{4"id": "cpr_j4mvlui5qotufgvaeqwhvlbfna",5"name": "Low Risk MCC Profile",6"created_date": "2024-03-12T18:13:45.7155085Z",7"last_modified_date": "2024-03-13T15:44:56.7155085Z"8},9{10"id": "cpr_53mkhdc4jjlu5jcryx76bjbrgm",11"name": "Medium Risk MCC Profile",12"created_date": "2024-05-05T10:43:13.7155085Z",13"last_modified_date": "2024-06-17T06:32:18.7155085Z"14}15]16}
You can update a specific control in the Dashboard or via the API. For example, you can change the amount of a velocity control, or allow or block different MCCs or MIDs.
Information
You cannot:
- Change the time frame of velocity controls after creation.
- Make changes outside the limits of any immutable controls.
To update a control in the Dashboard:
- Go to Card 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.
To update a control via the API, call the Update a control endpoint:
- Provide the
controlId
you want to update in the path. - Optionally, update the control
description
field. - Update the control settings in the
mcc_limit
,mid_limit
, orvelocity_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": null10}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 from a card in the Dashboard or via the API. To reapply the same control later, you must create a new control.
To delete a control in the Dashboard:
- Go to Card 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.
To delete a control via the API, call the Remove a control endpoint, and provide the controlId
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}