Checkout.com API logo

Control groups

Group multiple spending controls together and specify how to apply the combined outcome.

Create a control group

Creates a control group and applies it to the specified target.

SecurityOAuth2: OAuth
Request
Request Body schema: application/json
required
target_id
required
string (IssuingTargetIdForAdd) = 30 characters ^(crd|cpr)_[a-z0-9]{26}$

The ID of the card or control profile to apply the control to. Note that control profiles cannot be a target for velocity_limit controls.

fail_if
required
string (ControlGroupCondition)

Sets how to determine the result of the group.

Enum: "all_fail" "any_fail"
required
Array of objects (add-control-group-request-control)

The controls that belong to the group.

description
string <= 256 characters

A description for the control group.

Responses
201

Control group created successfully

401

Unauthorized

404

Target not found

422

Invalid data was sent

500

Internal Server Error

503

Service Unavailable

post/issuing/controls/control-groups
Request samples
application/json
{
  • "description": "Block grocery shopping except Walmart",
  • "fail_if": "all_fail",
  • "target_id": "crd_fa6psq42dcdd6fdn5gifcq1491",
  • "controls": [
    ]
}
Response samples
application/json
{
  • "id": "cgr_oemoyd3otivelkhf4zcnimwdva",
  • "description": "Block grocery shopping except Walmart",
  • "target_id": "crd_dba7tjsh7utufgid7yety4gnxq",
  • "fail_if": "all_fail",
  • "controls": [
    ],
  • "is_editable": true,
  • "created_date": "2023-12-06T14:01:31.7155085Z",
  • "last_modified_date": "2023-12-06T14:01:31.7155085Z",
  • "_links": {}
}

Get a target's control groups

Retrieves a list of control groups applied to the specified target.

SecurityOAuth2: OAuth
Request
query Parameters
target_id
required
string (IssuingTargetId) = 30 characters ^(crd|cpr)_[a-z0-9]{26}$

The ID of the card or control profile.

Example: target_id=crd_fa6psq42dcdd6fdn5gifcq1491
Responses
200

Target's control groups retrieved successfully

401

Unauthorized

404

Target not found

422

Invalid data was sent

500

Internal Server Error

get/issuing/controls/control-groups
Request samples 
Response samples 
application/json
{
  • "control_groups": [
    ]
}
Get control group details
Retrieves the details of a control group you created previously.


SecurityOAuth2: OAuth 
Request 
path Parameters
controlGroupId
required
string (IssuingControlGroupId)   = 30 characters ^cgr_[a-z0-9]{26}$
The control group's unique identifier.


 
 Example:  cgr_oemoyd3otivelkhf4zcnimwdva
Responses 
200
Control group retrieved successfully


401
Unauthorized


404
Control group not found


500
Internal Server Error


get/issuing/controls/control-groups/{controlGroupId}
Request samples 
Response samples 
application/json
{
  • "id": "cgr_oemoyd3otivelkhf4zcnimwdva",
  • "description": "Block grocery shopping except Walmart",
  • "target_id": "crd_dba7tjsh7utufgid7yety4gnxq",
  • "fail_if": "all_fail",
  • "controls": [
    ],
  • "is_editable": true,
  • "created_date": "2023-12-06T14:01:31.7155085Z",
  • "last_modified_date": "2023-12-06T14:01:31.7155085Z",
  • "_links": {}
}
Remove a control group
Removes the control group and all the controls it contains.


If you want to reapply an equivalent control group to the card, you'll need to create a new control group.


SecurityOAuth2: OAuth 
Request 
path Parameters
controlGroupId
required
string (IssuingControlGroupId)   = 30 characters ^cgr_[a-z0-9]{26}$
The control group's unique identifier.


 
 Example:  cgr_oemoyd3otivelkhf4zcnimwdva
Responses 
200
Control group deleted successfully


401
Unauthorized


404
Control group not found


422
Invalid data was sent


500
Internal Server Error


503
Service Unavailable


delete/issuing/controls/control-groups/{controlGroupId}
Request samples 
Response samples 
application/json
{
  • "id": "cgr_oemoyd3otivelkhf4zcnimwdva"
}
➔ Next to Cardholder access tokens