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
|
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
|
Name of the merchant group. Allowable Values: 1–40 chars |
token
string
|
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
|
Date and time when the resource was created, in UTC. Allowable Values: Format: yyyy-MM-ddThh:mm:ssZ |
last_modified_time
datetime
|
Date and time when the resource was last modified, in UTC. Allowable Values: Format: yyyy-MM-ddThh:mm:ssZ |
mids
array of strings
|
Comma-separated list of alphanumeric merchant identifiers. Allowable Values: Valid array of one or more merchant identifiers |
name
string
|
Name of the merchant group. Allowable Values: 40 char max |
token
string
|
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.
URL query parameters
Copy section link
| Fields | Description |
|---|---|
mid
string
|
Returns all merchant groups that contain the specified merchant identifier. Allowable Values: Existing merchant identifier |
count
integer
|
Number of resources to retrieve. Allowable Values: 1-10 Default value: |
start_index
integer
|
Sort order index of the first resource in the returned array. Allowable Values: Any integer Default value: |
sort_by
string
|
Field on which to sort.
Use any field in the resource model, or one of the system fields Allowable Values:
Default value: |
Response body
Copy section link
| Fields | Description |
|---|---|
count
integer
|
Number of resources retrieved. This field is returned if there are resources in your returned array. Allowable Values: Any integer |
data
array of objects
|
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
|
Indicates if the merchant group is active or not. Allowable Values:
|
data[].created_time
datetime
|
Date and time when the resource was created, in UTC. Allowable Values: Format: yyyy-MM-ddThh:mm:ssZ |
data[].last_modified_time
datetime
|
Date and time when the resource was last modified, in UTC. Allowable Values: Format: yyyy-MM-ddThh:mm:ssZ |
data[].mids
array of strings
|
Comma-separated list of alphanumeric merchant identifiers. Allowable Values: Valid array of one or more merchant identifiers |
data[].name
string
|
Name of the merchant group. Allowable Values: 40 char max |
data[].token
string
|
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. This field is returned if there are resources in your returned array. Allowable Values: Any integer |
is_more
boolean
|
A value of This field is returned if there are resources in your returned array. Allowable Values:
|
start_index
integer
|
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 |
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
|
Unique identifier of the merchant group. Allowable Values: Existing merchant group token |
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
|
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
|
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
|
Date and time when the resource was created, in UTC. Allowable Values: Format: yyyy-MM-ddThh:mm:ssZ |
last_modified_time
datetime
|
Date and time when the resource was last modified, in UTC. Allowable Values: Format: yyyy-MM-ddThh:mm:ssZ |
mids
array of strings
|
Comma-separated list of alphanumeric merchant identifiers. Allowable Values: Valid array of one or more merchant identifiers |
name
string
|
Name of the merchant group. Allowable Values: 40 char max |
token
string
|
Unique identifier of the merchant group. Allowable Values: Existing merchant group token |
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
|
Unique identifier of the merchant group. Allowable Values: Existing merchant group token |
Response body
Copy section link
| Fields | Description |
|---|---|
active
boolean
|
Indicates if the merchant group is active or not. Allowable Values:
|
created_time
datetime
|
Date and time when the resource was created, in UTC. Allowable Values: Format: yyyy-MM-ddThh:mm:ssZ |
last_modified_time
datetime
|
Date and time when the resource was last modified, in UTC. Allowable Values: Format: yyyy-MM-ddThh:mm:ssZ |
mids
array of strings
|
Comma-separated list of alphanumeric merchant identifiers. Allowable Values: Valid array of one or more merchant identifiers |
name
string
|
Name of the merchant group. Allowable Values: 40 char max |
token
string
|
Unique identifier of the merchant group. Allowable Values: Existing merchant group token |