# RevCent MCP Operation: `EditUserGateway`

This file explains how MCP/AI clients should use the `EditUserGateway` operation.

It starts from the current `EditUserGateway` schema and focuses on:

- Partial update behavior
- Explicit confirmation requirement
- Site Gateway and credential edit risks
- SmartBIN edit behavior
- Detailed cascade rules for limiting gateway usage based on gateway metrics over a time period

Sources:
- RevCent operation schema for `EditUserGateway`
- RevCent operation schema for `GetUserGateway`
- RevCent operation schema for `GetSiteGateway`
- RevCent operation schema for `CreateSecureForm`
- RevCent Gateway KB: https://kb.revcent.com/en/payments/credit-card/gateway
- RevCent SmartBIN KB: https://kb.revcent.com/en/payments/credit-card/smartbin

---

## Operation Summary

`EditUserGateway` edits a specific User Gateway.

The schema describes this as a very consequential operation that should only be performed upon explicit confirmation from the user.

Required:

```text
user_gateway_id
```

The operation is a partial update operation:

```text
Only include fields that should be modified.
```

---

# Required Field

| Field | Type | Required | Description |
|---|---:|---:|---|
| `user_gateway_id` | string | Yes | 20-character User Gateway ID. |

---

# Editable Fields

| Field | Type | Description |
|---|---:|---|
| `name` | string | User Gateway name. Must be unique. |
| `description` | string | User Gateway description. |
| `enabled` | boolean | Whether the User Gateway is currently enabled. |
| `site_gateway_id` | string | 20-character Site Gateway ID. Only provide if explicitly changing the Site Gateway association. |
| `secure_form_id` | string | 20-character Secure Form ID. Only provide if explicitly changing gateway credentials. |
| `custom_descriptor` | object | Descriptor details. |
| `merchant_account_id` | string | Merchant account ID / MID. |
| `discount_rate` | number | Discount rate specific to the MID. |
| `transaction_success_fee` | number | Flat fee for approved transactions. |
| `transaction_fail_fee` | number | Flat fee for failed/declined transactions. |
| `global_cascade_rules` | object | Gateway eligibility rules. |
| `smart_bin` | object | SmartBIN settings. If provided, the entire SmartBIN object overwrites existing SmartBIN settings. |

The schema has:

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

Do not send unknown fields.

---

# Explicit Confirmation Requirement

Editing a gateway can affect live payment processing. MCP/AI should not call `EditUserGateway` without explicit user confirmation, especially for:

- `enabled`
- `site_gateway_id`
- `secure_form_id`
- `global_cascade_rules`
- `smart_bin`
- `merchant_account_id`
- transaction fee fields
- custom descriptor fields shown to customers

---

# Safe Edit Workflow

```text
1. Retrieve the existing User Gateway with GetUserGateway.
2. Identify exactly which fields the user wants to change.
3. Determine whether the gateway is used in live payment profiles.
4. If changing site_gateway_id, confirm explicit user intent.
5. If changing credentials, create a Secure Form.
6. If changing cascade rules, preserve existing rules that should remain.
7. If changing smart_bin, retrieve and include the full SmartBIN object that should remain.
8. Submit only intended fields.
9. Verify configuration after edit.
```

---

# Partial Update Examples

## Rename Only

```json
{
 "user_gateway_id": "XXXXXXXXXXXXXXXXXXXX",
 "name": "Brand A - NMI Primary MID 845678"
}
```

## Disable Only

```json
{
 "user_gateway_id": "XXXXXXXXXXXXXXXXXXXX",
 "enabled": false
}
```

## Update Credentials Only

```json
{
 "user_gateway_id": "XXXXXXXXXXXXXXXXXXXX",
 "secure_form_id": "YYYYYYYYYYYYYYYYYYYY"
}
```

---

# High-Risk Fields

## `site_gateway_id`

Only provide `site_gateway_id` if the user explicitly wants to modify the Site Gateway associated with the User Gateway. Changing Site Gateway changes the underlying processor/integration type.

## `secure_form_id`

Only provide `secure_form_id` if the user explicitly wants to modify gateway credentials.

Use:

```json
{
 "form_source": "gateway",
 "form_source_id": "SITE_GATEWAY_ID"
}
```

from `CreateSecureForm`.

Do not ask the user to paste sensitive credentials into chat.

## `enabled`

Changing enabled status can affect real payment routing. Before disabling, consider payment profiles, fallback gateways, live checkout, renewals, trials, and recovery attempts.

---


# Global Cascade Rules

`global_cascade_rules` determine whether a User Gateway should be eligible when RevCent is choosing a gateway for a transaction. They are gateway eligibility controls, not cosmetic settings.

Cascade rules can limit gateway usage based on specific gateway metrics over a past time window, such as:

```text
Do not use this gateway after it captures more than $10,000 in the last 1 day.
Do not use this gateway after more than 50 declines in the last 1 hour.
Do not use this gateway when decline percentage is above 35% in the last 1 day.
Do not use this gateway when chargebacks exceed 10 in the last 1 month.
Do not use this gateway during a GMT denied time window.
```

If a cascade rule makes a gateway ineligible, RevCent should skip that gateway during gateway selection and use another eligible gateway if the payment profile has valid fallback/routing.

---

## Top-Level Shape

```json
{
 "global_cascade_rules": {
 "enabled": true,
 "revenue_rules": {
 "enabled": true,
 "options": []
 },
 "time_rules": {
 "enabled": true,
 "options": []
 }
 }
}
```

If `global_cascade_rules.enabled` is false, gateway-level cascade rules are not active.

---

## Revenue Rules

Revenue rules allow or disallow gateway use based on historical payment metrics.

Revenue rule shape:

```json
{
 "enabled": true,
 "bound": "max",
 "rule_value": 10000,
 "source": "gateway",
 "source_value": "captured",
 "calculation": "sum",
 "time_value": 1,
 "time_unit": "day"
}
```

| Field | Allowed values / type | Meaning |
|---|---|---|
| `enabled` | boolean | Whether the individual revenue rule is enabled. |
| `bound` | `min`, `max` | Whether the calculated value must stay above or below `rule_value`. |
| `rule_value` | number | Threshold compared against the calculated value. |
| `source` | `gateway`, `global`, `step` | Metric scope/source used for the calculation. |
| `source_value` | `captured`, `declined`, `chargeback`, `total`, `amount` | Metric being measured. |
| `calculation` | `count`, `percent`, `sum` | How the metric is calculated. |
| `time_value` | integer | How far back RevCent evaluates. |
| `time_unit` | `hour`, `day`, `week`, `month` | Unit for the past period. |

### `source = gateway`

When the user wants to limit this specific gateway based on its own metrics, use:

```json
"source": "gateway"
```

This is the most common gateway-level protection pattern.

Examples:

```text
This gateway's captured amount in the last 1 day.
This gateway's declined count in the last 1 hour.
This gateway's chargeback percentage in the last 1 month.
This gateway's total transaction count in the last 1 week.
```

Use `global` or `step` only if the user specifically wants account-level or payment-step-based behavior.

### `bound = max`

Use `bound = max` for upper-limit rules such as maximum captured amount, decline count, chargeback count, decline percentage, or transaction count. Use `bound = min` only for advanced cases where the gateway must meet a minimum metric threshold before use.

MCP/AI should not guess `min` vs `max`; most gateway limitation rules are `max`.

---

## Cascade Rule Examples

### Example 1: Captured Volume Cap, $10,000 Per Day

User intent:

```text
Do not use this gateway after it captures more than $10,000 in a day.
```

Rule:

```json
{
 "enabled": true,
 "bound": "max",
 "rule_value": 10000,
 "source": "gateway",
 "source_value": "captured",
 "calculation": "sum",
 "time_value": 1,
 "time_unit": "day"
}
```

Plain meaning:

```text
Look at this gateway's captured transaction amount over the last 1 day. If the sum exceeds 10000, skip this gateway.
```

### Example 2: Captured Volume Cap, $50,000 Per Week

```json
{
 "enabled": true,
 "bound": "max",
 "rule_value": 50000,
 "source": "gateway",
 "source_value": "captured",
 "calculation": "sum",
 "time_value": 1,
 "time_unit": "week"
}
```

Plain meaning:

```text
If this gateway captured more than $50,000 over the last 1 week, skip it.
```

### Example 3: Decline Count Cap, 50 Per Hour

```json
{
 "enabled": true,
 "bound": "max",
 "rule_value": 50,
 "source": "gateway",
 "source_value": "declined",
 "calculation": "count",
 "time_value": 1,
 "time_unit": "hour"
}
```

Plain meaning:

```text
If this gateway has more than 50 declined transactions in the last 1 hour, skip it.
```

### Example 4: Decline Percentage Cap, 35% Per Day

```json
{
 "enabled": true,
 "bound": "max",
 "rule_value": 35,
 "source": "gateway",
 "source_value": "declined",
 "calculation": "percent",
 "time_value": 1,
 "time_unit": "day"
}
```

Plain meaning:

```text
If this gateway's declined percentage is higher than 35% over the last 1 day, skip it.
```

### Example 5: Chargeback Count Cap, 10 Per Month

```json
{
 "enabled": true,
 "bound": "max",
 "rule_value": 10,
 "source": "gateway",
 "source_value": "chargeback",
 "calculation": "count",
 "time_value": 1,
 "time_unit": "month"
}
```

Plain meaning:

```text
If this gateway has more than 10 chargebacks in the last 1 month, skip it.
```

### Example 6: Chargeback Percentage Cap, 1% Per Month

```json
{
 "enabled": true,
 "bound": "max",
 "rule_value": 1,
 "source": "gateway",
 "source_value": "chargeback",
 "calculation": "percent",
 "time_value": 1,
 "time_unit": "month"
}
```

Plain meaning:

```text
If this gateway's chargeback percentage exceeds 1% over the last 1 month, skip it.
```

### Example 7: Total Attempt Cap, 500 Per Day

```json
{
 "enabled": true,
 "bound": "max",
 "rule_value": 500,
 "source": "gateway",
 "source_value": "total",
 "calculation": "count",
 "time_value": 1,
 "time_unit": "day"
}
```

Plain meaning:

```text
If this gateway has more than 500 total transaction attempts in the last 1 day, skip it.
```

### Example 8: Multiple Gateway Protection Rules

User intent:

```text
Use this gateway only while it is under $10,000 captured per day, under 50 declines per hour, and under 1% chargebacks per month.
```

Rule set:

```json
{
 "global_cascade_rules": {
 "enabled": true,
 "revenue_rules": {
 "enabled": true,
 "options": [
 {
 "enabled": true,
 "bound": "max",
 "rule_value": 10000,
 "source": "gateway",
 "source_value": "captured",
 "calculation": "sum",
 "time_value": 1,
 "time_unit": "day"
 },
 {
 "enabled": true,
 "bound": "max",
 "rule_value": 50,
 "source": "gateway",
 "source_value": "declined",
 "calculation": "count",
 "time_value": 1,
 "time_unit": "hour"
 },
 {
 "enabled": true,
 "bound": "max",
 "rule_value": 1,
 "source": "gateway",
 "source_value": "chargeback",
 "calculation": "percent",
 "time_value": 1,
 "time_unit": "month"
 }
 ]
 },
 "time_rules": {
 "enabled": false,
 "options": []
 }
 }
}
```

Plain meaning:

```text
The gateway is eligible only while all enabled rules pass. If any enabled rule makes it ineligible, RevCent should skip this gateway.
```

---

## Time Rules

Time rules allow or deny gateway usage based on current GMT / UTC+0 day and time.

```json
{
 "enabled": true,
 "name": "sunday",
 "start_time": "12:00am",
 "end_time": "11:59pm",
 "option": "deny"
}
```

| Field | Allowed values / type | Meaning |
|---|---|---|
| `enabled` | boolean | Whether the individual time rule is enabled. |
| `name` | `monday` through `sunday` | Weekday the rule applies to. |
| `start_time` | string | Start time formatted as `hh:mm:a`. |
| `end_time` | string | End time formatted as `hh:mm:a`. |
| `option` | `allow`, `deny` | Whether to allow or deny gateway use during that window. |

Important:

```text
All time rules are GMT / UTC+0.
```

MCP/AI must not assume the user's local timezone matches the rule timezone.

### Example 9: Deny Gateway on Sunday

```json
{
 "enabled": true,
 "name": "sunday",
 "start_time": "12:00am",
 "end_time": "11:59pm",
 "option": "deny"
}
```

### Example 10: Deny Gateway During Maintenance Window

```json
{
 "enabled": true,
 "name": "monday",
 "start_time": "2:00am",
 "end_time": "4:00am",
 "option": "deny"
}
```

---

## MCP Rules for Cascade Rules

MCP/AI should follow these rules:

1. Do not invent cascade thresholds.
2. Do not invent payment volume caps.
3. Do not invent decline caps.
4. Do not invent chargeback caps.
5. Ask the user for the exact business rule or clearly present a proposed rule for approval.
6. Prefer `source = gateway` when limiting this gateway based on its own metrics.
7. Use `bound = max` for upper-limit rules.
8. Use `calculation = sum` for money amount limits.
9. Use `calculation = count` for occurrence limits.
10. Use `calculation = percent` for rate/percentage limits.
11. Always explain the time window.
12. Always mention time rules use GMT / UTC+0.
13. Consider whether payment profiles have fallback gateways if a cascade rule makes the gateway ineligible.


---

# Editing Cascade Rules: Preserve Existing Rules

When editing `global_cascade_rules`, treat the submitted object as the intended cascade configuration.

Before changing cascade rules:

1. Retrieve the existing gateway.
2. Review existing cascade rules.
3. Preserve rules that should remain.
4. Add/remove only what the user intends.
5. Summarize the new combined rules in plain English.
6. Confirm if the change is high-impact.

Do not accidentally remove existing protective rules when adding a new rule.

## Example: Add Daily Captured Volume Cap

```json
{
 "user_gateway_id": "XXXXXXXXXXXXXXXXXXXX",
 "global_cascade_rules": {
 "enabled": true,
 "revenue_rules": {
 "enabled": true,
 "options": [
 {
 "enabled": true,
 "bound": "max",
 "rule_value": 15000,
 "source": "gateway",
 "source_value": "captured",
 "calculation": "sum",
 "time_value": 1,
 "time_unit": "day"
 }
 ]
 },
 "time_rules": {
 "enabled": false,
 "options": []
 }
 }
}
```

Plain-English summary:

```text
This gateway will be eligible only while its captured amount over the last 1 day is at or below $15,000.
```

## Example: Add Decline Spike Protection

```json
{
 "enabled": true,
 "bound": "max",
 "rule_value": 100,
 "source": "gateway",
 "source_value": "declined",
 "calculation": "count",
 "time_value": 2,
 "time_unit": "hour"
}
```

Plain-English summary:

```text
This gateway will be skipped if its declined transaction count exceeds 100 over the last 2 hours.
```

## Example: Disable Cascade Rules

Only do this with explicit user confirmation.

```json
{
 "user_gateway_id": "XXXXXXXXXXXXXXXXXXXX",
 "global_cascade_rules": {
 "enabled": false,
 "revenue_rules": {
 "enabled": false,
 "options": []
 },
 "time_rules": {
 "enabled": false,
 "options": []
 }
 }
}
```

---


# SmartBIN

---

## SmartBIN Enablement Requirements

SmartBIN requires two separate enablement steps:

```text
1. SmartBIN must be enabled for the RevCent account.
2. SmartBIN must be enabled inside a Choose Gateway node within a payment profile.
```

Gateway-level `smart_bin` settings prepare gateway metadata for SmartBIN scoring, but they do not, by themselves, cause SmartBIN routing to happen.

MCP/AI should not imply that adding or editing the `smart_bin` object is enough to activate SmartBIN routing. The account-level feature and the payment profile Choose Gateway node must both be enabled for SmartBIN use.

SmartBIN is an advanced RevCent feature that can route payments to the gateway with the highest statistical likelihood of approval for the specific customer card/payment request.

The SmartBIN KB explains that:

- SmartBIN is an extra monthly charge and RevCent must enable it for the account.
- SmartBIN is most useful when the user has more than one gateway.
- It helps when approval rates vary by issuer and gateway.
- RevCent scores available gateways for each payment request and chooses the gateway with the highest SmartBIN score.
- SmartBIN is only available when using a payment profile.
- SmartBIN is enabled inside a Choose Gateway node.
- SmartBIN will not help if only one gateway is available.
- Prefer-gateway conditions may prevent SmartBIN from being used because preferred gateways can take priority.
- Historical data, recent transactions, time windows, anomalies, and other conditions contribute to scoring.
- New gateways may be sampled so RevCent can learn performance without overloading the gateway.

SmartBIN is part of a routing strategy:

```text
Gateway SmartBIN metadata
 ↓
payment profile
 ↓
Choose Gateway node
 ↓
Use SmartBIN enabled
 ↓
RevCent scores available gateways
 ↓
Best-scoring eligible gateway is selected
```

---

## When SmartBIN Should Be Used

SmartBIN is appropriate when:

```text
The account has multiple gateways.
Approval rates vary by gateway and issuer/BIN.
The user wants RevCent to choose the gateway most likely to approve the request.
The user is using a payment profile.
SmartBIN is enabled for the RevCent account.
SmartBIN is enabled in a Choose Gateway node within the payment profile.
The gateways have been prepared with SmartBIN/acquirer information.
```

SmartBIN is not usually useful when:

```text
The account has only one gateway.
Approval rates are already high regardless of issuer and gateway.
SmartBIN is not enabled for the RevCent account.
The user is not using a payment profile.
The payment profile does not have a Choose Gateway node with SmartBIN enabled.
Prefer-gateway logic should intentionally override SmartBIN.
```

---

## Preparing SmartBIN

The SmartBIN KB says preparation is important and users should edit each gateway and set acquirer information for each card brand.

Preparation steps:

1. Edit each gateway.
2. Set acquirer information for each card brand.
3. Add MID/BIN/MCC/processor information when known.
4. Save changes.
5. Enable SmartBIN in the payment profile Choose Gateway node.

The KB says MID, BIN, MCC, and processor fields are recommended but not required, while acquirer information for each card brand should be set.

---

## `smart_bin` Object

The `smart_bin` object is available on `CreateUserGateway` and `EditUserGateway`.

Only provide it when the account is using or preparing for SmartBIN.

Schema guidance:

```text
When creating a gateway and using SmartBIN, complete as many fields as possible so the algorithm has the most information available.
```

Edit warning:

```text
When editing smart_bin via EditUserGateway, the entire smart_bin object must be present. If smart_bin is provided, it overwrites existing SmartBIN settings. Retrieve the existing User Gateway first and include all SmartBIN properties that should remain.
```

---

## Top-Level SmartBIN Properties

| Property | Type | Description |
|---|---:|---|
| `mcc` | string | Merchant Category Code for the specific gateway. |
| `processor` | enum string | Processor for the gateway. Must be one of the schema-defined enum values. |
| `visa` | object | Visa-specific SmartBIN settings. |
| `mastercard` | object | Mastercard-specific SmartBIN settings. |
| `discover` | object | Discover-specific SmartBIN settings. |
| `amex` | object | American Express-specific SmartBIN settings. |

Example shape:

```json
{
 "smart_bin": {
 "mcc": "5968",
 "processor": "nmi",
 "visa": {},
 "mastercard": {},
 "discover": {},
 "amex": {}
 }
}
```

---

## `processor`

`processor` must be a valid enum value from the schema.

Example schema values include:

```text
nmi
stripe_connect
checkout_com
braintree
elavon
world_pay
vantiv
paysafe_direct
```

MCP/AI must not freeform a processor name such as `NMI`, `Stripe`, or `Checkout.com` unless it maps to the exact enum value required by the schema.

Correct:

```json
"processor": "nmi"
```

Incorrect:

```json
"processor": "NMI"
```

---

## Card Brand Objects

Each card brand can include:

| Property | Type | Description |
|---|---:|---|
| `mid` | string | MID for that card brand on this gateway. |
| `bin` | string | BIN for that card brand on this gateway. |
| `acquirer` | enum string | Acquirer for that card brand. Must be one of the schema-defined enum values. |

Card brand objects:

```text
visa
mastercard
discover
amex
```

Example:

```json
{
 "smart_bin": {
 "mcc": "5968",
 "processor": "nmi",
 "visa": {
 "mid": "VISA_MID_123",
 "bin": "123456",
 "acquirer": "elavon"
 },
 "mastercard": {
 "mid": "MC_MID_123",
 "bin": "654321",
 "acquirer": "elavon"
 },
 "discover": {
 "mid": "DISC_MID_123",
 "bin": "601100",
 "acquirer": "elavon"
 },
 "amex": {
 "mid": "AMEX_MID_123",
 "bin": "10000000002",
 "acquirer": "elavon"
 }
 }
}
```

---

## `acquirer`

Each card brand's `acquirer` must be a valid enum value from the schema.

Example acquirer enum values include:

```text
elavon
fiserv
global_payments
jp_morgan_chase
maverick
paysafe
stripe_payfac
tsys
vantiv
worldpay
other
```

The exact value should come from the schema and/or merchant account provider.

MCP/AI should not invent acquirer values. The user may need to contact their merchant account provider.

---

## American Express BIN

The `amex.bin` property is enum-constrained in the schema.

Allowed values shown by the schema include:

```text
10000000002
10000000006
10000000232
10000000319
10000000005
```

MCP/AI should not use a random Amex BIN value.

---

## SmartBIN and payment profiles

SmartBIN data on gateways is only part of setup.

To actually use SmartBIN for payment routing:

```text
1. SmartBIN must be enabled for the RevCent account.
2. The user must use a payment profile.
3. The payment profile must contain a Choose Gateway node.
4. SmartBIN must be enabled in that Choose Gateway node.
5. Multiple eligible gateways should be available.
6. Gateway SmartBIN/acquirer information should be prepared.
```

If SmartBIN is not enabled inside the Choose Gateway node, the SmartBIN metadata on a gateway may exist but SmartBIN routing will not be used for that gateway choice.

---

## MCP Rules for SmartBIN

1. Do not configure SmartBIN unless the user is using or preparing to use SmartBIN.
2. Do not assume SmartBIN is enabled for the account.
3. Tell the user RevCent must enable SmartBIN first if not already enabled.
4. Complete as many SmartBIN fields as possible when creating a gateway for SmartBIN use.
5. For edits, retrieve the existing gateway first because `smart_bin` overwrites if provided.
6. Do not invent MCC, processor, MID, BIN, or acquirer values.
7. Use exact enum values for `processor` and `acquirer`.
8. Set acquirer information for each card brand when available.
9. Remember that MID/BIN/MCC/processor are recommended but not required by the KB.
10. Remember that SmartBIN must be enabled in a payment profile Choose Gateway node to route payments.


---

# SmartBIN Edit Warning: Full Object Required

The schema warns:

```text
If editing a gateway's smart_bin object via EditUserGateway, the entire smart_bin object must be present.
The smart_bin object in the request will overwrite existing if provided.
All properties should be retrieved first before editing.
```

MCP/AI must therefore:

```text
1. Retrieve the existing User Gateway.
2. Read existing smart_bin.
3. Modify only the intended SmartBIN field(s) locally.
4. Submit the complete intended smart_bin object.
```

Do not submit a partial `smart_bin` object unless the user intentionally wants omitted values removed.

---

# Output Schema

```json
{
 "api_call_id": "XXXXXXXXXXXXXXXXXXXX",
 "api_call_unix": 1740000000,
 "code": 1,
 "user_gateway_id": "YYYYYYYYYYYYYYYYYYYY",
 "result": "..."
}
```

---

# MCP Edit Checklist

1. User explicitly requested the edit.
2. `user_gateway_id` is known and 20 characters.
3. Current gateway was retrieved with `GetUserGateway`.
4. Only intended top-level fields are included.
5. If changing `site_gateway_id`, user explicitly consented.
6. If changing credentials, Secure Form was used.
7. If changing cascade rules, existing rules were reviewed.
8. Cascade rule thresholds were supplied or approved by the user.
9. Time rules use GMT / UTC+0.
10. If changing SmartBIN, existing `smart_bin` was retrieved first.
11. If changing SmartBIN, the full intended `smart_bin` object is submitted.
12. SmartBIN processor/acquirer enum values are exact schema values.
13. MCC/MID/BIN/acquirer values are not invented.
14. `enabled` changes were reviewed for payment impact.
15. Payment profile fallback/failsafe impact was considered, including whether any Choose Gateway node has SmartBIN enabled.
16. User understands this can affect live processing.


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