/ Guides / Cards / Card limits / Manage merchant controls

Merchant controls

An authorisation control (merchant control) prevents a card from being used with certain merchants, specified by their Merchant Category Code (MCC) or Merchant Identifier (MID).

List authorisation controls

Get/v2/cards/{cardId}/auth-controls

Request

Use this request to get a list of all authorisation controls associated with a given card.

Sample requestRequest structure
Copy
Copied
curl -i -X GET \
  'https://api.equalsmoney.com/v2/cards/e9293471-5eb3-4dbc-916c-dbaf9e2deefd/auth-controls?accountId=F12345' \
  -H 'Authorization: ApiKey YOUR_API_KEY_HERE'
Copy
Copied
curl -i -X GET \
  'https://api.equalsmoney.com/v2/cards/{cardId}/auth-controls?accountId={accountId}' \
  -H 'Authorization: ApiKey YOUR_API_KEY_HERE'

Path parameters

Parameter Description
cardId
string (uuid)
required		 The ID of the card that you want to retrieve authorisation controls for.

Allowable values:
An existing cardId (<= 36 characters)

Query parameters

Parameter Description
accountId
string
required		 The ID of the account associated with the card.

Allowable values:
An existing cardId (<= 36 characters)
personId
string (uuid)		 The ID of the person that the card belongs to.

Allowable values:
An existing personId (<= 36 characters)
limit
integer		 The maximum number of results to return. By default, this is set to 100.

Allowable values:
[ 1 .. 1000 ]
offset
integer		 The number of items to skip before returning results. By default, this is set to 0.

Allowable values:
A valid integer

Response

If your request is successful, you'll receive a 200 response.

Sample responseResponse structure
Copy
Copied
{
  "limit": 100,
  "offset": 0,
  "count": 1,
  "search": "string",
  "rows": [
    {
      "name": "Spending controls",
      "id": "a1e54aed-8a68-4602-a792-30f4c67497cf",
      "active": true,
      "startTime": "2023-03-14T12:08:53Z",
      "endTime": "2023-03-14T12:08:53Z",
      "merchantScope": {
        "mcc": "3596",
        "mid": "string",
        "mccGroup": "Airlines"
      }
    }
  ]
}
Copy
Copied
{
  "limit": integer,
  "offset": integer,
  "count": integer,
  "search": "string",
  "rows": [
    {
      "name": "string",
      "id": "string",
      "active": boolean,
      "startTime": "string",
      "endTime": "string",
      "merchantScope": {
        "mcc": "string",
        "mid": "string",
        "mccGroup": "string"
      }
    }
  ]
}

For more detailed information about this request and its response, see the API reference.

Create an authorisation control

Post/v2/cards/{cardId}/auth-controls

Request

Use this request to create an authorisation control for a given card. This prevents the card from being used with certain merchants, specified by their Merchant Category Code (MCC) or Merchant Identifier (MID).

Use mcc to block an entire merchant category or mid to block a specific merchant.

You can update a card's authorisation control at any point.

Sample requestRequest structure
Copy
Copied
curl -i -X POST \
  'https://api.equalsmoney.com/v2/cards/e9293471-5eb3-4dbc-916c-dbaf9e2deefd/auth-controls?accountId=F12345' \
  -H 'Authorization: ApiKey YOUR_API_KEY_HERE' \
  -H 'Content-Type: application/json' \
  -d '{
    "name": "Spending controls",
    "id": "82813e6b-6f2b-4f01-9b63-6f4c390cd590",
    "active": true,
    "startTime": "2023-03-14T12:08:53Z",
    "endTime": "2023-03-14T12:08:53Z",
    "merchantScope": {
      "mcc": "3596",
      "mid": "string",
      "mccGroup": "Airlines"
    }
  }'
Copy
Copied
curl -i -X POST \
  'https://api.equalsmoney.com/v2/cards/{cardId}/auth-controls?accountId={accountId}' \
  -H 'Authorization: ApiKey YOUR_API_KEY_HERE' \
  -H 'Content-Type: application/json' \
  -d '{
  "name": "string",
  "id": "string",
  "active": boolean,
  "startTime": "string",
  "endTime": "string",
  "merchantScope": {
    "mcc": "string",
    "mid": "string",
    "mccGroup": "string"
  }
}'

Path parameters

Parameter Description
cardId
string (uuid)
required		 The ID of the card that you want to retrieve authorisation controls for.

Allowable values:
An existing cardId (<= 36 characters)

Query parameters

Parameter Description
accountId
string
required		 The ID of the account associated with the card.

Allowable values:
An existing cardId (<= 36 characters)
personId
string (uuid)		 The ID of the person that the card belongs to.

Allowable values:
An existing personId (<= 36 characters)
limit
integer		 The maximum number of results to return. By default, this is set to 100.

Allowable values:
[ 1 .. 1000 ]
offset
integer		 The number of items to skip before returning results. By default, this is set to 0.

Allowable values:
A valid integer

Request body schema

Parameter Description
name
string
required		 The name of the authorisation control.

Allowable values:
<= 255 characters
id
string		 The ID of the authorisation control. If not provided, one will be generated automatically.

Allowable values:
<= 36 characters
active
boolean		 Whether or not the authorisation control should be active. By default, this is set to true.

Allowable values:
true, false
startTime
string		 The date and time at which the authorisation control starts, in ISO 8601 format without milliseconds.

Allowable values:
Format: yyyy-MM-ddThh:mm:ssZ
endTime
string		 The date and time at which the authorisation control ends, in ISO 8601 format without milliseconds.

Allowable values:
Format: yyyy-MM-ddThh:mm:ssZ
merchantScope
string		 Details about the merchant scope.

Allowable values:
A valid merchantScope object containing the following fields: mcc, mid, mccGroup
merchantScope.mcc
string
required if no mid provided		 The merchant category code (MCC).

Allowable values:
<= 4 characters
merchantScope.mid
string
required if no mcc provided		 The merchant identified (MID).

Allowable values:
<= 36 characters
merchantScope.mccGroup
string		 The MCC group. You can use the list MCC groups request to get a full list of all available groups.

Allowable values:
<=36 characters

Response

If your request is successful, you'll receive a 201 response.

Sample responseResponse structure
Copy
Copied
{
  "name": "Spending controls",
  "id": "a1e54aed-8a68-4602-a792-30f4c67497cf",
  "active": true,
  "startTime": "2023-03-14T12:08:53Z",
  "endTime": "2023-03-14T12:08:53Z",
  "merchantScope": {
    "mcc": "3596",
    "mid": "string",
    "mccGroup": "Airlines"
  }
}
Copy
Copied
{
  "name": "string",
  "id": "string",
  "active": boolean,
  "startTime": "string",
  "endTime": "string",
  "merchantScope": {
    "mcc": "string",
    "mid": "string",
    "mccGroup": "string"
  }
}

For more detailed information about this request and its response, see the API reference.

Retrieve an authorisation control

Get/v2/cards/{cardId}/auth-controls/{authControlId}

Request

Use this request to get details about a given authorisation control.

Sample requestRequest structure
Copy
Copied
curl -i -X GET \
  'https://api.equalsmoney.com/v2/cards/e9293471-5eb3-4dbc-916c-dbaf9e2deefd/auth-controls/a1e54aed-8a68-4602-a792-30f4c67497cf?accountId=F12345' \
  -H 'Authorization: ApiKey YOUR_API_KEY_HERE'
Copy
Copied
curl -i -X GET \
  'https://api.equalsmoney.com/v2/cards/{cardId}/auth-controls/{authControlId}?accountId={accountId}' \
  -H 'Authorization: ApiKey YOUR_API_KEY_HERE'

Path parameters

Parameter Description
cardId
string (uuid)
required		 The ID of the card that you want to update an authorisation control for.

Allowable values:
An existing cardId (<= 36 characters)
authControlId
string (uuid)
required		 The ID of the authorisation control that you want to update.

Allowable values:
An existing authControlId (<= 36 characters)

Query parameters

Parameter Description
accountId
string
required		 The ID of the account that the card is associated with.

Allowable values:
An existing cardId (<= 36 characters)
personId
string (uuid)		 The ID of the person that the card belongs to.

Allowable values:
An existing personId (<= 36 characters)

Response

If your request is successful, you'll receive a 200 response.

Sample responseResponse structure
Copy
Copied
{
  "name": "Spending controls",
  "id": "a1e54aed-8a68-4602-a792-30f4c67497cf",
  "active": true,
  "startTime": "2023-03-14T12:08:53Z",
  "endTime": "2023-03-14T12:08:53Z",
  "merchantScope": {
    "mcc": "3596",
    "mid": "string",
    "mccGroup": "Airlines"
  }
}
Copy
Copied
{
  "name": "string",
  "id": "string",
  "active": boolean,
  "startTime": "string",
  "endTime": "string",
  "merchantScope": {
    "mcc": "string",
    "mid": "string",
    "mccGroup": "string"
  }
}

For more detailed information about this request and its response, see the API reference.

Update an authorisation control

Put/v2/cards/{cardId}/auth-controls/{authControlId}

Request

Use this request to update the details of a given authorisation control.

Sample requestRequest structure
Copy
Copied
curl -i -X PUT \
  'https://api.equalsmoney.com/v2/cards/e9293471-5eb3-4dbc-916c-dbaf9e2deefd/auth-controls/a1e54aed-8a68-4602-a792-30f4c67497cf?accountId=F12345' \
  -H 'Authorization: ApiKey YOUR_API_KEY_HERE' \
  -H 'Content-Type: application/json' \
  -d '{
    "name": "Spending controls",
    "active": true,
    "startTime": "2023-03-14T12:08:53Z",
    "endTime": "2023-03-14T12:08:53Z",
    "merchantScope": {
      "mcc": "3596",
      "mid": "string",
      "mccGroup": "Airlines"
    }
  }'
Copy
Copied
curl -i -X PUT \
  'https://api.equalsmoney.com/v2/cards/{cardId}/auth-controls/{authControlId}?accountId={accountId}' \
  -H 'Authorization: ApiKey YOUR_API_KEY_HERE' \
  -H 'Content-Type: application/json' \
  -d '
  {
    "name": "string",
    "active": boolean,
    "startTime": "string",
    "endTime": "string",
    "merchantScope": {
      "mcc": "string",
      "mid": "string",
      "mccGroup": "string"
    }
  }'

Path parameters

Parameter Description
cardId
string
required		 The ID of the card that the authorisation control applies to.

Allowable values:
An existing cardId (<= 36 characters)
authControlId
string
required		 The ID of the authorisation control that you want to update.

Allowable values:
An existing authControlId (<= 36 characters)

Query parameters

Parameter Description
accountId
string
required		 The ID of the account that the card is associated with.

Allowable values:
An existing accountId
personId
string		 The ID of the person that the card belongs to.

Allowable values:
An existing personId (<= 36 characters)

Request body schema

Parameter Description
name
string		 The name of the authorisation control.

Allowable values:
<= 255 characters
active
boolean		 Whether or not the authorisation control should be active. By default, this is set to true.

Allowable values:
true, false
startTime
string		 The date and time at which the authorisation control starts, in ISO 8601 format without milliseconds.

Allowable values:
Format: yyyy-MM-ddThh:mm:ssZ
endTime
string		 The date and time at which the authorisation control ends, in ISO 8601 format without milliseconds.

Allowable values:
Format: yyyy-MM-ddThh:mm:ssZ
merchantScope
object		 Details about the merchant scope.

Allowable values:
A valid merchantScope object containing the following fields: mcc, mid, mcc
merchantScope.mcc
string		 The merchant category code (MCC).

Allowable values:
<= 4 characters
merchantScope.mid
string		 The merchant identifier (MID).

Allowable values:
<= 36 characters
merchantScope.mccGroup
string		 The MCC group. You can use the list MCC groups request to get a full list of all available groups.

Allowable values:
<=36 characters

Response

If your request is successful, you'll receive a 200 response.

Sample responseResponse structure
Copy
Copied
{
  "name": "Spending controls",
  "id": "a1e54aed-8a68-4602-a792-30f4c67497cf",
  "active": true,
  "startTime": "2023-03-14T12:08:53Z",
  "endTime": "2023-03-14T12:08:53Z",
  "merchantScope": {
    "mcc": "3596",
    "mid": "string",
    "mccGroup": "Airlines"
  }
}
Copy
Copied
{
  "name": "string",
  "id": "string",
  "active": boolean,
  "startTime": "string",
  "endTime": "string",
  "merchantScope": {
    "mcc": "string",
    "mid": "string",
    "mccGroup": "string"
  }
}

For more detailed information about this request and its response, see the API reference.

List MCC groups

Get/v2/mcc-groups

Request

Use this request to get list of pre-defined merchant category code (MCC) groups, which you can use to create an authorisation control.

Sample requestRequest structure
Copy
Copied
curl -i -X GET \
  'https://api.equalsmoney.com/v2/mcc-groups?accountId=F12345' \
  -H 'Authorization: ApiKey YOUR_API_KEY_HERE'
Copy
Copied
curl -i -X GET \
  'https://api.equalsmoney.com/v2/mcc-groups?accountId={accountId}' \
  -H 'Authorization: ApiKey YOUR_API_KEY_HERE'

Query parameters

Parameter Description
accountId
string
required		 The ID of the account that the card is associated with.

Allowable values:
An existing accountId
personId
string		 The ID of the person that the card belongs to.

Allowable values:
An existing personId (<= 36 characters)
limit
integer		 The maximum number of results to return. By default, this is set to 100.

Allowable values:
[ 1 .. 1000 ]
offset
integer		 The number of items to skip before returning results. By default, this is set to 0.

Allowable values:
A valid integer

Response

If your request is successful, you'll receive a 200 response.

Sample responseResponse structure
Copy
Copied
{
  "limit": 100,
  "offset": 0,
  "count": 1,
  "rows": [
    {
      "name": "Airlines MCCs 3000 through 3350",
      "id": "Airlines",
      "active": true,
      "mccs": [
        "\"3596\", \"3000-3350\""
      ],
      "config": {
        "authorizationControls": {
          "holdIncrease": {
            "type": "AMOUNT",
            "value": 100,
            "holdExperationDays": 30
          }
        }
      }
    }
  ]
}
Copy
Copied
{
  "limit": integer,
  "offset": integer,
  "count": integer,
  "rows": [
    {
      "name": "string",
      "id": "string",
      "active": boolean,
      "mccs": [
        "string", "string"
      ],
      "config": {
        "authorizationControls": {
          "holdIncrease": {
            "type": "string",
            "value": integer,
            "holdExperationDays": integer
          }
        }
      }
    }
  ]
}

For more detailed information about this request and its response, see the API reference.