Control card spending
Beta
Last updated: March 22, 2023
Card spending controls help you to manage your card spending budget and prevent fraud. You do this by applying controls to a card.
A control can contain one or both of the following rules:
- a velocity spending limit, which determines how much a card can spend over a given period of time
- a merchant category code (MCC) allowlist or blocklist rule, which determines the types of businesses a card can process transactions from
For example, you can apply a control that allows a card to spend up to €500 per month at food businesses.
You can apply multiple controls to a card, but the strictest control will always override the others. In the following example, the second control overrides the first control:
- allow the card to spend up to €500 per month at food businesses
- limit the card's overall spending to €400 per month
Controls are set per card, so a cardholder can have a unique set of spending controls applied to each card they've been issued.
As spending controls are applied per card, you'll need to retrieve the required card's ID before you can apply the required controls.
If you've just created a card, you'll find the card ID in the response's id
field.
Alternatively, you can use the following endpoint to retrieve a list of cards issued to the specified cardholder:
get
https://api.checkout.com/issuing/cardholders/{cardholderId}/cards
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 Doe",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}
From the list of cards returned in the response, make a note of the id
value of the card you want to apply spending controls to.
A velocity limit determines how much a card can spend over a given period of time. For example, you can apply a velocity limit which caps the overall card spending to €1000 per month:
post
https://api.checkout.com/issuing/controls
1{2"description": "Limit spend to €1000 per month",3"control_type": "velocity_limit",4"target_id": "crd_fa6psq42dcdd6fdn5gifcq1491",5"velocity_limit": {6"amount_limit": 1000,7"velocity_window": {8"type": "monthly"9}10}11}
1{2"id": "ctr_gp7vkmxayztufjz6top5bjcdra",3"description": "Limit spend to €1000 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": 1000,10"velocity_window": {11"type": "monthly"12}13}14}
You also have the option to apply more granular velocity limits, by specifying which MCCs the given velocity limit applies to. For example, you can apply a velocity limit which caps the spending at food businesses to €500 per month:
Information
The MCC list for a given velocity limit is set separately to the overall MCC rules.
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}
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 apply multiple velocity limits to a card by sending separate requests to the endpoint. For example, by applying both of the previous example velocity limits, the cardholder would be able to:
- spend up to €1000 per month
- spend up to €500 per month at food businesses, without exceeding the overall €1000 monthly limit
After creating a velocity limit control, you can use the API to retrieve the control using its ID if you need to update it at a later date. You can also retrieve a list of all controls applied to a specified card.
An MCC rule determines the types of businesses a card can process transactions from.
You do this by by supplying a list of MCCs to either allow or block. For example, you can block all authorization requests coming from gambling institutions.
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}
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}
While you can specify which MCCs to block using multiple rules, you can only use a single rule to define which MCCs to allow. If you need to update an MCC control's allowlist, update the control itself.
After creating an MCC rule control, you can use the API to retrieve the control using its ID if you need to update it at a later date. You can also retrieve a list of all controls applied to a specified card.
You can use the API to update an existing control, or remove it from a card entirely.
You can update an existing velocity limit to change the limit amount, period of time, or the list of MCCs it applies to.
Similarly, you can add or remove MCCs from your MCC blocklist or allowlist rule.
put
https://api.checkout.com/issuing/controls/{control_id}
1{2"mcc_limit": {3"type": "block",4"mcc_list": ["7995"]5}6}
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}
Removing a control from a card deletes the control entirely.
To apply an equivalent control at a later date, you'll need to create a new velocity limit or MCC rule.
delete
https://api.checkout.com/issuing/controls/{control_id}
1{2"id": "ctr_ixy6g5hndwuudmuz5tsgct36ae"3}