# RevCent Gateway Group Overview This document explains Gateway Groups in RevCent at a broad level. It is not an operation-specific guide. Instead, it explains what Gateway Groups are, why they matter, how they work with User Gateways, and why ecommerce businesses should use them as part of RevCent payment routing. Sources: - RevCent Gateway Group operation schemas - RevCent Add/Remove User Gateway to/from Gateway Group operation schemas - RevCent Payment Profile routing concepts --- # What Is a Gateway Group? A Gateway Group is a named collection of User Gateways. In RevCent: ```text User Gateway = an actual configured gateway/MID in the user's account. Gateway Group = a collection of User Gateways grouped for organization and payment routing. ``` A Gateway Group can contain one or more User Gateways. Example: ```text Brand A Gateways - Brand A NMI Primary - Brand A NMI Backup - Brand A Authorize.net Reserve ``` Another example: ```text Subscription Renewal Gateways - Renewal MID 1 - Renewal MID 2 - Renewal Backup Gateway ``` Gateway Groups are useful because ecommerce businesses often need different sets of gateways for different parts of the business. --- # Why Gateway Groups Matter Gateway Groups make payment routing easier, safer, and more maintainable. Without Gateway Groups, payment profiles may need to reference individual gateways directly. With Gateway Groups, a payment profile can reference a group. That means the user can change which gateways are included in a routing path by changing the Gateway Group membership instead of editing the payment profile itself. Conceptually: ```text Payment Profile Choose Gateway Node ↓ Uses Gateway Group: Brand A Gateways ↓ Brand A Gateways contains Gateway A, Gateway B, Gateway C ↓ RevCent chooses from the gateways in that group ``` Later, the business can change the group: ```text Brand A Gateways now contains Gateway A, Gateway C, Gateway D ``` The payment profile can continue pointing to the same Gateway Group. This is one of the biggest benefits of Gateway Groups. --- # Gateway Groups vs User Gateways ## User Gateway A User Gateway is an individual configured payment gateway/MID. Examples: ```text Brand A - NMI Primary MID 845678 Brand A - Authorize.net Backup MID 1234 Brand B - Stripe Main Gateway Subscription Renewals - NMI Gateway ``` A User Gateway has its own settings, such as: - Enabled status - Site Gateway association - Credentials - Custom descriptor - Merchant account ID - Fees - Cascade rules - SmartBIN metadata ## Gateway Group A Gateway Group organizes multiple User Gateways. Examples: ```text Brand A Gateways Brand B Gateways US Initial Sale Gateways Subscription Renewal Gateways Trial Expiration Gateways Backup Gateways ``` A Gateway Group has: - Gateway Group ID - Name - Description - Enabled status - User Gateway membership array The group does not replace individual gateway settings. Each User Gateway still has its own cascade rules, enabled status, credentials, SmartBIN metadata, and other configuration. --- # How Gateway Groups Work With Payment Profiles Payment profiles are where RevCent decides how payments should be processed. A payment profile can include a Choose Gateway node. A Choose Gateway node can choose from a gateway source, including a Gateway Group. That makes Gateway Groups a key part of payment routing. Conceptually: ```text Customer attempts payment ↓ Payment profile starts ↓ Choose Gateway node uses a Gateway Group ↓ RevCent evaluates gateways in that group ↓ Eligible gateway is selected ↓ Payment is processed ``` Gateway Groups are useful because they create a stable target for payment profiles. Instead of editing the payment profile every time a gateway is added, removed, or replaced, the user can often modify the Gateway Group. --- # Why This Is Valuable for Ecommerce Businesses Ecommerce businesses rarely have one simple payment routing need forever. As a business grows, it may have: - Multiple brands - Multiple stores - Multiple websites - Multiple corporations or business entities - Multiple MIDs - Multiple processors - Different gateways for initial sales - Different gateways for subscription renewals - Different gateways for trial expirations - Different backup gateways - Different routing strategies by risk or transaction type Gateway Groups help organize this complexity. They allow a RevCent account to keep payment routing clean and understandable. --- # Common Gateway Group Use Cases ## Brand-Based Routing A business with multiple brands may want each brand to use only its own gateways. Example: ```text Brand A Gateways - Brand A Gateway 1 - Brand A Gateway 2 Brand B Gateways - Brand B Gateway 1 - Brand B Gateway 2 ``` Payment profile routing: ```text Brand A Payment Profile → Choose Gateway from Brand A Gateways Brand B Payment Profile → Choose Gateway from Brand B Gateways ``` This helps avoid accidentally routing Brand A transactions through Brand B merchant accounts. --- ## Corporation or Business Entity Routing Some RevCent accounts may operate multiple corporations or business entities. Gateway Groups can separate gateways by entity. Example: ```text Corp A Gateways Corp B Gateways ``` This is important because one corporation should not accidentally process through another corporation's merchant account. --- ## Initial Sale vs Renewal Routing Initial sales and subscription renewals may have different routing needs. Example: ```text Initial Sale Gateways Subscription Renewal Gateways Trial Expiration Gateways ``` A business may want renewals to use specific gateways or MIDs that are better suited for recurring billing. Gateway Groups let those sets be organized clearly. --- ## Backup Gateway Pools A business can create backup gateway groups. Example: ```text Primary Gateways Backup Gateways Reserve Gateways ``` Payment profiles can route to backup gateways if primary gateways decline, become ineligible, or are disabled. --- ## SmartBIN Candidate Groups If SmartBIN is enabled in a payment profile Choose Gateway node, the Gateway Group used by that node can define the candidate gateway set. Example: ```text Choose Gateway node uses SmartBIN Gateway source = Brand A Gateways SmartBIN scores eligible gateways inside Brand A Gateways ``` Changing Gateway Group membership can change which gateways SmartBIN can score. This means Gateway Groups are important for controlling SmartBIN's available gateway pool. --- # Gateway Groups and Cascade Rules Gateway Groups and cascade rules work together, but they are different concepts. ```text Gateway Group = which gateways are available to a routing path. Cascade Rules = whether an individual gateway is eligible at the moment of selection. ``` Example: ```text Brand A Gateways contains Gateway A, Gateway B, Gateway C. ``` Gateway A has a cascade rule: ```text Do not use after $10,000 captured in the last day. ``` If Gateway A is over that limit: ```text Gateway A is skipped. Gateway B and Gateway C may still be eligible. ``` The group provides the candidate pool. Each gateway's own rules determine whether it can be used for a specific transaction. --- # Gateway Groups and Enabled Status A Gateway Group has its own enabled status. User Gateways inside the group also have their own enabled status. For a Gateway Group to be useful in live payment routing: ```text The Gateway Group should be enabled. The User Gateways inside the group should be enabled and ready. The User Gateways should have valid credentials. The payment profile should be configured to use the group. ``` A group containing only disabled gateways may not provide a useful route. A disabled Gateway Group used by a live payment profile may cause routing problems depending on the payment profile design. --- # Managing Gateway Group Membership Gateway Group membership can be managed in three main ways: ```text CreateGatewayGroup with initial user_gateway array EditGatewayGroup with replacement user_gateway array AddUserGatewayToGatewayGroup / RemoveUserGatewayFromGatewayGroup for incremental changes ``` --- ## Initial Membership During Creation When creating a Gateway Group, the user can include an initial `user_gateway` array. Example: ```json { "name": "Brand A Gateways", "description": "Gateway group for Brand A payment routing.", "enabled": true, "user_gateway": [ "AAAAAAAAAAAAAAAAAAAA", "BBBBBBBBBBBBBBBBBBBB" ] } ``` This is useful when the group should be created with known gateways immediately. --- ## Full Membership Replacement With EditGatewayGroup `EditGatewayGroup` can update the `user_gateway` array. Important: ```text If user_gateway is provided to EditGatewayGroup, it replaces the full current gateway array. ``` Example current group: ```text Brand A Gateways = Gateway A + Gateway B + Gateway C ``` Edit request: ```json { "gateway_group_id": "GGGGGGGGGGGGGGGGGGGG", "user_gateway": [ "AAAAAAAAAAAAAAAAAAAA" ] } ``` Result: ```text Brand A Gateways = Gateway A only ``` Gateway B and Gateway C are removed. This behavior is powerful but risky. Providing an empty array removes all gateways from the group. ```json { "gateway_group_id": "GGGGGGGGGGGGGGGGGGGG", "user_gateway": [] } ``` Result: ```text Brand A Gateways has no gateways. ``` This may break payment routing if a payment profile relies on that group. --- ## Incremental Add/Remove Operations For ordinary membership changes, the safer approach is usually: ```text AddUserGatewayToGatewayGroup RemoveUserGatewayFromGatewayGroup ``` Use Add when the user wants to add gateways without removing existing gateways. Use Remove when the user wants to remove gateways while leaving the rest of the group intact. Example Add: ```json { "gateway_group_id": "GGGGGGGGGGGGGGGGGGGG", "user_gateway": [ "DDDDDDDDDDDDDDDDDDDD" ] } ``` Example Remove: ```json { "gateway_group_id": "GGGGGGGGGGGGGGGGGGGG", "user_gateway": [ "BBBBBBBBBBBBBBBBBBBB" ] } ``` This avoids accidentally replacing the whole group. --- # Why Group Membership Changes Can Be Safer Than Payment Profile Edits Payment profiles define the actual payment flow. Editing a payment profile can be high-impact because it can change: - Gateway selection - Retry logic - Fallback paths - Payment processing nodes - Decline behavior - Custom error behavior - Payment flow structure Gateway Group membership changes are often narrower. Example: ```text Payment profile already uses Brand A Gateways. User wants to include a new Brand A backup gateway. ``` Instead of editing the payment profile: ```text Add the new gateway to Brand A Gateways. ``` The payment profile stays stable. This is a cleaner operational model. --- # Example: Adding a Gateway Without Editing the Payment Profile Existing setup: ```text Payment profile Choose Gateway node → Brand A Gateways Brand A Gateways = Gateway A + Gateway B ``` New gateway: ```text Gateway C ``` Action: ```text AddUserGatewayToGatewayGroup ``` New group: ```text Brand A Gateways = Gateway A + Gateway B + Gateway C ``` The payment profile still points to Brand A Gateways. No payment profile flow edit is required. --- # Example: Removing a Gateway From Routing Existing setup: ```text Payment profile Choose Gateway node → Brand A Gateways Brand A Gateways = Gateway A + Gateway B + Gateway C ``` Gateway B should no longer receive traffic. Action: ```text RemoveUserGatewayFromGatewayGroup ``` New group: ```text Brand A Gateways = Gateway A + Gateway C ``` The payment profile can keep using the same Gateway Group. --- # Best Practices ## Use Gateway Groups in Payment Profiles When possible, use Gateway Groups in payment profile Choose Gateway nodes instead of hardcoding individual gateways. This is especially useful for: - Multi-brand accounts - Multi-corp accounts - Multiple MIDs - Backup routing - SmartBIN candidate pools - Renewal-specific routing - Trial-expiration routing - Regional routing --- ## Keep Groups Specific Specific groups are safer than broad groups. Better: ```text Brand A Initial Sale Gateways Brand A Renewal Gateways Brand B Trial Expiration Gateways US Backup Gateways ``` Riskier: ```text All Gateways ``` Broad groups can accidentally allow the wrong gateway to be used for the wrong brand, business, or payment type. --- ## Use Clear Descriptions A Gateway Group description should explain: - What the group is for - Which payment profiles should use it - Which gateways belong in it - Which gateways should not belong in it - Whether it is for initial sales, renewals, trials, backup, or recovery - Whether SmartBIN may use this group as a candidate set - Whether only specific brands/corps should use it 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. ``` --- ## Prefer Add/Remove for Small Changes For adding or removing specific gateways, prefer: ```text AddUserGatewayToGatewayGroup RemoveUserGatewayFromGatewayGroup ``` Use full `EditGatewayGroup.user_gateway` replacement only when the desired final membership array is known and intentional. --- ## Retrieve Before Major Edits Before changing a Gateway Group, retrieve it first. Review: ```text id name description enabled user_gateway ``` This prevents accidental membership loss. --- ## Consider Live Payment Impact Gateway Group changes can affect live payment routing. Before changing a group used in a payment profile, consider: - Is the group used by live checkout? - Is it used by renewals? - Is it used by trials or recovery? - Are there enough enabled gateways remaining? - Are cascade rules likely to make some gateways ineligible? - Is SmartBIN using this group as its candidate set? - Does the payment profile have fallback behavior? --- # Common Mistakes ## Mistake: Confusing User Gateways and Site Gateways Gateway Groups contain User Gateway IDs. They do not contain Site Gateway IDs. ## Mistake: Using EditGatewayGroup to Add One Gateway If the user only wants to add one gateway, do not send: ```json { "user_gateway": [ "NEW_GATEWAY_ID" ] } ``` unless the user intentionally wants the group to contain only that one gateway. Use: ```text AddUserGatewayToGatewayGroup ``` instead. ## Mistake: Emptying a Live Group Sending: ```json { "user_gateway": [] } ``` removes all gateways from the group. This can break payment routing if a live payment profile uses the group. ## Mistake: Creating Overly Broad Groups A group like: ```text All Gateways ``` may be risky if gateways belong to different brands, corporations, stores, or payment use cases. ## Mistake: Forgetting SmartBIN Candidate Impact If a SmartBIN-enabled Choose Gateway node uses a Gateway Group, changing group membership changes the gateways SmartBIN can score. --- # Business Value Summary Gateway Groups help ecommerce businesses use RevCent as a payment routing platform instead of just a collection of gateway credentials. They provide: - Cleaner gateway organization - Safer payment profile design - Easier inclusion/exclusion of gateways - Better brand/corp separation - Better renewal and trial routing - Easier backup gateway management - Cleaner SmartBIN candidate sets - Less need to edit payment profiles for routine gateway changes In short: ```text Gateway Groups let businesses organize gateways around how payments should actually be routed. ``` They are one of the key building blocks that make RevCent useful for advanced ecommerce payment routing. --- # Key Takeaways ```text Gateway Groups are collections of User Gateways. ``` ```text Gateway Groups are useful in payment profile Choose Gateway nodes. ``` ```text Changing group membership can include or exclude gateways without editing the payment profile itself. ``` ```text EditGatewayGroup.user_gateway replaces the full gateway array if provided. ``` ```text AddUserGatewayToGatewayGroup and RemoveUserGatewayFromGatewayGroup are safer for incremental changes. ``` ```text Gateway Groups work with User Gateway cascade rules and SmartBIN to support advanced payment routing. ``` --- 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.