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.

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'

Path parameters

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

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.

{
  "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"
      }
    }
  ]
}

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.

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"
    }
  }'

Path parameters

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

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

Response

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

{
  "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"
  }
}

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.

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'

Path parameters

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

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.

{
  "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"
  }
}

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.

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"
    }
  }'

Path parameters

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

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

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

merchantScope

object

Details about the merchant scope.Allowable values: A valid merchantScope object containing the following fields: mcc, mid, mcc

Show merchantScope properties

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.

{
  "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"
  }
}

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.

curl -i -X GET \
  'https://api.equalsmoney.com/v2/mcc-groups?accountId=F12345' \
  -H 'Authorization: ApiKey YOUR_API_KEY_HERE'

Query parameters

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.

{
  "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
          }
        }
      }
    }
  ]
}

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

​Merchant controls

​List authorisation controls

​Request

​Path parameters

​Query parameters

​Response

​Create an authorisation control

​Request

​Path parameters

​Query parameters

​Request body schema

​Response

​Retrieve an authorisation control

​Request

​Path parameters

​Query parameters

​Response

​Update an authorisation control

​Request

​Path parameters

​Query parameters

​Request body schema

​Response

​List MCC groups

​Request

​Query parameters

​Response

Merchant controls

List authorisation controls

Request

Path parameters

Query parameters

Response

Create an authorisation control

Request

Path parameters

Query parameters

Request body schema

Response

Retrieve an authorisation control

Request

Path parameters

Query parameters

Response

Update an authorisation control

Request

Path parameters

Query parameters

Request body schema

Response

List MCC groups

Request

Query parameters

Response