Checkout.com API logo

Controls

Set spending controls to limit how much can be spent over a given period of time.

Create a control

Creates a control and applies it to the specified target.

SecurityOAuth2: OAuth
Request
header Parameters
Cko-Idempotency-Key
string [ 1 .. 256 ] characters ^[A-Za-z0-9._-]+$

An optional idempotency key for safely retrying Issuing requests.

Example: 7c1b9f96-4f2e-4b1a-bc2b-3d0f1a2e9f3a
Request Body schema: application/json
required
required
object (VelocityLimit)

The velocity limit, which determines how much a target card can spend over a given timeframe.

control_type
required
string (IssuingControlType)

The control's type.

A velocity_limit determines how much can be spent over a given period of time. An mcc_limit determines the types of businesses from which transactions can be processed. A mid_limit specifies the merchants from whom transactions can be processed.

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.

description
string <= 256 characters

A description for the control.

Responses
201

Control created successfully

401

Unauthorized

404

Target not found

422

Invalid data was sent

500

Internal Server Error

503

Service Unavailable

post/issuing/controls
Request samples
application/json
{
  • "description": "Maximum spend of 500€ per week for restaurants",
  • "control_type": "velocity_limit",
  • "target_id": "crd_fa6psq42dcdd6fdn5gifcq1491",
  • "velocity_limit": {
    }
}
Response samples
application/json
{
  • "id": "ctr_gp7vkmxayztufjz6top5bjcdra",
  • "description": "Maximum spend of 500€ per week for restaurants",
  • "control_type": "velocity_limit",
  • "target_id": "crd_fa6psq42dcdd6fdn5gifcq1491",
  • "is_editable": true,
  • "created_date": "2023-03-12T18:20:12Z",
  • "last_modified_date": "2023-03-12T18:20:12Z",
  • "_links": {},
  • "velocity_limit": {
    }
}

Get controls by target

Retrieves a list of spending controls 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 controls retrieved successfully

401

Unauthorized

404

Target not found

422

Invalid data was sent

500

Internal Server Error

get/issuing/controls
Request samples 
Response samples 
application/json
{
  • "controls": [
    ]
}
Get control details
Retrieves the details of an existing control.


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


 
 Example:  ctr_gp7vkmxayztufjz6top5bjcdra
query Parameters
cardId
string (IssuingCardId)   = 30 characters ^crd_[a-z0-9]{26}$
The unique identifier for the card you want to get the remaining cascading velocity control for.


 
 Example:  cardId=crd_fa6psq242dcd6fdn5gifcq1491
Responses 
200
Control retrieved successfully


401
Unauthorized


404
Control not found


500
Internal Server Error


get/issuing/controls/{controlId}
Request samples 
Response samples 
application/json
{
  • "id": "ctr_gp7vkmxayztufjz6top5bjcdra",
  • "target_id": "crd_fa6psq42dcdd6fdn5gifcq1491",
  • "description": "Maximum spend of 500€ per week for restaurants",
  • "control_type": "velocity_limit",
  • "is_editable": true,
  • "created_date": "2021-09-09T19:41:39Z",
  • "last_modified_date": "2021-09-09T19:41:39Z",
  • "velocity_limit": {
    }
}
Update a control
Updates an existing control.


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


 
 Example:  ctr_gp7vkmxayztufjz6top5bjcdra
Request Body schema: application/json
required
One of:
The control you want to update.


You can update only one control per request.


description
string  <= 256 characters 
A description for the control.


 
object (MccLimit) 
The merchant category code (MCC) rule, which determines the types of businesses transactions can be processed from.


 
Responses 
200
Control updated successfully


401
Unauthorized


404
Control not found


422
Invalid data was sent


500
Internal Server Error


503
Service Unavailable


put/issuing/controls/{controlId}
Request samples 
application/json
{
  • "description": "Allow the card to be used only in restaurants and supermarkets",
  • "mcc_limit": {
    }
}
Response samples 
application/json
{
  • "id": "ctr_gp7vkmxayztufjz6top5bjcdra",
  • "target_id": "crd_fa6psq42dcdd6fdn5gifcq1491",
  • "description": "Maximum spend of 500€ per week for restaurants",
  • "control_type": "velocity_limit",
  • "is_editable": true,
  • "created_date": "2021-09-09T19:41:39Z",
  • "last_modified_date": "2021-09-09T19:41:39Z",
  • "velocity_limit": {
    }
}
Remove a control
Removes an existing control from the target it was applied to.


If you want to reapply an equivalent control to the target, you must create a new control.


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


 
 Example:  ctr_gp7vkmxayztufjz6top5bjcdra
Responses 
200
Control deleted successfully


401
Unauthorized


404
Control not found


422
Invalid data was sent


500
Internal Server Error


503
Service Unavailable


delete/issuing/controls/{controlId}
Request samples 
Response samples 
application/json
{
  • "id": "ctr_gp7vkmxayztufjz6top5bjcdra"
}
➔ Next to Control profiles