Merchant Groups
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
Copy section link
Action: POST
Endpoint: /merchantgroups
To create a merchant group, send a POST request to the /merchantgroups endpoint.
Request body
Copy section link
| Fields | Description |
|---|---|
active
boolean
|
Indicates if the merchant group is active or not. Allowable Values:
Default Value: |
mids
array of strings
|
A comma-separated list of alphanumeric merchant identifiers. Allowable Values: Each merchant identifier is 2–15 characters in length |
name
string
|
The name of the merchant group. Allowable Values: 1–40 chars |
token
string
|
The 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 |
Response body
Copy section link
| Fields | Description |
|---|---|
active
boolean
|
Indicates if the merchant group is active or not. Allowable Values:
|
created_time
datetime
|
The date and time when the resource was created, in UTC. Allowable Values: yyyy-MM-ddThh:mm:ssZ |
last_modified_time
datetime
|
The date and time when the resource was last modified, in UTC. Allowable Values: yyyy-MM-ddThh:mm:ssZ |
mids
array of strings
|
A comma-separated list of alphanumeric merchant identifiers. Allowable Values: Each merchant identifier is 2–15 characters in length |
name
string
|
The name of the merchant group. Allowable Values: 40 char max |
token
string
|
The unique identifier of the merchant group. Allowable Values: Existing merchant group token |
List merchant groups
Copy section link
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.
This endpoint supports field filtering and pagination.
URL query parameters
Copy section link
| Fields | Description |
|---|---|
mid
string
|
Returns all merchant groups that contain the specified merchant identifier. Allowable Values: A valid merchant identifier |
count
integer
|
The number of resources to retrieve. Allowable Values: 1-10 |
start_index
integer
|
The sort order index of the first resource in the returned array. Allowable Values: Any integer |
sort_by
string
|
Field on which to sort.
Use any field in the resource model, or one of the system fields Allowable Values:
|
Response body
Copy section link
| Fields | Description |
|---|---|
count
integer
|
The number of resources retrieved. Allowable Values: Any integer |
data
array of objects
|
An array of merchant group objects. Allowable Values: A valid merchant group array |
data[].active
boolean
|
Indicates if the merchant group is active or not. Allowable Values:
|
data[].created_time
datetime
|
The date and time when the resource was created, in UTC. Allowable Values: yyyy-MM-ddThh:mm:ssZ |
data[].last_modified_time
datetime
|
The date and time when the resource was last modified, in UTC. Allowable Values: yyyy-MM-ddThh:mm:ssZ |
data[].mids
array of strings
|
A comma-separated list of alphanumeric merchant identifiers. Allowable Values: Each merchant identifier is 2–15 characters in length |
data[].name
string
|
The name of the merchant group. Allowable Values: 40 char max |
data[].token
string
|
The unique identifier of the merchant group. Allowable Values: Existing merchant group token |
end_index
integer
|
The sort order index of the last resource in the returned array. Allowable Values: Any integer |
is_more
boolean
|
A value of Allowable Values:
|
start_index
integer
|
The sort order index of the last resource in the returned array. Allowable Values: Any integer |
Retrieve merchant group
Copy section link
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
Copy section link
| Fields | Description |
|---|---|
token
string
|
The unique identifier of the merchant group. Allowable Values: Existing merchant group token Send a |
Response body
Copy section link
| Fields | Description |
|---|---|
active
boolean
|
Indicates if the merchant group is active or not. Allowable Values:
|
created_time
datetime
|
The date and time when the resource was created, in UTC. Allowable Values: yyyy-MM-ddThh:mm:ssZ |
last_modified_time
datetime
|
The date and time when the resource was last modified, in UTC. Allowable Values: yyyy-MM-ddThh:mm:ssZ |
mids
array of strings
|
A comma-separated list of alphanumeric merchant identifiers. Allowable Values: Each merchant identifier is 2–15 characters in length |
name
string
|
The name of the merchant group. Allowable Values: 40 char max |
token
string
|
The unique identifier of the merchant group. Allowable Values: Existing merchant group token |
Update merchant group
Copy section link
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
Copy section link
| Fields | Description |
|---|---|
token
string
|
The unique identifier of the merchant group. Allowable Values: Existing merchant group token Send a |
Request body
Copy section link
| Fields | Description |
|---|---|
active
boolean
|
Indicates if the merchant group is active or not. Allowable Values:
Default Value: |
mids
array of strings
|
A comma-separated list of alphanumeric merchant identifiers. Allowable Values: Each merchant identifier is 2–15 characters in length |
name
string
|
The name of the merchant group. Allowable Values: 1–40 chars |
Response body
Copy section link
| Fields | Description |
|---|---|
active
boolean
|
Indicates if the merchant group is active or not. Allowable Values:
|
created_time
datetime
|
The date and time when the resource was created, in UTC. Allowable Values: yyyy-MM-ddThh:mm:ssZ |
last_modified_time
datetime
|
The date and time when the resource was last modified, in UTC. Allowable Values: yyyy-MM-ddThh:mm:ssZ |
mids
array of strings
|
A comma-separated list of alphanumeric merchant identifiers. Allowable Values: Each merchant identifier is 2–15 characters in length |
name
string
|
The name of the merchant group. Allowable Values: 40 char max |
token
string
|
The unique identifier of the merchant group. Allowable Values: Existing merchant group token |