Control groups

Last updated: July 30, 2025

You can group multiple spending controls together into a control group and specify how to apply the combined outcome. This enables you to build complex rules for card behavior. Control groups can target either a card or a control profile. Targets can have multiple control groups.

You can create control groups to decline a payment if it fails:

All controls in the group – The evaluations function as a logical AND operation
Any control in the group - The evaluations function as a logical OR operation

Create a control group and specify the fail condition, the target, and the controls you want to include in the group.

You can then:

Retrieve the control group's details.
Retrieve all control groups for a target.
Remove a control group from a target.

Call the Create a control group endpoint, and provide the following:

description – A description of the control group.
fail_if – The fail condition for the control group. This can be one of:
- all_fail – Decline the payment if all controls fail.
- any_fail – Decline the payment if any control fails.
target_id – The ID of the card (prefixed with crd_) or control profile (prefixed with cpr_) you want the control group to target.

Specify multiple controls in the controls array, which contains the following fields:

description – A description of the control.
control_type – The type of control. This can be one of:
- mcc_limit – A merchant category code (MCC) control
- mid_limit – A merchant identification number (MID) control
- velocity_limit – A velocity control

For MCC controls, provide an mcc_limit object, which contains the following:

type – This can be either allow or block.
mcc_list – The array of MCCs that you want to allow or block.

For MID controls, provide an mid_limit object, which contains the following:

type – This can be either allow or block.
mid_list – The array of MIDs you want to allow or block.

For velocity controls, provide a velocity_limit object, which contains the following:

amount_limit – The amount the card can spend.
velocity_window – The time frame over which the card can spend the amount.
velocity_window.type – This can be one of:
- all_time – The card can spend the amount at any time.
- daily – The card can spend the amount within 24 hours.
- monthly – The card can spend the amount within a calendar month.
- weekly – The card can spend the amount within a calendar week.

post

https://api.checkout.com/issuing/control-groups


1{
2  "description": "Only allow groceries at Walmart up to $1000 per day",
3  "fail_if": "all_fail",
4  "target_id": "crd_fa6psq42dcdd6fdn5gifcq1491",
5  "controls": [
6    {
7      "description": "Block the card from being used for groceries",
8      "control_type": "mcc_limit",
9      "mcc_limit": {
10        "type": "block",
11        "mcc_list": [
12          "5422"
13        ]
14      }
15    },
16    {
17      "description": "Allow the card to be used at Walmart",
18      "control_type": "mid_limit",
19      "mid_limit": {
20        "type": "allow",
21        "mid_list": [
22          "1234"
23        ]
24      }
25    },
26    {
27      "description": "Allow the card to spend a maximum of $1000 daily",
28      "control_type": "velocity_limit",
29      "velocity_limit": {
30        "amount_limit": 100000,
31        "velocity_window": {
32            "type": "daily"
33        }
34      }
35    }
36  ]
37}


1{
2  "id": "cgr_oemoyd3otivelkhf4zcnimwdva",
3  "description": "Only allow groceries at Walmart up to $1000 per day",
4  "target_id": "crd_dba7tjsh7utufgid7yety4gnxq",
5  "fail_if": "all_fail",
6  "controls": [
7    {
8      "mcc_limit": {
9        "type": "block",
10        "mcc_list": [
11          "5422"
12        ]
13      },
14      "description": "Block the card from being used for groceries",
15      "control_type": "mcc_limit"
16    },
17    {
18      "mid_limit": {
19        "type": "allow",
20        "mid_list": [
21          "1234"
22        ]
23      },
24      "description": "Allow the card to be used at Walmart",
25      "control_type": "mid_limit"
26    },
27    {
28      "velocity_limit": {
29        "amount_limit": 100000,
30        "velocity_window": {
31            "type": "daily"
32        }
33      },
34      "description": "Allow the card to spend a maximum of $1000 daily",
35      "control_type": "velocity_limit"
36    }
37  ],
38  "is_editable": true,
39  "created_date":"2025-01-06T14:01:31.7155085Z",
40  "last_modified_date": "2025-01-06T14:01:31.7155085Z",
41  "_links": {
42    "self": {
43      "href": "https://api.checkout.com/issuing/control-groups/cgr_oemoyd3otivelkhf4zcnimwdva",
44      "actions": [
45        "GET"
46      ],
47      "types": [
48        "application/json"
49      ]
50    }
51  }
52}

The response returns the control group ID in the id field, prefixed with cgr_. The is_editable boolean is set to true because you created the control group and can update it.

Call the Get a control group endpoint, and provide the ID of the control group you want to retrieve as the {controlGroupId} path parameter.

get

https://api.checkout.com/issuing/control-groups/{controlGroupId}


1{
2  "id": "cgr_oemoyd3otivelkhf4zcnimwdva",
3  "description": "Only allow groceries at Walmart up to $1000 per day",
4  "target_id": "crd_dba7tjsh7utufgid7yety4gnxq",
5  "fail_if": "all_fail",
6  "controls": [
7    {
8      "mcc_limit": {
9        "type": "block",
10        "mcc_list": [
11          "5422"
12        ]
13      },
14      "description": "Block the card from being used for groceries",
15      "control_type": "mcc_limit"
16    },
17    {
18      "mid_limit": {
19        "type": "allow",
20        "mid_list": [
21          "1234"
22        ]
23      },
24      "description": "Allow the card to be used at Walmart",
25      "control_type": "mid_limit"
26    },
27    {
28      "velocity_limit": {
29        "amount_limit": 100000,
30        "velocity_window": {
31            "type": "daily"
32        }
33      },
34      "description":"Allow the card to spend a maximum of $1000 daily",
35      "control_type":"velocity_limit"
36    }
37  ],
38  "is_editable": true,
39  "created_date": "2025-01-06T14:01:31.7155085Z",
40  "last_modified_date": "2025-01-06T14:01:31.7155085Z",
41  "_links": {
42    "self":{
43      "href": "https://api.checkout.com/issuing/control-groups/cgr_oemoyd3otivelkhf4zcnimwdva",
44      "actions": [
45        "GET"
46      ],
47      "types": [
48        "application/json"
49      ]
50    }
51  }
52}

The response returns the details of the specified control group and each control in the group, along with associated metadata.

To retrieve all control groups that target a card or control profile, call the Get control groups by target endpoint, and provide the target ID as the {targetId} path parameter.

get

https://api.checkout.com/issuing/control-groups/{targetId}


1{
2  "control_groups": [
3    {
4      "id": "cgr_oemoyd3otivelkhf4zcnimwdva",
5      "description": "Only allow groceries at Walmart up to $1000 per day",
6      "target_id": "crd_dba7tjsh7utufgid7yety4gnxq",
7      "fail_if": "all_fail",
8      "controls": [
9        {
10          "mcc_limit": {
11            "type": "block",
12            "mcc_list": [
13              "5422"
14            ]
15          },
16          "description": "Block the card from being used for groceries",
17          "control_type": "mcc_limit"
18        },
19        {
20          "mid_limit": {
21            "type": "allow",
22            "mid_list": [
23              "1234"
24            ]
25          },
26          "description": "Allow the card to be used at Walmart",
27          "control_type": "mid_limit"
28        },
29        {
30          "velocity_limit":{
31            "amount_limit": 100000,
32            "velocity_window": {
33                "type": "daily"
34            }
35          },
36          "description":"Allow the card to spend a maximum of $1000 daily",
37          "control_type":"velocity_limit"
38        }
39      ],
40      "is_editable": true,
41      "created_date": "2025-01-06T14:01:31.7155085Z",
42      "last_modified_date": "2025-01-06T14:01:31.7155085Z"
43    }
44  ]
45}

The response returns the IDs of all control groups that target the card or control profile, along with the details of each control and associated metadata.

Call the Remove a control group endpoint, and provide the control group ID as the {controlGroupId} path parameter.

Note

Removing a control group deletes all controls in the control group.

To reapply a control group to the target, you must create a new control group.

delete

https://api.checkout.com/issuing/control-groups/{controlGroupId}


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

The response returns the ID of the control group you removed.

Control groups

How it works

Create a control group

Request examples

Response examples

Get control group details

Response example

Retrieve control groups by target

Response example

Remove a control group

Note

Response example