Group Management Developer Guide

This section describes how to use this guide and where to find further information.

Audience and Purpose: This guide provides information about how to implement the Group Management product using the REST API.
Conventions: IMPORTANT

An Important
statement contains information essential to successfully completing a task or learning a concept.
Related Documentation: Visit the Cybersource documentation hub to find additional technical documentation.
Customer Support: For support information about any service, visit the Support Center:
support.visaacceptance.com

Recent Revisions to This Document

26.07.01

Initial release.

Introduction to Managing Groups

The Group Management product enables you to manage merchants within their organizational hierarchy by grouping the merchants by their need to access specific features. This feature provides a centralized platform for overseeing merchant activities by grouped merchant IDs (MIDs).

Grouping MIDs enables streamlined reporting for the selected MIDs in a group. By grouping merchants, businesses can achieve enhanced visibility into their transaction data across locations or business units. Group Management simplifies organizing complex merchant structures into their own groups and provides efficiency in handling merchant-related operations. You can manage your groups using the REST API.

Managing Your Organization Groups

This section explains how to use the REST API to manage your organization groups.

IMPORTANT

An organization can have a maximum of 5,000 groups.

Prerequisites

To gain access to the Group Management feature, users must be assigned a specific account management permission. The Groups Manage permission in Account Management controls access to group management functions enabling the user to view and edit the group (adding and deleting group members).

Group Management restricts user access with these limitations:

When a user is assigned to a group, the user is restricted to that single group and cannot access the Group Management page.

Portfolio users who are not assigned to a group can manage all groups, including the groups that were set up by merchant account users.

Merchant users who are not assigned to a group can manage only groups that are specific to their account.

Transacting organization users cannot create, update, or delete a group.

Create a Group

You can create a group and associate it with a portfolio or merchant account. Organization groups enable logical grouping of merchant accounts for more efficient account management and reporting. Each organization group can contain up to 10,000 MIDs.

IMPORTANT

A maximum of 5,000 groups can be set up in the system for a given organization

IMPORTANT

The owner organization specified in the request has administrative control over the group.

Endpoints

Production:

POST https://api.cybersource.com/groups

Test:

POST https://apitest.cybersource.com/groups

Required Fields for Creating a Group

organizationId: The unique identifier of the organization that will own this group.
name: The name of the group.

Optional Fields for Creating a Group

description: The description of the group that explains the purpose of the group.
selectedOrganizationIds: The list of organization IDs that are members of the group.
type: The group type identifier used to categorize groups for organizational purposes.

REST Example: Create a Group

Request

{
  "groupId": "1234574366",
  "organizationId": "groupmerchant_acct435",
  "name": "Group001",
  "description": "Group",
  "creationDateTime": "2026-04-14 15:11:02",
  "updatedDateTime": "2026-04-14 15:11:02",
  "type": "CustomGroup",
  "selectedOrganizationCount": "5",
  "selectedOrganizationIds": [
    "grptransmerchant001",
    "grptransmerchant002",
    "grptransmerchant003",
    "grptransmerchant004",
    "grptransmerchant005"
  ]
}

Response to a Successful Request

{
  "groupId": "1234574366",
  "organizationId": "groupmerchant_acct435",
  "name": "Group001",
  "description": "Group",
  "creationDateTime": "2026-04-14 15:11:02",
  "updatedDateTime": "2026-04-14 15:11:02",
  "type": "CustomGroup",
  "selectedOrganizationCount": "3",
  "selectedOrganizationIds": [
    "grptransmerchant001",
    "grptransmerchant002",
    "grptransmerchant003"
  ]
}

Retrieve a List of the Groups in a Portfolio

You can retrieve a list of organization groups associated to a portfolio or merchant account. The list provides summary information for each group, including metadata and member count.

Endpoints

Production:

GET https://api.cybersource.com/groups

Test:

GET https://apitest.cybersource.com/groups

Required Field for Retrieving a List of Groups

organizationId: The unique identifier of the organization that will own this group.

REST Example: Retrieve a List of Groups

Request

GET /groups/{organizationId}

Response to a Successful Request

{
  "organizationId": "myorg123",
  "count": 2,
  "_embedded": {
    "groups": [
      {
        "id": "grp_1001",
        "name": "Marketing Campaign Merchants",
        "description": "Q2 2024 Marketing Campaign Merchants",
        "members": [
          "merchant002",
          "merchant003",
          "merchant004"
        ],
        "metadata": {
          "createdTime": "2024-01-10T12:00:00Z",
          "lastUpdatedTime": "2024-04-10T18:45:12Z"
        },
        "_links": {
          "self": {
            "href": "/group-management/v1/groups/grp_1001"
          }
        }
      },
      {
        "id": "grp_1002",
        "name": "High Value Merchants",
        "description": "Top revenue merchants",
        "members": [
          "merchant010",
          "merchant011"
        ],
        "metadata": {
          "createdTime": "2024-02-05T09:30:00Z",
          "lastUpdatedTime": "2024-03-20T15:22:40Z"
        },
        "_links": {
          "self": {
            "href": "/group-management/v1/groups/grp_1002"
          }
        }
      }
    ]
  },
  "_links": {
    "self": {
      "href": "/group-management/v1/groups/myorg123"
    }
  }

Retrieve Group Details

You can retrieve a description of the group and a list of its members.

Endpoints

Production:

GET https://api.cybersource.com/groups/{groupId}

Test:

GET https://apitest.cybersource.com/groups/{groupId}

Required Field for Retrieving Group Details

groupId: The unique identifier of the group.

REST Example: Retrieve Group Details

Request

GET https://api.cybersource.com/groups/123456789

Response to a Successful Request

{
  "groupId": "123456789",
  "organizationId": "test_organization_id",
  "name": "testGroupName",
  "description": "test group description",
  "creationDateTime": "2026-04-14 15:11:02",
  "updatedDateTime": "2026-04-14 15:11:02",
  "type": "CustomGroup",
  "selectedOrganizationCount": 5,
  "selectedOrganizationIds": [
    "test_organization_id1",
    "test_organization_id2",
    "test_organization_id3",
    "test_organization_id4",
    "test_organization_id5"
  ]
}

Update Group Details

You can update an organization group by modifying its description. You can also add organizations to the group, remove organizations from the group, or do both in a single request.

A request to update group details generates a response status code but not a response body. Any of these response codes may be generated:

200

The organization group was successfully updated.

400

The request was invalid or cannot be processed.

401

Authentication credentials are missing or invalid.

403

The request is understood but access is not allowed.

404

The requested resource does not exist.

500

An unexpected system error occurred or the request timed out.

Endpoints

Production:

PATCH https://api.cybersource.com/groups/{groupId}

Test:

PATCH https://apitest.cybersource.com/groups/{groupId}

Required Fields for Updating Group Details

groupId: The unique numeric identifier for a group.

organizationId: The unique identifier of the organization that owns the group.

Optional Fields for Updating Group Details

addOrganizationIds: The list of organization IDs to add as new members to the group.

description: The description of the group that explains the purpose of the group.
removeOrganizationIds: The list of organization IDs to remove from the group.

REST Example: Update Group Details

Request

{
   "organizationId": "test_organization_id",
   "description": "test group description",
   "addOrganizationIds": [
      "test_organization_id1",
      "test_organization_id2"
   ],
   "removeOrganizationIds": [
      "test_organization_id3"
   ]
}

Response to a Successful Request

200 OK

Delete a Group

You can delete an organization group that is no longer needed. Remove the group users from the organization before deleting it. Deleting a group cannot be reversed.

IMPORTANT

Do not delete a group if users are still assigned to the group. While the group will be deleted, the group users will retain their association with the deleted group.

A request to delete a group generates a response status code but not a response body. Any of these response codes may be generated:

200

The organization group was successfully updated.

400

The request was invalid or cannot be processed.

401

Authentication credentials are missing or invalid.

403

The request is understood but access is not allowed.

404

The requested resource does not exist.

500

An unexpected system error occurred or the request timed out.

Endpoints

Production:

DELETE https://api.cybersource.com/groups/{groupId}

Test:

DELETE https://apitest.cybersource.com/groups/{groupId}

Required Field for Deleting a Group

groupId: The unique numeric identifier for an organization group.

REST Example: Delete a Group

Request

DELETE /groups/{groupId}

Response to a Successful Request

200 OK