# RevCent MCP Operation: `EditGatewayGroup`

This document explains how MCP/AI clients should use the `EditGatewayGroup` 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 `EditGatewayGroup`
- 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

`EditGatewayGroup` edits an existing Gateway Group using a 20-character `gateway_group_id`.

The operation can update:

```text
name
description
enabled
user_gateway
```

Important:

```text
If user_gateway is provided, it replaces the current gateway group gateway array with the provided array.
Providing an empty array removes all gateways from the group.
```

This is the most important behavior MCP/AI must understand.

---

# Gateway Groups and Payment Profiles

Gateway Groups are often used in payment profile Choose Gateway nodes.

A payment profile can point at a Gateway Group instead of a single User Gateway.

This allows the business to modify which gateways are available for that 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
  ↓
Gateway Group contains User Gateway A, B, and C
  ↓
RevCent chooses from that group according to payment profile logic
```

If the business later wants to remove Gateway B and add Gateway D, it can update the group:

```text
Brand A Gateways = Gateway A + Gateway C + Gateway D
```

The payment profile can keep referencing the same Gateway Group.

---

# Required Field

| Field | Type | Required | Description |
|---|---:|---:|---|
| `gateway_group_id` | string | Yes | 20-character Gateway Group ID. |

---

# Editable Fields

| Field | Type | Description |
|---|---:|---|
| `name` | string | Gateway Group name. Must be unique across Gateway Groups. |
| `description` | string | Gateway Group description. |
| `enabled` | boolean | Whether the Gateway Group is currently enabled. |
| `user_gateway` | array<string> | Array of 20-character User Gateway IDs. If provided, this replaces the full current gateway array. |

The schema has:

```json
"additionalProperties": false
```

Do not send unknown fields.

---

# Critical Rule: `user_gateway` Replaces the Full Gateway Array

`EditGatewayGroup.user_gateway` is not an add-one or remove-one operation.

It is a full replacement of the Gateway Group's current gateway membership.

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 from the group.

---

## Empty Array Removes All Gateways

If MCP sends:

```json
{
  "gateway_group_id": "GGGGGGGGGGGGGGGGGGGG",
  "user_gateway": []
}
```

the group will have no gateways.

This may break payment routing if a payment profile Choose Gateway node relies on the group.

MCP/AI should never send an empty `user_gateway` array unless the user explicitly wants to remove all gateways from the group.

---

# Safer Membership Management: Add/Remove Operations

If the user only wants to add or remove specific gateways, MCP should usually use:

```text
AddUserGatewayToGatewayGroup
RemoveUserGatewayFromGatewayGroup
```

instead of `EditGatewayGroup.user_gateway`.

---

## AddUserGatewayToGatewayGroup

Use when adding one or more gateways while preserving existing group membership.

Example:

```json
{
  "gateway_group_id": "GGGGGGGGGGGGGGGGGGGG",
  "user_gateway": [
    "DDDDDDDDDDDDDDDDDDDD"
  ]
}
```

Use cases:

```text
Add the new backup gateway to Brand A Gateways.
Add this newly approved MID to Subscription Renewal Gateways.
Include this new NMI gateway in the payment profile's gateway group.
```

---

## RemoveUserGatewayFromGatewayGroup

Use when removing one or more gateways while preserving the rest of the group.

Example:

```json
{
  "gateway_group_id": "GGGGGGGGGGGGGGGGGGGG",
  "user_gateway": [
    "BBBBBBBBBBBBBBBBBBBB"
  ]
}
```

Use cases:

```text
Remove this disabled gateway from Brand A Gateways.
Take this MID out of renewal routing.
Exclude this gateway from the payment profile's gateway group.
```

---

# Edit vs Add/Remove Decision

Use `EditGatewayGroup` for:

```text
Changing name
Changing description
Changing enabled status
Replacing the entire gateway membership array intentionally
```

Use `AddUserGatewayToGatewayGroup` for:

```text
Adding one or more gateways while preserving existing group members
```

Use `RemoveUserGatewayFromGatewayGroup` for:

```text
Removing one or more gateways while preserving existing group members
```

MCP/AI should not use `EditGatewayGroup.user_gateway` for casual add/remove changes unless it has first retrieved the current group and built the complete final intended list.

---

# Safe Edit Workflow

Before calling `EditGatewayGroup`, MCP should:

```text
1. Retrieve the current Gateway Group with GetGatewayGroup.
2. Review the current user_gateway membership.
3. Determine whether the user wants metadata changes or membership changes.
4. If membership changes are incremental, prefer Add/Remove operations.
5. If replacing the full user_gateway array, build the complete final intended list.
6. Confirm no active gateway is accidentally removed.
7. Consider whether a payment profile Choose Gateway node uses this group.
8. Warn the user if live payment routing may be affected.
9. Submit only intended fields.
10. Retrieve the group after edit to verify final state.
```

---

# Editing `name`

The name must remain unique.

Example:

```json
{
  "gateway_group_id": "GGGGGGGGGGGGGGGGGGGG",
  "name": "Brand A US Gateways"
}
```

Rename only when the new name is clearer.

If the group is referenced in internal documentation, payment profile descriptions, or operational notes, update those references as needed.

---

# Editing `description`

Use the description to document:

- Group purpose
- Brand/business/corp
- Which gateways should belong
- Which payment profiles use the group
- Whether it is for initial sales, renewals, trials, or backup routing
- Any SmartBIN or cascade-rule expectations

Example:

```json
{
  "gateway_group_id": "GGGGGGGGGGGGGGGGGGGG",
  "description": "Brand A US initial sale gateway group. Used by Brand A payment profile Choose Gateway nodes. Only include Brand A corporate MIDs."
}
```

---

# Editing `enabled`

`enabled` controls whether the Gateway Group is currently enabled.

Example:

```json
{
  "gateway_group_id": "GGGGGGGGGGGGGGGGGGGG",
  "enabled": false
}
```

Before disabling a Gateway Group, MCP should consider:

```text
Is this group used by any live payment profile Choose Gateway node?
Are there alternative gateway groups or fallback routing paths?
Will initial sales, renewals, trials, or recovery payments be affected?
Is the user intentionally pausing routing through this group?
```

A disabled group used by live payment routing may cause payment processing issues depending on the payment profile design.

---

# Editing `user_gateway` Full Replacement

Use this only when the user wants the group membership to become exactly the provided array.

Current group:

```text
Brand A Gateways = Gateway A + Gateway B + Gateway C
```

Desired group:

```text
Brand A Gateways = Gateway A + Gateway C + Gateway D
```

Correct full replacement request:

```json
{
  "gateway_group_id": "GGGGGGGGGGGGGGGGGGGG",
  "user_gateway": [
    "AAAAAAAAAAAAAAAAAAAA",
    "CCCCCCCCCCCCCCCCCCCC",
    "DDDDDDDDDDDDDDDDDDDD"
  ]
}
```

MCP must include all gateways that should remain.

Do not include only the newly added gateway.

---

# Example: Bad Add Attempt With EditGatewayGroup

User says:

```text
Add Gateway D to Brand A Gateways.
```

Current group:

```text
Gateway A + Gateway B + Gateway C
```

Bad request:

```json
{
  "gateway_group_id": "GGGGGGGGGGGGGGGGGGGG",
  "user_gateway": [
    "DDDDDDDDDDDDDDDDDDDD"
  ]
}
```

Bad result:

```text
Gateway A, B, and C are removed.
Only Gateway D remains.
```

Correct approach:

```text
Use AddUserGatewayToGatewayGroup
```

or retrieve the full group and submit:

```json
{
  "gateway_group_id": "GGGGGGGGGGGGGGGGGGGG",
  "user_gateway": [
    "AAAAAAAAAAAAAAAAAAAA",
    "BBBBBBBBBBBBBBBBBBBB",
    "CCCCCCCCCCCCCCCCCCCC",
    "DDDDDDDDDDDDDDDDDDDD"
  ]
}
```

---

# Example: Removing One Gateway

User says:

```text
Remove Gateway B from Brand A Gateways.
```

Preferred approach:

```text
Use RemoveUserGatewayFromGatewayGroup
```

Request:

```json
{
  "gateway_group_id": "GGGGGGGGGGGGGGGGGGGG",
  "user_gateway": [
    "BBBBBBBBBBBBBBBBBBBB"
  ]
}
```

Alternative full replacement:

```json
{
  "gateway_group_id": "GGGGGGGGGGGGGGGGGGGG",
  "user_gateway": [
    "AAAAAAAAAAAAAAAAAAAA",
    "CCCCCCCCCCCCCCCCCCCC"
  ]
}
```

Only use full replacement if MCP has retrieved the group and built the full intended final list.

---

# Example: Replacing All Gateways

User says:

```text
Replace the current group with these two new gateways only.
```

Use `EditGatewayGroup`:

```json
{
  "gateway_group_id": "GGGGGGGGGGGGGGGGGGGG",
  "user_gateway": [
    "XXXXXXXXXXXXXXXXXXXX",
    "YYYYYYYYYYYYYYYYYYYY"
  ]
}
```

This is the right use of `EditGatewayGroup.user_gateway` because the user explicitly wants full replacement.

---

# Payment Profile Impact

Gateway Group membership edits can affect live payment routing.

If a payment profile Choose Gateway node uses a group, changes to that group may immediately affect which gateways are available for payments.

Possible effects:

- A new gateway begins receiving traffic.
- An old gateway stops receiving traffic.
- A backup gateway becomes available.
- A disabled gateway remains in the group but is not useful.
- The group has no usable gateways.
- SmartBIN scoring changes because the available gateway set changes.
- Cascade-rule fallback behavior changes because eligible gateway options changed.

MCP should treat Gateway Group membership changes as payment-routing changes.

---

# Gateway Groups and SmartBIN

If a payment profile Choose Gateway node uses SmartBIN and chooses from a Gateway Group, the gateways in that group can affect which gateways are available for SmartBIN scoring.

This means:

```text
Changing the Gateway Group can change the SmartBIN candidate gateway set.
```

MCP should consider this when adding or removing gateways from a group used by SmartBIN-enabled payment profile nodes.

---

# Gateway Groups and Cascade Rules

Each User Gateway can have its own cascade rules.

A Gateway Group does not replace gateway-level cascade rules.

Instead:

```text
Gateway Group determines which gateways are available to the payment profile path.
Gateway cascade rules determine whether each gateway is eligible at the time of selection.
```

Example:

```text
Brand A Gateways contains Gateway A, Gateway B, Gateway C.
Gateway A is over its daily captured cap.
Gateway A is skipped.
Gateway B and C remain eligible if their cascade rules pass.
```

---

# Best Practices

## Use Gateway Groups as Stable Routing References

Let payment profiles reference stable Gateway Groups.

Then manage gateway availability by changing group membership.

This can reduce unnecessary payment profile edits.

---

## Prefer Add/Remove for Small Membership Changes

For adding or removing a few gateways, use:

```text
AddUserGatewayToGatewayGroup
RemoveUserGatewayFromGatewayGroup
```

This avoids accidentally replacing the whole array.

---

## Use Full Replacement Only Intentionally

Only use `EditGatewayGroup.user_gateway` when the desired final membership list is known and intentionally complete.

---

## Retrieve Before Editing

Always retrieve the current group before meaningful edits.

Use:

```text
GetGatewayGroup
```

Review:

```text
id
name
description
enabled
user_gateway
```

---

## Keep Groups Specific

Avoid overly broad groups unless intentional.

Better:

```text
Brand A Initial Sale Gateways
Brand A Renewal Gateways
Brand B Trial Expiration Gateways
US Backup Gateways
```

Worse:

```text
All Gateways
```

Specific groups prevent cross-brand or cross-corp routing mistakes.

---

# MCP Edit Workflow

Before editing a Gateway Group:

1. User explicitly asks for the edit.
2. MCP retrieves the current group.
3. MCP identifies whether the change is metadata, enabled status, add, remove, or full replacement.
4. For add/remove, MCP prefers Add/Remove operations.
5. For full replacement, MCP builds the complete final array.
6. MCP checks whether the group is used by payment profiles.
7. MCP warns if live payment routing may be affected.
8. MCP submits only intended fields.
9. MCP verifies final group state after edit.

---

# Validation Checklist

Before calling `EditGatewayGroup`:

1. `gateway_group_id` is present.
2. `gateway_group_id` is 20 characters.
3. Current group was retrieved.
4. User explicitly requested the edit.
5. Only intended fields are included.
6. If `user_gateway` is included, it is the complete intended final array.
7. User understands `user_gateway` replaces the full group gateway array.
8. Empty `user_gateway` array is intentional.
9. Each `user_gateway` value is a 20-character User Gateway ID.
10. IDs are User Gateway IDs, not Site Gateway IDs.
11. Payment profile impact was considered.
12. SmartBIN candidate set impact was considered if applicable.
13. Cascade-rule/fallback impact was considered.
14. Group enabled status is intentional.
15. 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
EditGatewayGroup can change metadata, enabled status, or full gateway membership.
```

```text
If user_gateway is provided, it replaces the full current gateway array.
```

```text
Use AddUserGatewayToGatewayGroup / RemoveUserGatewayFromGatewayGroup for safer incremental membership changes.
```

```text
Gateway Groups are valuable in payment profile Choose Gateway nodes because group membership can change without modifying the payment profile itself.
```

```text
Gateway Group edits can affect live payment routing and should be handled carefully.
```


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