> ## Documentation Index
> Fetch the complete documentation index at: https://docs.equalsmoney.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Manage merchant controls

> An **authorisation control** (merchant control) prevents a card from being used with certain merchants, specified by their Merchant Category Code (MCC

# 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

<Note>
  **GET** `/v2/cards/{cardId}/auth-controls`
</Note>

### Request

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

<CodeGroup>
  ```bash Sample request theme={null}
  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'
  ```

  ```bash Request structure theme={null}
  curl -i -X GET \
    'https://api.equalsmoney.com/v2/cards/{cardId}/auth-controls?accountId={accountId}' \
    -H 'Authorization: ApiKey YOUR_API_KEY_HERE'
  ```
</CodeGroup>

#### Path parameters

<ParamField body="cardId" type="string (uuid)" required>
  The ID of the card that you want to retrieve authorisation controls for.

  Allowable values: An existing `cardId` (≤ 36 characters)
</ParamField>

#### Query parameters

<ParamField body="accountId" type="string" required>
  The ID of the account associated with the card.

  Allowable values: An existing `cardId` (≤ 36 characters)
</ParamField>

<ParamField body="personId" type="string (uuid)">
  The ID of the person that the card belongs to.

  Allowable values: An existing `personId` (≤ 36 characters)
</ParamField>

<ParamField body="limit" type="integer">
  The maximum number of results to return. By default, this is set to `100`.

  Allowable values: `[ 1 .. 1000 ]`
</ParamField>

<ParamField body="offset" type="integer">
  The number of items to skip before returning results. By default, this is set to `0`.

  Allowable values: A valid integer
</ParamField>

### Response

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

<CodeGroup>
  ```json Sample response theme={null}
  {
    "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"
        }
      }
    ]
  }
  ```

  ```json Response structure theme={null}
  {
    "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"
        }
      }
    ]
  }
  ```
</CodeGroup>

For more detailed information about this request and its response, [see the API reference](/api-reference/merchant-controls/list-authorisation-controls).

## Create an authorisation control

<Note>
  **POST** `/v2/cards/{cardId}/auth-controls`
</Note>

### 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.

<CodeGroup>
  ```bash Sample request theme={null}
  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"
      }
    }'
  ```

  ```bash Request structure theme={null}
  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"
    }
  }'
  ```
</CodeGroup>

#### Path parameters

<ParamField body="cardId" type="string (uuid)" required>
  The ID of the card that you want to retrieve authorisation controls for.

  Allowable values: An existing `cardId` (≤ 36 characters)
</ParamField>

#### Query parameters

<ParamField body="accountId" type="string" required>
  The ID of the account associated with the card.

  Allowable values: An existing `cardId` (≤ 36 characters)
</ParamField>

<ParamField body="personId" type="string (uuid)">
  The ID of the person that the card belongs to.

  Allowable values: An existing `personId` (≤ 36 characters)
</ParamField>

<ParamField body="limit" type="integer">
  The maximum number of results to return. By default, this is set to `100`.

  Allowable values: `[ 1 .. 1000 ]`
</ParamField>

<ParamField body="offset" type="integer">
  The number of items to skip before returning results. By default, this is set to `0`.

  Allowable values: A valid integer
</ParamField>

#### Request body schema

### Response

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

<CodeGroup>
  ```json Sample response theme={null}
  {
    "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"
    }
  }
  ```

  ```json Response structure theme={null}
  {
    "name": "string",
    "id": "string",
    "active": boolean,
    "startTime": "string",
    "endTime": "string",
    "merchantScope": {
      "mcc": "string",
      "mid": "string",
      "mccGroup": "string"
    }
  }
  ```
</CodeGroup>

For more detailed information about this request and its response, [see the API reference](/api-reference/merchant-controls/create-an-authorisation-control).

## Retrieve an authorisation control

<Note>
  **GET** `/v2/cards/{cardId}/auth-controls/{authControlId}`
</Note>

### Request

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

<CodeGroup>
  ```bash Sample request theme={null}
  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'
  ```

  ```bash Request structure theme={null}
  curl -i -X GET \
    'https://api.equalsmoney.com/v2/cards/{cardId}/auth-controls/{authControlId}?accountId={accountId}' \
    -H 'Authorization: ApiKey YOUR_API_KEY_HERE'
  ```
</CodeGroup>

#### Path parameters

<ParamField body="cardId" type="string (uuid)" required>
  The ID of the card that you want to update an authorisation control for.

  Allowable values: An existing `cardId` (≤ 36 characters)
</ParamField>

<ParamField body="authControlId" type="string (uuid)" required>
  The ID of the authorisation control that you want to update.

  Allowable values: An existing `authControlId` (≤ 36 characters)
</ParamField>

#### Query parameters

<ParamField body="accountId" type="string" required>
  The ID of the account that the card is associated with.

  Allowable values: An existing `cardId` (≤ 36 characters)
</ParamField>

<ParamField body="personId" type="string (uuid)">
  The ID of the person that the card belongs to.

  Allowable values: An existing `personId` (≤ 36 characters)
</ParamField>

### Response

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

<CodeGroup>
  ```json Sample response theme={null}
  {
    "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"
    }
  }
  ```

  ```json Response structure theme={null}
  {
    "name": "string",
    "id": "string",
    "active": boolean,
    "startTime": "string",
    "endTime": "string",
    "merchantScope": {
      "mcc": "string",
      "mid": "string",
      "mccGroup": "string"
    }
  }
  ```
</CodeGroup>

For more detailed information about this request and its response, [see the API reference](/api-reference/merchant-controls/retrieve-an-authorisation-control).

## Update an authorisation control

<Note>
  **PUT** `/v2/cards/{cardId}/auth-controls/{authControlId}`
</Note>

### Request

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

<CodeGroup>
  ```bash Sample request theme={null}
  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"
      }
    }'
  ```

  ```bash Request structure theme={null}
  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"
      }
    }'
  ```
</CodeGroup>

#### Path parameters

<ParamField body="cardId" type="string" required>
  The ID of the card that the authorisation control applies to.

  Allowable values: An existing `cardId` (≤ 36 characters)
</ParamField>

<ParamField body="authControlId" type="string" required>
  The ID of the authorisation control that you want to update.

  Allowable values: An existing `authControlId` (≤ 36 characters)
</ParamField>

#### Query parameters

<ParamField body="accountId" type="string" required>
  The ID of the account that the card is associated with.

  Allowable values: An existing `accountId`
</ParamField>

<ParamField body="personId" type="string">
  The ID of the person that the card belongs to.

  Allowable values: An existing `personId` (≤ 36 characters)
</ParamField>

#### Request body schema

<ParamField body="name" type="string">
  The name of the authorisation control.

  Allowable values: ≤ 255 characters
</ParamField>

<ParamField body="active" type="boolean">
  Whether or not the authorisation control should be active. By default, this is set to `true`.

  Allowable values: `true`, `false`
</ParamField>

<ParamField body="merchantScope" type="object">
  Details about the merchant scope.

  Allowable values: A valid `merchantScope` object containing the following fields: `mcc`, `mid`, `mcc`

  <Expandable title="merchantScope properties">
    <ParamField body="merchantScope.mcc" type="string">
      The merchant category code (MCC).

      Allowable values: ≤ 4 characters
    </ParamField>

    <ParamField body="merchantScope.mid" type="string">
      The merchant identifier (MID).

      Allowable values: ≤ 36 characters
    </ParamField>

    <ParamField body="merchantScope.mccGroup" type="string">
      The MCC group. You can use the [list MCC groups](#list-mcc-groups) request to get a full list of all available groups.

      Allowable values: ≤ 36 characters
    </ParamField>
  </Expandable>
</ParamField>

### Response

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

<CodeGroup>
  ```json Sample response theme={null}
  {
    "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"
    }
  }
  ```

  ```json Response structure theme={null}
  {
    "name": "string",
    "id": "string",
    "active": boolean,
    "startTime": "string",
    "endTime": "string",
    "merchantScope": {
      "mcc": "string",
      "mid": "string",
      "mccGroup": "string"
    }
  }
  ```
</CodeGroup>

For more detailed information about this request and its response, [see the API reference](/api-reference/merchant-controls/update-an-authorisation-control).

## List MCC groups

<Note>
  **GET** `/v2/mcc-groups`
</Note>

### Request

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

<CodeGroup>
  ```bash Sample request theme={null}
  curl -i -X GET \
    'https://api.equalsmoney.com/v2/mcc-groups?accountId=F12345' \
    -H 'Authorization: ApiKey YOUR_API_KEY_HERE'
  ```

  ```bash Request structure theme={null}
  curl -i -X GET \
    'https://api.equalsmoney.com/v2/mcc-groups?accountId={accountId}' \
    -H 'Authorization: ApiKey YOUR_API_KEY_HERE'
  ```
</CodeGroup>

#### Query parameters

<ParamField body="accountId" type="string" required>
  The ID of the account that the card is associated with.

  Allowable values: An existing `accountId`
</ParamField>

<ParamField body="personId" type="string">
  The ID of the person that the card belongs to.

  Allowable values: An existing `personId` (≤ 36 characters)
</ParamField>

<ParamField body="limit" type="integer">
  The maximum number of results to return. By default, this is set to `100`.

  Allowable values: `[ 1 .. 1000 ]`
</ParamField>

<ParamField body="offset" type="integer">
  The number of items to skip before returning results. By default, this is set to `0`.

  Allowable values: A valid integer
</ParamField>

### Response

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

<CodeGroup>
  ```json Sample response theme={null}
  {
    "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
            }
          }
        }
      }
    ]
  }
  ```

  ```json Response structure theme={null}
  {
    "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
            }
          }
        }
      }
    ]
  }
  ```
</CodeGroup>

For more detailed information about this request and its response, [see the API reference](/api-reference/merchant-controls/list-mcc-groups).