/
10 minute read
February 27, 2023

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
Copied

Is this helpful?

Yes
No

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

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

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
Copied

Is this helpful?

Yes
No

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

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
Copied

Is this helpful?

Yes
No

Subscribe to our developer newsletter