# RevCent MCP Operation: `CreateGatewayGroup` This document explains how MCP/AI clients should use the `CreateGatewayGroup` operation in RevCent. A Gateway Group is a named collection of User Gateways. Gateway Groups are useful for organizing gateways and for payment profile routing, especially inside Choose Gateway nodes. Sources: - RevCent operation schema for `CreateGatewayGroup` - RevCent operation schema for `GetGatewayGroup` - RevCent operation schema for `GetGatewayGroups` - RevCent operation schema for `AddUserGatewayToGatewayGroup` - RevCent operation schema for `RemoveUserGatewayFromGatewayGroup` - RevCent payment profile schema and payment routing behavior --- ## Operation Summary `CreateGatewayGroup` creates a new Gateway Group and returns a 20-character `gateway_group_id`. A Gateway Group can be created: ```text With no gateways initially With one or more User Gateway IDs in the user_gateway array ``` Gateway Groups can later be modified by either: ```text EditGatewayGroup AddUserGatewayToGatewayGroup RemoveUserGatewayFromGatewayGroup ``` --- # Why Gateway Groups Exist Gateway Groups let a RevCent user organize multiple User Gateways into logical payment-routing sets. Examples: ```text Brand A Gateways Brand B Gateways US Initial Sale Gateways Subscription Renewal Gateways Trial Expiration Gateways Backup Gateways High Approval Gateways Low Risk Gateways Corporate Entity A Gateways Corporate Entity B Gateways ``` A Gateway Group is especially useful when a RevCent account has: - Multiple brands - Multiple stores - Multiple websites - Multiple corporations or business entities - Multiple MIDs - Multiple processors - Separate initial-sale and renewal routing - Separate trial-expiration routing - Separate backup gateway pools - Payment profiles that should route to a group rather than hardcoding individual gateways --- # Gateway Groups and Payment Profiles Gateway Groups are very useful in payment profile Choose Gateway nodes. A payment profile Choose Gateway node can route to a Gateway Group instead of selecting an individual User Gateway. This is powerful because the payment profile can continue pointing at the same Gateway Group while the user changes which gateways are inside the group. Conceptually: ```text Payment profile Choose Gateway node ↓ Uses Gateway Group: Brand A Gateways ↓ Gateway Group contains User Gateway A, B, and C ↓ RevCent chooses from the group according to payment profile logic ``` Later, the user can add or remove gateways from the group: ```text Brand A Gateways now contains User Gateway A, C, and D ``` The payment profile can keep using the same Gateway Group ID. That means: ```text You can include/exclude gateways by editing the Gateway Group membership instead of editing the payment profile itself. ``` This is one of the biggest operational benefits of Gateway Groups. --- ## Why This Matters Payment profiles are critical payment-routing infrastructure. Editing a payment profile can be high risk because it changes the payment flow itself. Gateway Groups provide a safer organizational layer. For example: ```text Payment profile routes to Brand A Gateway Group. A new Brand A backup gateway is created. Instead of editing the payment profile, add the new gateway to Brand A Gateway Group. ``` This keeps the payment profile flow stable while allowing gateway membership to evolve. --- # Required Fields | Field | Type | Required | Description | |---|---:|---:|---| | `name` | string | Yes | Gateway Group name. Must be unique across Gateway Groups. | --- # Optional Fields | Field | Type | Description | |---|---:|---| | `description` | string | Gateway Group description. | | `enabled` | boolean | Whether the Gateway Group is currently enabled. | | `user_gateway` | array | Array of 20-character User Gateway IDs to associate with the group. | The schema has: ```json "additionalProperties": false ``` Do not send unknown fields. --- # `name` The Gateway Group name must be unique. A good name should describe the group’s routing purpose. Good examples: ```text Brand A Gateways Brand B Gateways US Initial Sale Gateways Subscription Renewal Gateways Trial Expiration Gateways Backup Gateways Corporate Entity A Gateways ``` Poor examples: ```text Gateways Group Test Primary Main ``` A Gateway Group name should be understandable to a human reviewing a payment profile. --- # `description` The description should explain: - Which brand/business/corp the group belongs to - Which User Gateways should be included - Which payment profiles should use it - Whether the group is for initial sales, renewals, trials, recovery, backup, or another purpose - Whether the group should contain only live/enabled gateways - Whether the group is tied to a specific website, campaign, or store Good example: ```text Gateway group for Brand A US initial sale payment routing. Used by Brand A payment profile Choose Gateway nodes. Only include Brand A corporate MIDs and active US processing gateways. ``` Another example: ```text Subscription renewal gateway group for Brand B. Used by subscription payment profiles to route renewals through renewal-specific MIDs. ``` --- # `enabled` `enabled` controls whether the Gateway Group is currently enabled. If a Gateway Group is used in a live payment profile Choose Gateway node, it should normally be enabled. If the group is being prepared but should not yet be used, create it disabled: ```json "enabled": false ``` Enable it only after: 1. The correct gateways have been added. 2. The gateways are themselves enabled and ready. 3. The payment profile routing is ready to use the group. 4. The user understands that live payments may route through the group. --- # `user_gateway` `user_gateway` is an array of 20-character User Gateway IDs associated with the Gateway Group. Example: ```json { "user_gateway": [ "AAAAAAAAAAAAAAAAAAAA", "BBBBBBBBBBBBBBBBBBBB", "CCCCCCCCCCCCCCCCCCCC" ] } ``` Important: ```text Gateway Groups contain User Gateway IDs. They do not contain Site Gateway IDs. ``` MCP/AI should verify that each ID is a User Gateway ID before adding it to a group. --- # Creating a Gateway Group With Gateways Already Included You can create a Gateway Group and set the initial gateway membership in one request. Example: ```json { "name": "Brand A Gateways", "description": "Gateway group for Brand A payment profile routing. Used by Brand A Choose Gateway nodes.", "enabled": true, "user_gateway": [ "AAAAAAAAAAAAAAAAAAAA", "BBBBBBBBBBBBBBBBBBBB" ] } ``` Use this when: - The user already knows which gateways belong in the group. - The gateways already exist. - The group should be ready immediately after creation. - The payment profile should be able to use this group right away. --- # Creating an Empty Gateway Group You can also create a group without gateways. Example: ```json { "name": "Brand A Backup Gateways", "description": "Backup gateway group for Brand A. Gateways will be added after setup/testing.", "enabled": false } ``` Use this when: - Gateways have not been created yet. - The group is part of a planned routing structure. - The user wants to prepare payment profile logic before adding live gateways. - The group should not be active until gateways are verified. --- # Add/Remove Operations After Creation After a Gateway Group is created, MCP/AI can manage membership with: ```text AddUserGatewayToGatewayGroup RemoveUserGatewayFromGatewayGroup ``` These operations are safer when the user only wants to add or remove specific gateways. --- ## AddUserGatewayToGatewayGroup Use this operation when the user wants to add one or more gateways to an existing group without replacing the full group membership. Example: ```json { "gateway_group_id": "GGGGGGGGGGGGGGGGGGGG", "user_gateway": [ "DDDDDDDDDDDDDDDDDDDD" ] } ``` Use this when: ```text Add this new backup gateway to Brand A Gateways. Add these two new renewal gateways to the Subscription Renewal group. Include this newly approved MID in the payment profile's gateway group. ``` --- ## RemoveUserGatewayFromGatewayGroup Use this operation when the user wants to remove one or more gateways from an existing group without replacing the full group membership. Example: ```json { "gateway_group_id": "GGGGGGGGGGGGGGGGGGGG", "user_gateway": [ "BBBBBBBBBBBBBBBBBBBB" ] } ``` Use this when: ```text Remove this gateway from Brand A Gateways. Stop including this MID in renewal routing. Take this disabled gateway out of the backup group. ``` --- # Create vs Add/Remove Decision Use `CreateGatewayGroup.user_gateway` when: ```text The group does not exist yet. The user knows the initial full list of gateways. The request is to create a new group with those gateways. ``` Use `AddUserGatewayToGatewayGroup` when: ```text The group already exists. The user wants to add gateways. Existing group membership should remain. ``` Use `RemoveUserGatewayFromGatewayGroup` when: ```text The group already exists. The user wants to remove gateways. Other gateways in the group should remain. ``` Do not use `EditGatewayGroup.user_gateway` to add or remove one gateway unless you intentionally provide the complete final membership list. --- # Gateway Groups as Stable Payment Profile References A major benefit of Gateway Groups is that payment profiles can reference the group rather than the individual gateways. This means gateway membership can change without changing the payment profile. Example: ```text Payment profile Choose Gateway node uses: Gateway Group = Brand A Gateways ``` Initial group: ```text Brand A Gateways = Gateway A + Gateway B ``` Later group: ```text Brand A Gateways = Gateway A + Gateway C + Gateway D ``` The payment profile can continue using the same Gateway Group. This is useful because payment profile edits can be more consequential than gateway group membership changes. --- # Best Practices ## Prefer Gateway Groups for Payment Profile Routing When possible, use Gateway Groups in payment profile Choose Gateway nodes instead of hardcoding individual gateways. This is especially useful for accounts with multiple: - Brands - Corporations - MIDs - Processors - Websites - Stores - Regions - Payment request types - Backup routing strategies --- ## Keep Groups Specific Avoid overly broad groups like: ```text All Gateways ``` unless the user intentionally wants every gateway available for a specific routing path. Better: ```text Brand A Initial Sale Gateways Brand A Subscription Renewal Gateways Brand B Trial Expiration Gateways US Backup Gateways ``` Specific groups reduce the chance that the wrong gateway is used for the wrong business or payment type. --- ## Use Enabled Gateways in Live Groups A live payment profile Choose Gateway node should generally point at a Gateway Group that contains enabled, ready-to-use User Gateways. A group that contains only disabled gateways may not provide useful routing. Before using a group in live routing: 1. Confirm the group is enabled. 2. Confirm included User Gateways are enabled. 3. Confirm included User Gateways have valid credentials. 4. Confirm cascade rules are intentional. 5. Confirm SmartBIN metadata is prepared if SmartBIN will be used. 6. Confirm the payment profile has fallback/failsafe logic if needed. --- # Example: Brand-Based Routing A RevCent account has two brands: ```text Brand A Brand B ``` Each brand has separate MIDs. Gateway Groups: ```text Brand A Gateways Brand B Gateways ``` Payment profiles: ```text Brand A Payment Profile → Choose Gateway node uses Brand A Gateways Brand B Payment Profile → Choose Gateway node uses Brand B Gateways ``` This avoids routing Brand A payments through Brand B gateways. --- # Example: Renewal-Specific Routing A subscription business may have: ```text Initial Sale Gateways Subscription Renewal Gateways Trial Expiration Gateways ``` Each group can be used in a different payment profile or payment flow path. This allows the business to tune gateway routing based on the payment request type. --- # Example: Adding a New Backup Gateway Without Editing the Payment Profile Existing setup: ```text Payment profile Choose Gateway node → Brand A Gateways Brand A Gateways = Gateway A + Gateway B ``` User creates a new gateway: ```text Gateway C ``` Instead of editing the payment profile, MCP can use: ```text AddUserGatewayToGatewayGroup ``` New setup: ```text Brand A Gateways = Gateway A + Gateway B + Gateway C ``` The payment profile still points to the same group. --- # MCP Creation Workflow Before calling `CreateGatewayGroup`, MCP should: 1. Confirm the user wants a new Gateway Group. 2. Determine the group purpose. 3. Choose a clear, unique name. 4. Write a useful description. 5. Determine whether the group should be enabled. 6. Determine whether gateways should be included at creation. 7. Verify any provided User Gateway IDs. 8. Confirm the IDs are User Gateways, not Site Gateways. 9. Consider whether this group will be used in a payment profile Choose Gateway node. 10. Explain that future gateway additions/removals can often be done by updating the group rather than editing the payment profile. --- # Validation Checklist Before submitting `CreateGatewayGroup`: 1. `name` is present. 2. `name` is unique across Gateway Groups. 3. `description` explains the group purpose. 4. `enabled` is intentional. 5. If `user_gateway` is provided, each value is a 20-character User Gateway ID. 6. If the group will be used in live payment routing, included gateways are enabled and ready. 7. The group is specific enough to avoid cross-brand or cross-corp routing mistakes. 8. MCP understands whether future membership changes should use Add/Remove operations. 9. No unknown fields are included. --- # Output Schema Successful response: ```json { "api_call_id": "XXXXXXXXXXXXXXXXXXXX", "api_call_unix": 1740000000, "code": 1, "gateway_group_id": "GGGGGGGGGGGGGGGGGGGG", "result": "..." } ``` --- # Key Takeaways ```text CreateGatewayGroup creates a named group of User Gateways. ``` ```text The user_gateway array can set initial gateway membership. ``` ```text Gateway Groups are especially useful in payment profile Choose Gateway nodes. ``` ```text Changing Gateway Group membership can include/exclude gateways without modifying the payment profile itself. ``` ```text Use AddUserGatewayToGatewayGroup / RemoveUserGatewayFromGatewayGroup for safer incremental membership changes after creation. ``` --- Document Parent Directory * [Operations](https://revcent.com/documentation/markdown/mcp/operation/index.md) - AI/MCP details and overviews for operations available within the RevCent MCP.