/
10 minute read
March 24, 2022

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

A comma-separated list of alphanumeric merchant identifiers.

Allowable Values:

Each merchant identifier is 2–15 characters in length

name

string
Required

The name of the merchant group.

Allowable Values:

1–40 chars

token

string
Optional

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

active

boolean
Conditionally returned

Indicates if the merchant group is active or not.

Allowable Values:

true, false

created_time

datetime
Conditionally returned

The date and time when the resource was created, in UTC.

Allowable Values:

yyyy-MM-ddThh:mm:ssZ

last_modified_time

datetime
Conditionally returned

The date and time when the resource was last modified, in UTC.

Allowable Values:

yyyy-MM-ddThh:mm:ssZ

mids

array of strings
Conditionally returned

A comma-separated list of alphanumeric merchant identifiers.

Allowable Values:

Each merchant identifier is 2–15 characters in length

name

string
Conditionally returned

The name of the merchant group.

Allowable Values:

40 char max

token

string
Conditionally returned

The unique identifier of the merchant group.

Allowable Values:

Existing merchant group token

Sample request body
JSON
Copied

Is this helpful?

Yes
No
Sample response body
JSON
Copied

Is this helpful?

Yes
No

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.

This endpoint supports field filtering and pagination.

URL query parameters
Fields Description

mid

string
Optional

Returns all merchant groups that contain the specified merchant identifier.

Allowable Values:

A valid merchant identifier

count

integer
Optional

The number of resources to retrieve.

Allowable Values:

1-10

start_index

integer
Optional

The sort order index of the first resource in the returned array.

Allowable Values:

Any integer

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:

lastModifiedTime, createdTime, or any field in the resource model

Response body
Fields Description

count

integer
Conditionally returned

The number of resources retrieved.

Allowable Values:

Any integer

data

array of objects
Conditionally returned

An array of merchant group objects.

Allowable Values:

A valid merchant group array

data[].active

boolean
Conditionally returned

Indicates if the merchant group is active or not.

Allowable Values:

true, false

data[].created_time

datetime
Conditionally returned

The date and time when the resource was created, in UTC.

Allowable Values:

yyyy-MM-ddThh:mm:ssZ

data[].last_modified_time

datetime
Conditionally returned

The date and time when the resource was last modified, in UTC.

Allowable Values:

yyyy-MM-ddThh:mm:ssZ

data[].mids

array of strings
Conditionally returned

A comma-separated list of alphanumeric merchant identifiers.

Allowable Values:

Each merchant identifier is 2–15 characters in length

data[].name

string
Conditionally returned

The name of the merchant group.

Allowable Values:

40 char max

data[].token

string
Conditionally returned

The 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.

Allowable Values:

Any integer

is_more

boolean
Conditionally returned

A value of true indicates that more unreturned resources exist.

Allowable Values:

true, false

start_index

integer
Conditionally returned

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

Allowable Values:

Any integer

Sample response body
JSON
Copied

Is this helpful?

Yes
No

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

The unique identifier of the merchant group.

Allowable Values:

Existing merchant group token

Send a GET request to /merchantgroups to retrieve merchant group tokens.

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

The date and time when the resource was created, in UTC.

Allowable Values:

yyyy-MM-ddThh:mm:ssZ

last_modified_time

datetime
Conditionally returned

The date and time when the resource was last modified, in UTC.

Allowable Values:

yyyy-MM-ddThh:mm:ssZ

mids

array of strings
Conditionally returned

A comma-separated list of alphanumeric merchant identifiers.

Allowable Values:

Each merchant identifier is 2–15 characters in length

name

string
Conditionally returned

The name of the merchant group.

Allowable Values:

40 char max

token

string
Conditionally returned

The unique identifier of the merchant group.

Allowable Values:

Existing merchant group token

Sample response body
JSON
Copied

Is this helpful?

Yes
No

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

The unique identifier of the merchant group.

Allowable Values:

Existing merchant group token

Send a GET request to /merchantgroups to retrieve merchant group tokens.

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

A comma-separated list of alphanumeric merchant identifiers.

Allowable Values:

Each merchant identifier is 2–15 characters in length

name

string
Optional

The name of the merchant group.

Allowable Values:

1–40 chars

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

The date and time when the resource was created, in UTC.

Allowable Values:

yyyy-MM-ddThh:mm:ssZ

last_modified_time

datetime
Conditionally returned

The date and time when the resource was last modified, in UTC.

Allowable Values:

yyyy-MM-ddThh:mm:ssZ

mids

array of strings
Conditionally returned

A comma-separated list of alphanumeric merchant identifiers.

Allowable Values:

Each merchant identifier is 2–15 characters in length

name

string
Conditionally returned

The name of the merchant group.

Allowable Values:

40 char max

token

string
Conditionally returned

The unique identifier of the merchant group.

Allowable Values:

Existing merchant group token

Sample request body
JSON
Copied

Is this helpful?

Yes
No
Sample response body
JSON
Copied

Is this helpful?

Yes
No
Join our developer newsletter