Merchant controls

An authorisation control (merchant control) restricts which merchants a card can be used with, specified by their Merchant Category Code (MCC) or Merchant Identifier (MID). Use the action field to choose how the control is applied:

BLOCK (the default) — the card can’t be used with the merchants in scope. Everything else is still allowed.
ALLOW — the card can only be used with the merchants in scope. Everything else is declined.

For example, a control with action set to BLOCK and merchantScope.mcc set to 5813 stops the card being used in bars, but leaves every other merchant category available. The same scope with action set to ALLOW does the opposite: the card works in bars and nowhere else. When a card has more than one ALLOW control, the allow-lists combine across mcc and mid, and combine within each of them. So several ALLOW controls on mcc let the card transact at any of those categories, but adding an ALLOW control on mid as well means a transaction has to match both an allowed MCC and an allowed MID to be approved.

action is set when you create a control and can’t be changed afterwards — including action in an update request returns a 400 response. To switch a control between BLOCK and ALLOW, deactivate the existing control (set active to false) and create a new one with the action you need.Not every card programme supports action. Sending it on a programme that doesn’t returns a 400 response — omit it to get the default BLOCK behaviour. To check whether a card’s programme supports it, retrieve any of the card’s existing controls: programmes that support action always return it, and programmes that don’t always omit it.

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'

curl -i -X GET \
  'https://api.equalsmoney.com/v2/cards/{cardId}/auth-controls?accountId={accountId}' \
  -H 'Authorization: ApiKey YOUR_API_KEY_HERE'

Path parameters

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

string

required

The ID of the account associated with the card.Allowable values: An existing cardId (≤ 36 characters)

string (uuid)

The ID of the person that the card belongs to.Allowable values: An existing personId (≤ 36 characters)

integer

The maximum number of results to return. By default, this is set to 100.Allowable values: [ 1 .. 1000 ]

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",
      "action": "BLOCK",
      "merchantScope": {
        "mcc": "3596",
        "mid": "string",
        "mccGroup": "Airlines"
      }
    }
  ]
}

{
  "limit": integer,
  "offset": integer,
  "count": integer,
  "search": "string",
  "rows": [
    {
      "name": "string",
      "id": "string",
      "active": boolean,
      "startTime": "string",
      "endTime": "string",
      "action": "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 restricts which merchants the card can be used with, specified by their Merchant Category Code (MCC) or Merchant Identifier (MID). Use mcc to scope the control to an entire merchant category or mid to scope it to a specific merchant. Use action to choose whether the control blocks the merchants in scope (BLOCK, the default) or restricts the card to only those merchants (ALLOW). You can update a card’s authorisation control at any point, apart from its action.

On card programmes that support action, the rest of the payload is more restrictive than on those that don’t:

Send exactly one of merchantScope.mcc or merchantScope.mid. Sending both, or neither, returns a 400 response.
merchantScope.mccGroup, startTime and endTime aren’t supported and return a 400 response.
Any id you send is ignored — the control’s id is always generated for you.

The allow-list sample below is shaped for these programmes; the first sample is not.

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

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": "Fuel only",
    "active": true,
    "action": "ALLOW",
    "merchantScope": {
      "mcc": "5541"
    }
  }'

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",
  "action": "string",
  "merchantScope": {
    "mcc": "string",
    "mid": "string",
    "mccGroup": "string"
  }
}'

Path parameters

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

string

required

The ID of the account associated with the card.Allowable values: An existing cardId (≤ 36 characters)

string (uuid)

The ID of the person that the card belongs to.Allowable values: An existing personId (≤ 36 characters)

integer

The maximum number of results to return. By default, this is set to 100.Allowable values: [ 1 .. 1000 ]

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

string

required

The name of the authorisation control.Allowable values: ≤ 255 characters

string (uuid)

Unique identifier of the authorisation control. If you don’t provide one, it’s generated for you. On card programmes that support action, it’s always generated and any id you send is ignored.Allowable values: A valid UUID (≤ 36 characters)

boolean

Whether or not the authorisation control should be active. By default, this is set to true.Allowable values: true, false

string (date-time)

Date and time when the control goes into effect, in UTC. Not supported on card programmes that support action — sending it returns a 400 response.Allowable values: An ISO 8601 datetime, for example 2023-03-14T12:08:53Z

string (date-time)

Date and time when the control ends, in UTC. Not supported on card programmes that support action — sending it returns a 400 response.Allowable values: An ISO 8601 datetime, for example 2023-03-14T12:08:53Z

string

How the control is applied to the merchants in merchantScope. Use BLOCK to stop the card being used with those merchants, or ALLOW to restrict the card to only those merchants. By default, this is set to BLOCK. Not supported on every card programme — see the note at the top of this page.Allowable values: BLOCK, ALLOW

object

Details about the merchant scope. On card programmes that support action, send exactly one of mcc or mid — sending both, or neither, returns a 400 response.Allowable values: A valid merchantScope object containing the following fields: mcc, mid, mccGroup

Show merchantScope properties

string

The merchant category code (MCC).Allowable values: ≤ 4 characters

string

The merchant identifier (MID).Allowable values: ≤ 36 characters

string

The MCC group. You can use the list MCC groups request to get a full list of all available groups. Not supported on card programmes that support action — sending it returns a 400 response.Allowable values: ≤ 36 characters

Response

If your request is successful, you’ll receive a 201 response. The sample below shows every field the endpoint can return. action is only present on card programmes that support it. Programmes that don’t support it omit action and can return startTime, endTime and merchantScope.mccGroup instead — no single response contains all of these.

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

{
  "name": "string",
  "id": "string",
  "active": boolean,
  "startTime": "string",
  "endTime": "string",
  "action": "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.

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'

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

string (uuid)

required

The ID of the card that you want to update an authorisation control for.Allowable values: An existing cardId (≤ 36 characters)

string (uuid)

required

The ID of the authorisation control that you want to update.Allowable values: An existing authControlId (≤ 36 characters)

Query parameters

string

required

The ID of the account that the card is associated with.Allowable values: An existing cardId (≤ 36 characters)

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",
  "action": "BLOCK",
  "merchantScope": {
    "mcc": "3596",
    "mid": "string",
    "mccGroup": "Airlines"
  }
}

{
  "name": "string",
  "id": "string",
  "active": boolean,
  "startTime": "string",
  "endTime": "string",
  "action": "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. You can’t change a control’s action — including action in the request body returns a 400 response. To switch a control between BLOCK and ALLOW, set active to false on the existing control and create a new one with the action you need.

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

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

string

required

The ID of the card that the authorisation control applies to.Allowable values: An existing cardId (≤ 36 characters)

string

required

The ID of the authorisation control that you want to update.Allowable values: An existing authControlId (≤ 36 characters)

Query parameters

string

required

The ID of the account that the card is associated with.Allowable values: An existing accountId

string

The ID of the person that the card belongs to.Allowable values: An existing personId (≤ 36 characters)

Request body schema

string

The name of the authorisation control.Allowable values: ≤ 255 characters

boolean

Whether or not the authorisation control should be active. By default, this is set to true.Allowable values: true, false

object

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

Show merchantScope properties

string

The merchant category code (MCC).Allowable values: ≤ 4 characters

string

The merchant identifier (MID).Allowable values: ≤ 36 characters

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",
  "action": "BLOCK",
  "merchantScope": {
    "mcc": "3596",
    "mid": "string",
    "mccGroup": "Airlines"
  }
}

{
  "name": "string",
  "id": "string",
  "active": boolean,
  "startTime": "string",
  "endTime": "string",
  "action": "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.

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

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

Query parameters

string

required

The ID of the account that the card is associated with.Allowable values: An existing accountId

string

The ID of the person that the card belongs to.Allowable values: An existing personId (≤ 36 characters)

integer

The maximum number of results to return. By default, this is set to 100.Allowable values: [ 1 .. 1000 ]

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

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

​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