Skip to main content
Use the /merchantgroups endpoint to create, update, and retrieve groups of merchant identifiers (MIDs). You can use merchant groups for authorization controls and in card product configurations. For example, use a merchant group to create a merchant exemption for a group of merchants rather than an individual merchant.

​
Create merchant group

Action: POST
Endpoint: /merchantgroups To create a merchant group, send a POST request to the /merchantgroups endpoint.

​
Request body

FieldsDescription
active

boolean

Optional		Indicates if the merchant group is active or not.

Allowable Values:

true, false

Default value:
false
mids

array of strings

Optional		Comma-separated list of alphanumeric merchant identifiers. You can include merchant identifiers in multiple merchant groups.

Allowable Values:

Valid array of one or more merchant identifiers
name

string

Required		Name of the merchant group.

Allowable Values:

1–40 chars
token

string

Optional		Unique identifier of the group.

If you do not include a token, the system will generate one automatically. This token is necessary for use in other API calls, so we recommend that rather than let the system generate one, you use a simple string that is easy to remember. This value cannot be updated.

Allowable Values:

1–36 chars

​
Sample request body

JSON
{
  "token": "my_merchantgroup",
  "name": "My Merchant Group",
  "mids": [
    "123456789012345",
    "345123456789012",
    "123456789012"
  ],
  "active": true
}

​
Response body

FieldsDescription
active

boolean

Conditionally returned		Indicates if the merchant group is active or not.

Allowable Values:

true, false
created_time

datetime

Conditionally returned		Date and time when the resource was created, in UTC.

Allowable Values:

Format: yyyy-MM-ddThh:mm:ssZ
last_modified_time

datetime

Conditionally returned		Date and time when the resource was last modified, in UTC.

Allowable Values:

Format: yyyy-MM-ddThh:mm:ssZ
mids

array of strings

Conditionally returned		Comma-separated list of alphanumeric merchant identifiers.

Allowable Values:

Valid array of one or more merchant identifiers
name

string

Conditionally returned		Name of the merchant group.

Allowable Values:

40 char max
token

string

Conditionally returned		Unique identifier of the merchant group.

Allowable Values:

Existing merchant group token

​
Sample response body

JSON
{
  "token": "my_merchantgroup",
  "name": "My Merchant Group",
  "mids": [
    "123456789012345",
    "345123456789012",
    "123456789012"
  ],
  "active": true,
  "created_time": "2022-05-01T13:22:07Z",
  "last_modified_time": "2022-05-01T13:22:07Z"
}

​
List merchant groups

Action: GET
Endpoint: /merchantgroups To return an array of all merchant groups, send a GET request to the /merchantgroups endpoint. To return an array of all merchant groups that include a specific merchant identifier, send a GET request to the /merchantgroups endpoint that includes the merchant identifier in the query parameters.

​
URL query parameters

FieldsDescription
mid

string

Optional		Returns all merchant groups that contain the specified merchant identifier.

Allowable Values:

Existing merchant identifier
count

integer

Optional		Number of resources to retrieve.

Allowable Values:

1-10

Default value:
10
start_index

integer

Optional		Sort order index of the first resource in the returned array.

Allowable Values:

Any integer

Default value:
0
sort_by

string

Optional		Field on which to sort. Use any field in the resource model, or one of the system fields lastModifiedTime or createdTime. Prefix the field name with a hyphen (-) to sort in descending order. Omit the hyphen to sort in ascending order.

Allowable Values:

createdTime, lastModifiedTime, or any field in the resource model

Default value:
-lastModifiedTime

​
Response body

FieldsDescription
count

integer

Conditionally returned		Number of resources retrieved.

This field is returned if there are resources in your returned array.

Allowable Values:

Any integer
data

array of objects

Conditionally returned		Array of merchant group resources.

Resources are returned as appropriate to your query.

Allowable Values:

Valid array of one or more merchant group objects
data[].active

boolean

Conditionally returned		Indicates if the merchant group is active or not.

Allowable Values:

true, false
data[].created_time

datetime

Conditionally returned		Date and time when the resource was created, in UTC.

Allowable Values:

Format: yyyy-MM-ddThh:mm:ssZ
data[].last_modified_time

datetime

Conditionally returned		Date and time when the resource was last modified, in UTC.

Allowable Values:

Format: yyyy-MM-ddThh:mm:ssZ
data[].mids

array of strings

Conditionally returned		Comma-separated list of alphanumeric merchant identifiers.

Allowable Values:

Valid array of one or more merchant identifiers
data[].name

string

Conditionally returned		Name of the merchant group.

Allowable Values:

40 char max
data[].token

string

Conditionally returned		Unique identifier of the merchant group.

Allowable Values:

Existing merchant group token
end_index

integer

Conditionally returned		The sort order index of the last resource in the returned array.

This field is returned if there are resources in your returned array.

Allowable Values:

Any integer
is_more

boolean

Conditionally returned		A value of true indicates that more unreturned resources exist. A value of false indicates that no more unreturned resources exist.

This field is returned if there are resources in your returned array.

Allowable Values:

true, false
start_index

integer

Conditionally returned		Sort order index of the last resource in the returned array.

This field is returned if there are resources in your returned array.

Allowable Values:

Any integer

​
Sample response body

JSON
{
  "count": 2,
  "start_index": 0,
  "end_index": 1,
  "is_more": false,
  "data": [
    {
      "token": "my_merchantgroup",
      "name": "My Merchant Group",
      "mids": [
        "123456789012345",
        "345123456789012",
        "123456789012"
      ],
      "active": true,
      "created_time": "2022-05-01T13:22:07Z",
      "last_modified_time": "2022-05-01T13:32:07Z"
    },
    {
      "token": "my_merchantgroup_01",
      "name": "My Merchant Group 01",
      "mids": [
        "998877665544331",
        "246813579000"
      ],
      "active": true,
      "created_time": "2021-05-02T01:42:07Z",
      "last_modified_time": "2022-05-02T01:42:07Z"
    }
  ]
}

​
Update merchant group

Action: PUT
Endpoint: /merchantgroups/{token} To update a merchant group, send a PUT request to the /merchantgroups/{token} endpoint. Include the merchant group token path parameter to specify the merchant group to update.

​
URL path parameters

FieldsDescription
token

string

Required		Unique identifier of the merchant group.

Allowable Values:

Existing merchant group token

​
Request body

FieldsDescription
active

boolean

Optional		Indicates if the merchant group is active or not.

Allowable Values:

true, false

Default value:
false
mids

array of strings

Optional		Comma-separated list of alphanumeric merchant identifiers. You can include merchant identifiers in multiple merchant groups.

Allowable Values:

Valid array of one or more merchant identifiers
name

string

Optional		Name of the merchant group.

Allowable Values:

1–40 chars

​
Sample request body

JSON
{
  "name": "My Merchant Group",
  "mids": [
    "234567890123"
  ],
  "active": true
}

​
Response body

FieldsDescription
active

boolean

Conditionally returned		Indicates if the merchant group is active or not.

Allowable Values:

true, false
created_time

datetime

Conditionally returned		Date and time when the resource was created, in UTC.

Allowable Values:

Format: yyyy-MM-ddThh:mm:ssZ
last_modified_time

datetime

Conditionally returned		Date and time when the resource was last modified, in UTC.

Allowable Values:

Format: yyyy-MM-ddThh:mm:ssZ
mids

array of strings

Conditionally returned		Comma-separated list of alphanumeric merchant identifiers.

Allowable Values:

Valid array of one or more merchant identifiers
name

string

Conditionally returned		Name of the merchant group.

Allowable Values:

40 char max
token

string

Conditionally returned		Unique identifier of the merchant group.

Allowable Values:

Existing merchant group token

​
Sample response body

JSON
{
  "token": "my_merchantgroup",
  "name": "My Merchant Group",
  "mids": [
    "123456789012345",
    "345123456789012",
    "123456789012",
    "234567890123"
  ],
  "active": true,
  "created_time": "2022-05-01T13:22:07Z",
  "last_modified_time": "2022-05-01T13:32:07Z"
}

​
Retrieve merchant group

Action: GET
Endpoint: /merchantgroups/{token} To retrieve a specific merchant group, send a GET request to the /merchantgroups/{token} endpoint. Include the merchant group token path parameter to specify the merchant group to return.

​
URL path parameters

FieldsDescription
token

string

Required		Unique identifier of the merchant group.

Allowable Values:

Existing merchant group token

​
Response body

FieldsDescription
active

boolean

Conditionally returned		Indicates if the merchant group is active or not.

Allowable Values:

true, false
created_time

datetime

Conditionally returned		Date and time when the resource was created, in UTC.

Allowable Values:

Format: yyyy-MM-ddThh:mm:ssZ
last_modified_time

datetime

Conditionally returned		Date and time when the resource was last modified, in UTC.

Allowable Values:

Format: yyyy-MM-ddThh:mm:ssZ
mids

array of strings

Conditionally returned		Comma-separated list of alphanumeric merchant identifiers.

Allowable Values:

Valid array of one or more merchant identifiers
name

string

Conditionally returned		Name of the merchant group.

Allowable Values:

40 char max
token

string

Conditionally returned		Unique identifier of the merchant group.

Allowable Values:

Existing merchant group token

​
Sample response body

JSON
{
  "token": "my_merchantgroup",
  "name": "My Merchant Group",
  "mids": [
    "123456789012345",
    "345123456789012",
    "123456789012",
    "234567890123"
  ],
  "active": true,
  "created_time": "2022-05-01T13:22:07Z",
  "last_modified_time": "2022-05-01T13:32:07Z"
}

Related topics

MCC GroupsAccount Holder Groups2021 Release NotesSimulating Advanced TransactionsAbout Transactions