Group Management Developer Guide {#group-manage-about-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](https://developer.cybersource.com/docs.md "") to find additional technical documentation. Customer Support : For support information about any service, visit the Support Center: [support.visaacceptance.com](http://support.visaacceptance.com "") Recent Revisions to This Document {#group-manage-doc-revisions} =============================================================== 26.07.01 -------- Initial release. Introduction to Managing Groups {#group_management} =================================================== 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 {#group-manage-intro-tasks} ============================================================= 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. {#group-manage-intro-tasks_ol_cnp_ljl_vfc} Create a Group {#group-manage-add} ================================== 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 {#group-manage-create-req} =============================================================== organizationId : The unique identifier of the organization that will own this group. name : The name of the group. Optional Fields for Creating a Group {#group-manage-create-opt} =============================================================== 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 {#group-manage-create-ex-rest} =========================================================== 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 {#group-manage-list} ================================================================= 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 {#group-manage-list-req} ======================================================================= organizationId : The unique identifier of the organization that will own this group. REST Example: Retrieve a List of Groups {#group-manage-list-ex-rest} ==================================================================== 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 {#group-manage-retrieve-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 {#group-manage-retrieve-details-req} ================================================================================ groupId : The unique identifier of the group. REST Example: Retrieve Group Details {#group-manage-retrieve-details-ex-rest} ============================================================================= Request ```keyword 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 {#group-manage-update} =========================================== 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. {#group-manage-update_ul_nm1_4z2_vjc} Endpoints --------- **Production:** `PATCH ``https://api.cybersource.com``/groups/{groupId}` **Test:** `PATCH ``https://apitest.cybersource.com``/groups/{groupId}` Required Fields for Updating Group Details {#group-manage-update-req} ===================================================================== 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 {#group-manage-update-opt} ===================================================================== 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 {#group-manage-update-ex-rest} ================================================================= 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 {#group-manage-delete} ===================================== 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. {#group-manage-delete_ul_nm1_4z2_vjc} Endpoints --------- **Production:** `DELETE ``https://api.cybersource.com``/groups/{groupId}` **Test:** `DELETE ``https://apitest.cybersource.com``/groups/{groupId}` Required Field for Deleting a Group {#group-manage-delete-req} ============================================================== groupId : The unique numeric identifier for an organization group. REST Example: Delete a Group {#group-manage-delete-ex-rest} =========================================================== Request ``` DELETE /groups/{groupId} ``` Response to a Successful Request ``` 200 OK ```