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

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

Request body

Fields	Description
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

Fields	Description
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

Fields	Description
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

Fields	Description
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

Fields	Description
token string Required	Unique identifier of the merchant group. Allowable Values: Existing merchant group token

Request body

Fields	Description
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

Fields	Description
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

Fields	Description
token string Required	Unique identifier of the merchant group. Allowable Values: Existing merchant group token

Response body

Fields	Description
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"
}

​Create merchant group

​Request body

​Sample request body

​Response body

​Sample response body

​List merchant groups

​URL query parameters

​Response body

​Sample response body

​Update merchant group

​URL path parameters

​Request body

​Sample request body

​Response body

​Sample response body

​Retrieve merchant group

​URL path parameters

​Response body

​Sample response body

Create merchant group

Request body

Sample request body

Response body

Sample response body

List merchant groups

URL query parameters

Response body

Sample response body

Update merchant group

URL path parameters

Request body

Sample request body

Response body

Sample response body

Retrieve merchant group

URL path parameters

Response body

Sample response body