# RevCent MCP Operation: `CreatePaymentProfile`

This document explains the `CreatePaymentProfile` MCP operation and how an MCP should reason about creating a Payment Profile.

A Payment Profile is a payment-routing flow whose ultimate purpose is to process a credit card payment. Because the flow directly controls how credit card payments are selected, routed, attempted, retried, declined, aborted, or approved, incorrect flow logic can cause serious payment-processing problems.

Sources:
- RevCent Payment Profile Overview — `https://revcent.com/documentation/markdown/mcp/operation/OverviewPaymentProfile.md`
- RevCent API/MCP schema for `CreatePaymentProfile`
- RevCent Knowledge Base: Payment Profile — `https://kb.revcent.com/en/payments/credit-card/next-gen-payment-profile`

---

---

# Read the Payment Profile Overview First

Before creating, editing, reviewing, or deeply configuring Payment Profiles, AI/MCP should read the Payment Profile overview:

```text
https://revcent.com/documentation/markdown/mcp/operation/OverviewPaymentProfile.md
```

The overview explains Payment Profiles as a whole, including:

```text
What Payment Profiles are.
Why Payment Profiles are critical credit-card payment infrastructure.
How payment routing works in RevCent.
How gateway groups, gateways, failsafe gateways, retries, filters, Functions, metadata, abort paths, and process-payment nodes fit together.
How Payment Profiles affect initial sales, pending sale recovery, subscription renewals, and trial expirations.
Why incorrect Payment Profile logic can break checkout, route payments incorrectly, or prevent credit-card payments from being processed.
```

This operation file is focused on the specific API/MCP operation. The overview provides the broader conceptual context AI/MCP should understand before making Payment Profile design or edit decisions.

## Operation Summary

`CreatePaymentProfile` creates a new Payment Profile and returns a unique 20-character Payment Profile ID.

A Payment Profile contains a `payment_flow`, which is an array of connected nodes. When a payment request uses the profile, RevCent starts at the beginning of the flow and follows node outputs to determine what happens next.

At a minimum, a usable payment-processing flow must:

1. Start the payment request.
2. Choose a gateway.
3. Process the payment.

Conceptual minimum:

```text
Payment Request → Choose Gateway → Process Payment
```

If the flow does not eventually choose a gateway and process payment, the payment may never be attempted.

---

# Critical MCP Concept: What Is Being Created?

A Payment Profile is not just a saved configuration object.

It is an execution path for payment processing.

When a customer attempts to pay with a credit card, the Payment Profile determines:

- Whether the request should be processed.
- Which gateway or gateway group should be used.
- Whether the request should be routed differently by campaign, card type, amount, currency, metadata, customer group, product group, attempt count, or gateway response.
- Whether payment should be retried after a decline.
- Whether a different gateway should be used after a decline.
- Whether metadata should be inserted.
- Whether a custom Function should be called.
- Whether the flow should abort.
- Whether a custom error should be returned.

This means the MCP must treat the `payment_flow` as critical payment infrastructure.

A bad flow can:

- Prevent payments from being attempted.
- Route payments to the wrong gateway.
- Overuse a gateway.
- Retry too many times.
- Retry after a hard decline when it should stop.
- Abort valid payments.
- Fail to provide usable customer-facing errors.
- Create latency.
- Break checkout.
- Prevent subscription renewals or trial expirations from billing correctly.
- Cause recoverable declines to remain unrecovered.
- Cause unintended void/cancel behavior when kill terms or max attempts are involved.

---

# Simple vs Advanced Payment Profiles

Payment Profiles can be simple or advanced.

MCP should not create an advanced flow unless the user has clearly described the business rules that require it.

---

## Simple Payment Profile

A simple Payment Profile is appropriate when the business only needs to process payments through one gateway or a straightforward gateway set.

Use a simple flow when:

- There is only one gateway.
- There is one normal gateway group.
- No special routing is needed.
- No retry logic is needed.
- No card type, currency, campaign, product, metadata, or amount rules are needed.
- No custom Function is needed.
- The user wants the safest and easiest-to-understand profile.

Simple flow:

```text
start_payment_request
  ↓
action_choose_gateway
  ↓
action_process_payment
```

Recommended when the user says things like:

```text
Just use this gateway for payments.
```

```text
Use these gateways evenly.
```

```text
I do not need any special routing.
```

```text
I just need the profile to process credit card payments.
```

---

## Advanced Payment Profile

An advanced Payment Profile is appropriate when payment routing must change based on conditions.

Use an advanced flow when the business needs:

- Different gateways for different currencies.
- Different gateways for different campaigns.
- Different routing by card type.
- Different routing by BIN profile.
- Different routing by payment amount.
- Different routing for initial sales vs renewals vs trial expirations.
- Different retry behavior after declines.
- Gateway response parsing.
- Metadata-based routing.
- Customer group rules.
- Product group rules.
- Custom Function-based decisions.
- Smart gateway selection.
- Decline recovery routing.
- Custom error messaging.

Advanced flow example:

```text
start_payment_request
  ↓
filter_request_type
  ↓
filter_currency / filter_campaign / filter_attempt_count
  ↓
action_choose_gateway
  ↓
action_process_payment
  ↓
on decline: filter_gateway_response
  ↓
retry, abort, or choose a different gateway
```

Important:

Advanced flows should be created only when the user provides exact routing requirements.

Do not invent payment routing rules.

---

# Required / Core Input Fields

The `CreatePaymentProfile` operation supports the following primary fields.

| Field | Type | Description |
|---|---:|---|
| `name` | string | Unique Payment Profile name. |
| `description` | string | Human-readable explanation of what the profile is for. |
| `enabled` | boolean | Whether the Payment Profile is enabled. |
| `payment_flow` | array<object> | Flow nodes that determine how payment requests are routed and processed. |

---

## `name`

The name must be unique from other Payment Profile names.

Recommended naming patterns:

```text
Primary Credit Card Profile
Initial Sale - Standard Routing
Subscription Renewal - Gateway Group Routing
US Sales - USD Gateway Routing
High Risk Campaign - Manual Rules
Decline Recovery - Multi Gateway Retry
```

Avoid vague names:

```text
Profile 1
Test
New Profile
Payment
```

---

## `description`

A description is highly recommended.

It should explain:

- What the Payment Profile is used for.
- Which request types it supports.
- Which gateways or gateway groups it routes to.
- Whether it is simple or advanced.
- Whether it has retry/decline logic.
- Whether it uses Functions.
- Whether it has special abort/custom-error behavior.
- Whether it is intended for initial sales, pending sale recovery, renewals, trial expirations, or multiple request types.
- Initial version, usually `v1.0.0`, so future edits and backups can follow consistent versioning.

Example:

```text
Version: v1.0.0
Created: 2026-05-27
Purpose: Processes standard initial credit card sales.
Routing: Starts at payment request, chooses from the Primary Gateways group using evenly distributed selection, and processes payment once.
Flow Type: Simple
Change Summary: Initial Payment Profile creation. Declines end the flow without retry logic.
```

Advanced example:

```text
Version: v1.0.0
Created: 2026-05-27
Purpose: Routes initial sale requests by currency and campaign.
Routing: USD Facebook campaign traffic routes to Gateway Group A, EUR traffic routes to Gateway Group B, and all other traffic routes to Gateway Group C.
Flow Type: Advanced
Change Summary: Initial Payment Profile creation with currency/campaign routing. Declines containing explicitly user-provided hard-decline terms abort the flow. Other declines retry once through a fallback gateway.
```

---

## Description Versioning

A Payment Profile description should include a version from the beginning so future edits can use consistent versioning.

This is important because Payment Profiles often change over time as gateway groups, failsafe gateways, retry logic, filters, Functions, kill terms, metadata insertion, or business/corp routing rules evolve.

Adding a version at creation helps future `EditPaymentProfile` workflows understand:

- Which version of the flow was originally created.
- Which version is currently active.
- Which backup file corresponds to which profile state.
- What changed between edits.
- Whether a rollback restored a previous flow.
- Which version introduced a routing, retry, or decline-handling issue.

MCP should treat description versioning as part of the initial Payment Profile design, not something that starts only after the first edit.

---

### Recommended Description Format

When creating a Payment Profile, MCP should include version information in the `description`.

Recommended format:

```text
Version: v1.0.0
Created: 2026-05-27
Purpose: Processes standard initial credit card sales for Business A.
Routing: Uses Business A Primary Gateway Group with Gateway A as failsafe.
Flow Type: Simple
Change Summary: Initial Payment Profile creation. No retry logic, kill terms, or Function nodes.
```

For advanced profiles:

```text
Version: v1.0.0
Created: 2026-05-27
Purpose: Routes initial sales and subscription renewals for Business A.
Routing: USD traffic uses Business A USD Gateway Group with Gateway A as failsafe. EUR traffic uses Business A EUR Gateway Group with Gateway B as failsafe.
Flow Type: Advanced
Change Summary: Initial Payment Profile creation with request-type and currency routing. No kill terms added.
```

---

### Suggested Versioning Pattern

Use semantic-style versioning:

```text
vMAJOR.MINOR.PATCH
```

Recommended initial version:

```text
v1.0.0
```

Recommended interpretation for future edits:

| Version Change | Use When |
|---|---|
| Patch, such as `v1.0.1` | Description-only changes, internal notes, or non-routing edits. |
| Minor, such as `v1.1.0` | Adds or changes a limited flow branch, gateway group, failsafe gateway, retry rule, metadata insertion, or filter. |
| Major, such as `v2.0.0` | Major flow rewrite, request-type routing change, Function-based routing, kill-term change, or significant gateway/corp routing change. |

---

### MCP Guidance

When creating a Payment Profile, MCP should:

0. Confirm the Payment Profile overview has been reviewed when making broader design decisions.

1. Include an initial version in the description.
2. Use `v1.0.0` unless the user has a different versioning standard.
3. Include a concise purpose statement.
4. Include the intended routing summary.
5. Include whether the profile is simple or advanced.
6. Include whether retry logic, kill terms, or Function nodes are present.
7. Keep the description consistent with the visual flow and JSON `payment_flow`.
8. Explain that future backups and edits should use the same versioning pattern.

---

### Relationship to Future Backups

Versioning at creation makes future backup files easier to name and match to profile history.

Future `EditPaymentProfile` backups should use the version from the description.

Recommended future backup filename format:

```text
payment_profile_backup_<payment_profile_id>_<version>_<YYYY-MM-DD_HH-mm-ss>.json
```

Example:

```text
payment_profile_backup_XXXXXXXXXXXXXXXXXXXX_v1.0.0_2026-05-27_14-30-00.json
```

If a Payment Profile is created without a version in the description, future edit workflows may need to treat the first backup as `unversioned`, which is less clear.


---

## `enabled`

Use `false` while drafting or testing.

Recommended:

```json
"enabled": false
```

Do not enable a Payment Profile until:

- The flow has been reviewed.
- Node IDs are unique.
- Connections are valid.
- Every path is intentional.
- A gateway is chosen before processing payment.
- Retry paths are limited.
- Abort paths are intentional.
- Any Function node has safe timeout/error routing.
- The user understands what the profile will do.

---

# `payment_flow`

`payment_flow` is the most important part of the operation.

It is an array of nodes.

Each node has:

| Property | Purpose |
|---|---|
| `id` | Unique node identifier within the flow. |
| `type` | Node type. Determines node behavior. |
| `inputs` | Previous node outputs that connect into this node. |
| `outputs` | Next node inputs that this node routes to. |
| `position` | Optional visual layout position in the UI. |
| `node_settings` | Settings specific to the node type. |

---

## Minimum Required Processing Nodes

A payment-processing flow should include at least these three node types:

| Node Type | Purpose |
|---|---|
| `start_payment_request` | Begins the flow when the profile is triggered. |
| `action_choose_gateway` | Selects a gateway or gateway group. |
| `action_process_payment` | Sends the payment request to the chosen gateway. |

If `action_process_payment` runs before a gateway is chosen, payment cannot be properly processed.

If the flow never reaches `action_process_payment`, no credit card payment attempt occurs.

---

## Only One Start Node

Only one `start_payment_request` node can be present.

It is the beginning of the flow.

Rules:

- It has no inputs.
- It should be the first conceptual node.
- It starts the payment request.
- It should connect to the next node through `output_1`.

---

# Node Types

The schema supports these node types:

```text
start_payment_request
filter_attempt_count
filter_bin_profile
filter_campaign
filter_card_type
filter_currency
filter_customer_group
filter_gateway_response
filter_metadata
filter_payment_amount
filter_process_payment_count
filter_product_group
filter_request_type
filter_merge_filters
action_abort_flow
action_choose_gateway
action_insert_metadata
action_process_payment
action_custom_function
```

They can be grouped as:

| Group | Node Types |
|---|---|
| Start | `start_payment_request` |
| Filters | `filter_attempt_count`, `filter_bin_profile`, `filter_campaign`, `filter_card_type`, `filter_currency`, `filter_customer_group`, `filter_gateway_response`, `filter_metadata`, `filter_payment_amount`, `filter_process_payment_count`, `filter_product_group`, `filter_request_type`, `filter_merge_filters` |
| Actions | `action_abort_flow`, `action_choose_gateway`, `action_insert_metadata`, `action_process_payment`, `action_custom_function` |

---

# Start Node

## `start_payment_request`

This node begins the payment flow.

Every Payment Profile must begin with a Payment Request start node, and only one start node is allowed.

Typical use:

```text
start_payment_request → action_choose_gateway
```

Example shape:

```json
{
  "id": "start",
  "type": "start_payment_request",
  "inputs": {},
  "outputs": {
    "output_1": {
      "connections": [
        {
          "node": "choose_gateway",
          "output": "input_1"
        }
      ]
    }
  },
  "node_settings": {
    "node_note": "Start the payment request."
  }
}
```

---

# Action Nodes

## `action_choose_gateway`

## Prefer Gateway Groups Over Individual Gateways

For `action_choose_gateway`, gateway groups should generally be preferred over individual gateways as the selection source.

Best practice:

```text
Use selection_source = gateway_group whenever possible.
```

The reason is organizational and operational safety.

A single RevCent account may contain gateways for multiple businesses, brands, stores, corporations, merchant accounts, or processing strategies. Gateway groups allow those gateways to be organized so the correct business or corporation uses the correct gateways and avoids using gateways that belong to another business/corp inside the same RevCent account.

Gateway groups help prevent situations such as:

- Business A accidentally routing payments through Business B’s gateway.
- A campaign using a merchant account intended for a different brand.
- Subscription renewals using gateways meant only for initial sales.
- International traffic using gateways meant only for domestic traffic.
- High-risk traffic using gateways meant for low-risk traffic.
- A fallback route selecting a gateway that should not apply to that business/corp.

Gateway groups make payment routing easier to reason about because the Payment Profile can select from a pre-organized set of eligible gateways instead of directly referencing many individual gateways.

---

### Why Gateway Groups Are the Best Practice

Gateway groups provide a clean business/corp routing layer.

Use gateway groups to organize gateways by:

| Organization Method | Example |
|---|---|
| Business / corporation | `Business A Gateways`, `Business B Gateways` |
| Brand / store | `Brand One Gateways`, `Brand Two Gateways` |
| Geography | `US Gateways`, `EU Gateways`, `Canada Gateways` |
| Currency | `USD Gateways`, `EUR Gateways`, `GBP Gateways` |
| Request type | `Initial Sale Gateways`, `Renewal Gateways`, `Trial Expiration Gateways` |
| Risk level | `Low Risk Gateways`, `High Risk Gateways` |
| Campaign type | `Affiliate Campaign Gateways`, `Paid Search Gateways` |
| Fallback routing | `Primary Gateways`, `Fallback Gateways` |

This makes the Payment Profile more maintainable.

Instead of hard-coding many gateway IDs directly in the flow, the flow can choose from a gateway group that already represents the correct routing boundary.

---

### MCP Guidance

When creating a Payment Profile, MCP should first ask which gateway group should be used for each business/corp, route, or fallback path.

MCP should prefer:

```json
"selection_source": "gateway_group"
```

over:

```json
"selection_source": "gateway"
```

unless the user explicitly wants to route to specific individual gateways.

MCP should ask:

```text
Which gateway group should this business/corp use for this payment path?
```

rather than immediately asking:

```text
Which individual gateway should this payment path use?
```

---

### When Individual Gateways Are Appropriate

Individual gateway selection can still be appropriate when:

- The user intentionally wants one exact gateway.
- The account has only one gateway.
- A temporary test profile is being created.
- A specific failsafe gateway must be set.
- A Function or gateway-response path intentionally selects one known gateway.
- The user explicitly states that the route should use a specific gateway ID.

Even when individual gateways are used, MCP should still confirm that the selected gateway belongs to the correct business/corp and is appropriate for the request type.

---

### Failsafe Gateway Still Matters

Even when gateway groups are used as the selection source, a failsafe gateway should almost always be configured.

The failsafe gateway should belong to the same business/corp routing context as the gateway group.

For example:

```text
Gateway Group: Business A Primary Gateways
Failsafe Gateway: Business A Backup Gateway
```

Avoid:

```text
Gateway Group: Business A Primary Gateways
Failsafe Gateway: Business B Gateway
```

unless the user explicitly confirms that cross-business/corp fallback routing is intentional.


## Failsafe Gateway Guidance

An `action_choose_gateway` node should almost always have a failsafe gateway configured.

A failsafe gateway is important because gateway selection can fail or return no eligible gateway. This can happen when:

- All selected gateways are disabled.
- Gateway revenue/time rules exclude all selected gateways.
- Gateway group selection produces no eligible enabled gateway.
- Preference or exclusion rules eliminate the available gateways.
- Last-approved or last-declined gateway selection has no matching prior gateway.
- Gateway conditions change after the Payment Profile is created.

Without a failsafe gateway, if `action_choose_gateway` cannot select a gateway, the flow immediately terminates and returns an error instead of attempting the payment through a safe fallback.

MCP should treat a missing failsafe gateway as a major design risk.

Recommended rule:

```text
Every action_choose_gateway node should include a failsafe gateway unless the user has explicitly confirmed that no fallback gateway should be used.
```

The failsafe gateway should be:

- A valid enabled gateway.
- Appropriate for the request type, currency, and business use case.
- Able to process the relevant card/payment type.
- Safe to use if the normal gateway selection rules produce no gateway.
- Reviewed with the user before creation.

MCP should ask the user which gateway should be used as the failsafe if it is not already specified.


This node chooses which gateway will be used to process the payment.

A gateway must be chosen before `action_process_payment`.

Selection sources include:

| Selection Source | Meaning | MCP Guidance |
|---|---|---|
| `gateway_group` | Choose from enabled gateways inside selected gateway groups. | Preferred selection source. Best practice for organizing gateways across multiple businesses/corps, brands, currencies, request types, and fallback paths. |
| `gateway` | Choose from a specified array of gateway IDs. | Use only when the user intentionally wants specific individual gateways or when a single exact gateway route is required. |
| `gateway_last_approved` | Use the customer/entity’s last approved gateway if available, otherwise defer to failsafe behavior. | Advanced use. Confirm the fallback/failsafe gateway remains correct for the business/corp. |
| `gateway_last_declined` | Use the customer/entity’s last declined gateway if available, otherwise defer to failsafe behavior. | Advanced use. Confirm the fallback/failsafe gateway remains correct for the business/corp. |

Selection methods include:

| Selection Method | Meaning |
|---|---|
| `evenly_distribute` | Select based on lowest captured payment volume over the past 24 hours. Recommended when distributing volume. |
| `random` | Randomly choose a gateway. |
| `round_robin` | Rotate through selected gateways in order. Applies to gateway source. |
| `sort_order` | Try selected gateways in configured order. Applies to gateway source. |

Important:

- `evenly_distribute` is generally safest when spreading volume across multiple gateways or gateway groups.
- If no gateway can be selected, the flow immediately terminates and returns an error.
- Failsafe gateways can be used when no qualifying gateway is otherwise available.
- Gateway choice can consider preferences and exclusions, such as previously approved or declined gateways.

Example:

```json
{
  "id": "choose_gateway",
  "type": "action_choose_gateway",
  "inputs": {
    "input_1": {
      "connections": [
        {
          "node": "start",
          "input": "output_1"
        }
      ]
    }
  },
  "outputs": {
    "output_1": {
      "connections": [
        {
          "node": "process_payment",
          "output": "input_1"
        }
      ]
    }
  },
  "node_settings": {
    "selection_source": "gateway",
    "selection_method": "evenly_distribute",
    "gateways": [
      {
        "order": 0,
        "id": "XXXXXXXXXXXXXXXXXXXX"
      }
    ],
    "node_note": "Choose from the primary gateway group. Prefer gateway groups for proper business/corp routing."
  }
}
```

---

## `action_process_payment`

This node sends the payment request to the chosen gateway.

If a gateway has been chosen in a prior node, this node officially processes the payment.

Outputs:

| Output | Meaning |
|---|---|
| `output_1` | Payment successful. Usually the flow ends and the success response is returned. |
| `output_2` | Payment declined or gateway error. Can connect to retry, decline routing, Function, or abort logic. |

Important:

- If payment succeeds, the flow automatically ends and returns success.
- If payment fails and no `output_2` is connected, the flow ends and returns the decline.
- If payment fails and `output_2` is connected, the flow can continue to filters, Functions, another gateway choice, or abort flow.

Example:

```json
{
  "id": "process_payment",
  "type": "action_process_payment",
  "inputs": {
    "input_1": {
      "connections": [
        {
          "node": "choose_gateway",
          "input": "output_1"
        }
      ]
    }
  },
  "outputs": {
    "output_1": {
      "connections": []
    },
    "output_2": {
      "connections": []
    }
  },
  "node_settings": {
    "node_note": "Process the payment using the chosen gateway."
  }
}
```

---

## `action_abort_flow`

This node stops the flow and returns an error/decline result.

Use when:

- A hard decline should stop further attempts.
- A request should not be processed.
- A campaign, card type, amount, metadata, or customer group should be blocked.
- A Function returns a custom error.
- The flow should intentionally stop without additional gateway attempts.

Important:

- Once reached, the flow terminates immediately.
- If a payment was already attempted, decline results are returned.
- If no payment was attempted, an error is returned.
- Kill terms and max attempts can still apply when enabled.

---

## `action_insert_metadata`

This node inserts metadata.

It is special because it has no outputs and is run “on the side.” It does not control the main flow path.

Use it to tag:

- Sale
- Customer
- Subscription
- Subscription renewal
- Trial

Examples:

- Save the gateway ID chosen.
- Save the gateway name chosen.
- Save that a decline recovery route was used.
- Save the reason a flow branch was used.
- Save a routing decision.

Supported shortcodes include:

```text
#gateway_id#
#gateway_name#
```

Important:

Because `action_insert_metadata` has no output, the previous node must also route the main flow to another node if payment processing should continue.

Do not connect only to `action_insert_metadata` and forget to continue the payment path.

---

## `action_custom_function`

This node runs a RevCent Function during the payment flow.

Use it only for advanced payment logic.

This is a highly advanced feature and should be used only when there is an experienced developer and a strong understanding of payment flow processing.

Run methods:

| Run Method | Behavior |
|---|---|
| Queue And Continue | Function runs separately. The payment flow does not wait. The `output_1` is followed. |
| Wait For Response | RevCent waits for the Function response and uses it to determine flow behavior. |

Warnings for `Wait For Response`:

- Always route the `output_2` as a backup in case the Function fails or times out.
- Function has a maximum 8-second response time within the flow.
- Bad Function code can result in payments never being processed.
- Functions add latency to the payment response.

Use cases:

- Parse complex gateway decline responses.
- Call an external risk system.
- Choose a gateway dynamically.
- Return a custom error.
- Override gateway/gateway group selection.
- Decide next node based on external logic.

---

# Filter Nodes

Filter nodes route the flow based on a condition.

Most filters have:

| Output | Meaning |
|---|---|
| `output_1` | `output_1`: filter passed. |
| `output_2` | `output_2`: filter failed. |

Filters are checked before action nodes when multiple node types are available at the same point in the flow.

---

## `filter_attempt_count`

Filters based on the number of attempts for the entity being processed.

Applies to:

- Initial sale
- Subscription renewal

Important distinction:

- Attempt count means the number of completed Payment Profile flows for the same entity, not the number of individual process payment nodes inside one flow.
- Subscription renewal attempt count includes the current renewal.

Use cases:

- Route first attempt to one gateway.
- Route later attempts to other gateways.
- Stop after a certain number of attempts.

---

## `filter_process_payment_count`

Filters based on how many `action_process_payment` nodes have executed in the current flow request.

Use this to prevent too many gateway attempts inside one request.

Example:

```text
If process payment count <= 2, retry through a second gateway.
If process payment count > 2, abort.
```

Important:

This is different from `filter_attempt_count`.

| Filter | Counts |
|---|---|
| `filter_attempt_count` | Completed profile attempts across the entity/request history. |
| `filter_process_payment_count` | Process payment nodes executed in the current flow request. |

---

## `filter_request_type`

Filters by payment request type.

Supported request types:

```text
Initial Sale
Pending Sale Profile Recovery
Subscription Renew
Trial Expire
```

Use cases:

- Use one route for initial sales.
- Use another route for renewals.
- Route trial expirations differently.
- Avoid applying sale-only logic to renewals.

---

## `filter_gateway_response`

Filters based on the most recent gateway response in the current payment request.

Use cases:

- Abort on hard-decline terms.
- Retry on soft-decline terms.
- Route “3DS required” to a specific gateway.
- Send insufficient-funds declines to a later retry path.
- Return custom error messaging.

Important:

- The profile’s kill terms and max attempts may still apply.
- Gateway response filters are commonly used after an `action_process_payment` `output_2`.

---

## `filter_metadata`

Filters based on metadata from selected sources.

Metadata sources include:

| Source | Meaning |
|---|---|
| Customer | Metadata on the related customer. |
| Current Chosen Gateway | Metadata on the current gateway chosen, if any. |
| Payment Request | Metadata in the current initial sale API call. |
| Sale | Metadata on the related sale. |
| Subscription | Applies to subscription renew request type. |
| Trial | Applies to trial expire request type. |

Use cases:

- Route upsells differently.
- Route affiliate traffic differently.
- Route high-risk metadata differently.
- Route traffic by custom campaign/sub ID.
- Skip processing for blocked metadata.

---

## Other Filter Nodes

| Node Type | Use |
|---|---|
| `filter_bin_profile` | Route by first 6 digits / BIN profile. |
| `filter_campaign` | Route by campaign association. |
| `filter_card_type` | Route by card brand/type. |
| `filter_currency` | Route by currency. |
| `filter_customer_group` | Route by customer group. Use carefully because customer groups may not apply instantly. |
| `filter_payment_amount` | Route by amount threshold. |
| `filter_product_group` | Route by product group. |

---

## `filter_merge_filters`

Combines multiple filters into one AND condition.

Behavior:

- Connect filter nodes to the merge filter using `output_3`.
- All connected filters must pass for the merge filter to pass.
- If all pass, `output_1` is followed.
- If any fail, `output_2` is followed.

Use when multiple conditions must all be true.

Example:

```text
Currency is USD
AND card BIN is in BIN Profile 42
AND campaign is Facebook
```

---

# Filter Priority

When multiple filters exist at the same point, filter priority determines the order they are checked.

Important rule:

```text
Lower priority value = checked earlier.
```

Example:

| Filter | Priority | Meaning |
|---|---:|---|
| Attempt count <= 1 | 0 | Checked first. |
| Attempt count >= 3 | 1 | Checked second. |
| Attempt count >= 2 | 2 | Checked last. |

If filters have the same priority, they may be checked in random order.

MCP should set filter priority intentionally.

Bad priority can route payments to the wrong gateway.

---

# Flow Execution Rules

When RevCent needs to determine the next node, node type and outcome matter.

Next node determination order:

| Order | Node Type / Outcome | Meaning |
|---:|---|---|
| 1 | Abort Flow | Abort flow has highest precedence if present. |
| 2 | Filter Node Passed | First passing filter with `output_1` is followed. |
| 3 | Filter Node Failed | If no filters pass, failed filters with `output_2` are considered. |
| 4 | Action Node | If no filter path is chosen, first available action is followed. |
| 5 | No Next Node | Flow ends. Decline or error is returned depending on whether payment was attempted. |

Important:

- You can output from one node to multiple nodes, but RevCent determines which one is processed based on this priority.
- Filters are given priority because their pass/fail outcome may intentionally control the flow before actions run.
- Abort flow takes precedence.

---

# Payment Flow Design Principles

## Every Flow Must Ultimately Do One of Three Things

Every path should intentionally end in one of these outcomes:

1. Process payment.
2. Abort flow.
3. End after a failed/declined payment response.

A path that reaches no gateway and no process payment node may produce a generic error.

---

## Choose Gateway Before Processing Payment

The flow should always choose a gateway before `action_process_payment`.

Correct:

```text
start_payment_request → action_choose_gateway → action_process_payment
```

Dangerous:

```text
start_payment_request → action_process_payment
```

---

## Limit Retry Attempts

If a payment declines, retry logic can be useful, but it must be limited.

Use:

- `filter_process_payment_count`
- `filter_gateway_response`
- gateway exclusions
- abort paths
- max attempts settings

Avoid retry loops.

---

## Use Abort Flow for Hard Stops

Use `action_abort_flow` when:

- The request should not be processed.
- The decline is considered final.
- Business rules prohibit additional attempts.
- A Function returns a custom error.
- The flow cannot safely proceed.

---

## Use Functions Carefully

Use `action_custom_function` only when standard filters and actions are not enough.

Avoid using Functions for simple routing that can be handled by normal filters.

If using `Wait For Response`:

- Add `output_2` fallback.
- Keep logic fast.
- Avoid slow third-party calls.
- Return only properties needed.
- Test thoroughly.
- Understand that bad code can prevent payments.

---

# Simple Flow Example

> MCP note: The JSON example below is intentionally minimal for readability. In real use, the `action_choose_gateway` node should almost always include the appropriate failsafe gateway setting from the current schema/account configuration.

This flow starts payment request, chooses one gateway, and processes payment.

```json
{
  "name": "Primary Credit Card Profile",
  "description": "Version: v1.0.0\nCreated: 2026-05-27\nPurpose: Simple profile that chooses the primary gateway group and processes the payment.\nRouting: Uses the primary gateway group with a failsafe gateway.\nFlow Type: Simple\nChange Summary: Initial Payment Profile creation. No retry or advanced routing.",
  "enabled": false,
  "payment_flow": [
    {
      "id": "start",
      "type": "start_payment_request",
      "inputs": {},
      "outputs": {
        "output_1": {
          "connections": [
            {
              "node": "choose_gateway",
              "output": "input_1"
            }
          ]
        }
      },
      "position": {
        "x_axis": 0,
        "y_axis": 0
      },
      "node_settings": {
        "node_note": "Start payment request."
      }
    },
    {
      "id": "choose_gateway",
      "type": "action_choose_gateway",
      "inputs": {
        "input_1": {
          "connections": [
            {
              "node": "start",
              "input": "output_1"
            }
          ]
        }
      },
      "outputs": {
        "output_1": {
          "connections": [
            {
              "node": "process_payment",
              "output": "input_1"
            }
          ]
        }
      },
      "position": {
        "x_axis": 400,
        "y_axis": 0
      },
      "node_settings": {
        "selection_source": "gateway_group",
        "selection_method": "evenly_distribute",
        "gateway_groups": [
          {
            "order": 0,
            "id": "XXXXXXXXXXXXXXXXXXXX"
          }
        ],
        "node_note": "Choose from the primary gateway group. Prefer gateway groups for proper business/corp routing."
      }
    },
    {
      "id": "process_payment",
      "type": "action_process_payment",
      "inputs": {
        "input_1": {
          "connections": [
            {
              "node": "choose_gateway",
              "input": "output_1"
            }
          ]
        }
      },
      "outputs": {
        "output_1": {
          "connections": []
        },
        "output_2": {
          "connections": []
        }
      },
      "position": {
        "x_axis": 800,
        "y_axis": 0
      },
      "node_settings": {
        "node_note": "Process payment."
      }
    }
  ]
}
```

Important:

- Replace the gateway group ID with a real 20-character user gateway group ID.
- Prefer gateway groups over individual gateways unless the user explicitly wants a specific gateway.
- Create disabled first.
- Review and test before enabling.

---

# Advanced Flow Patterns

## Route by Currency

Use when different currencies should use different gateways.

Example:

```text
start
  ↓
filter_currency USD
  ├─ passed → choose USD gateway group → process
  └─ failed → choose default gateway group → process
```

Use only if the user gives exact currency routing rules.

---

## Route by Campaign

Use when certain campaigns require separate gateways.

Example:

```text
start
  ↓
filter_campaign Campaign A
  ├─ passed → choose Campaign A gateways → process
  └─ failed → choose default gateways → process
```

Use for:

- Affiliate campaigns
- Paid media campaigns
- High-risk campaigns
- International campaigns

---

## Route by Attempt Count

Use when each attempt should use a different gateway.

Example:

```text
Attempt 1 → Gateway A
Attempt 2 → Gateway B
Attempt 3+ → Gateway C
```

Important:

Set filter priorities carefully.

A `>= 3` filter should be checked before a `>= 2` filter if the `>= 2` filter is meant to only catch attempt two.

---

## Route by Gateway Response

Use after a declined payment attempt.

Example:

```text
process payment
  ↓ declined
filter_gateway_response contains "insufficient funds" or "stolen card"
  ├─ passed → abort flow
  └─ failed → choose fallback gateway → process payment
```

Use to distinguish:

- Hard declines
- Soft declines
- 3DS-required responses
- Retryable declines
- Fraud-related declines

---

## Function-Based Decline Routing

Use only when normal gateway response filters are not sufficient.

Example:

```text
process payment
  ↓ declined
action_custom_function
  ├─ response says abort → abort flow
  ├─ response sets gateway → process payment
  └─ function error/timeout → choose safe fallback gateway
```

Required safe design:

- `output_2` fallback must be connected.
- Function should return within 8 seconds.
- Function should not be allowed to block all payment processing on error.
- Function response should only include the properties needed.

---

# Custom Function Event Data

When a Function is executed from a payment flow, it receives `event.data`.

Important paths include:

```javascript
event.data.item_type
event.data.item_id
event.data.item_event
event.data.item_details.request
event.data.item_details.entity
event.data.item_details.customer
event.data.item_details.customer_card
event.data.item_details.campaign
event.data.item_details.payment_profile
event.data.item_details.payment_amount
event.data.item_details.products
event.data.item_details.shipping
event.data.item_details.tax
event.data.item_details.gateway_history
event.data.item_details.node_id
event.data.item_details.next_nodes
event.data.item_details.current_step
event.data.item_details.step_array
event.data.item_details.flow_path
```

Use this data to make routing decisions only when necessary.

---

## Function Response Object

If using `Wait For Response`, the Function may return:

```json
{
  "next_node_id": "43965f05-887a-4e70-8646-0410440a3494",
  "next_output": "1",
  "set_gateway_id": "bOLjn0yvKpUp10qK298R",
  "selection_method": "evenly_distribute",
  "choose_gateways": ["2r7zOBMldVIomKNdKZoG"],
  "choose_gateway_groups": ["GOGaPRql9oUAAkrm5Ll9"],
  "custom_error": "Card CVV Invalid"
}
```

| Field | Purpose |
|---|---|
| `next_node_id` | Route to a specific next node connected to the Function node. |
| `next_output` | Use Function node output `1` `output_1` or `output_2`. |
| `set_gateway_id` | Set a specific gateway for payment processing. Requires a following process-payment path. |
| `selection_method` | Override a following Choose Gateway node’s selection method. |
| `choose_gateways` | Override following Choose Gateway node gateway selections. |
| `choose_gateway_groups` | Override following Choose Gateway node gateway group selections. |
| `custom_error` | Return custom error through a following abort flow node. Requires `next_node_id` to point to the abort node. |

If the Function response does not need to affect the flow, use `Queue And Continue`.

---

# Additional Profile Settings That Can Override Flow

Some additional settings can take precedence over the payment flow. If these settings trigger, the flow may stop or never begin.

---

## Kill Terms

Kill terms stop the payment flow if a declined gateway response contains specific words or phrases.

Kill terms are powerful and risky because they can stop a payment flow and may cancel/void the related sale. They should only be used when the business intentionally wants certain gateway responses to end the payment attempt.

Important:

- Applies to initial sale attempts.
- Does not apply to renewals or trial expirations.
- Can cancel/void the related sale.
- Should be used only for specific hard-decline terms.
- Generic terms can kill too many sales.
- The user must explicitly state any kill terms.
- MCP must never invent, infer, guess, or auto-generate kill terms.
- MCP must not silently include broad user-provided kill terms without warning the user first.

---

### Required MCP Behavior for Kill Terms

MCP should follow this process before including kill terms:

1. Ask the user whether they want kill terms.
2. Require the user to explicitly provide the exact kill terms.
3. Review each provided term for broadness and false-positive risk.
4. Warn the user if any term appears too broad, generic, or likely to match unrelated gateway responses.
5. Explain what could happen if the term is included.
6. Only include the kill term after the user confirms they still want it included.

MCP should not write:

```text
I will add common hard-decline kill terms.
```

MCP should instead ask:

```text
Which exact gateway response words or phrases should stop the payment flow as kill terms?
```

---

### Broad Kill Term Warning

If the user provides broad terms, MCP should warn before including them.

Potentially dangerous terms include:

```text
the
and
card
declined
error
failed
invalid
payment
do not honor
insufficient
```

These terms may appear in many gateway responses and could cause false positives.

For example, the term:

```text
card
```

could match many unrelated responses, including responses that may still be recoverable.

The term:

```text
declined
```

could match nearly every decline response and may stop retry logic even when the decline is soft or recoverable.

The term:

```text
insufficient
```

may match insufficient-funds declines, which some businesses may want to retry later rather than kill immediately.

---

### Example Warning Message

If the user explicitly provides a broad term, MCP should say something like:

```text
You provided `declined` as a kill term. This may be too broad because many gateway responses contain the word declined, including recoverable soft declines. Including it could cause the payment flow to stop and potentially cancel/void sales more often than intended. Do you still want to include `declined` as a kill term?
```

Another example:

```text
You provided `card` as a kill term. This is likely too broad because many gateway messages mention card even when the response is not a hard decline. This could create false positives and stop valid retry paths. Please confirm before I include it.
```

---

### Better Kill Term Practice

Better kill terms should usually be exact gateway response phrases that the business has reviewed and intentionally wants to treat as hard stops.

MCP should not provide a default list of “better” terms because kill terms depend on:

- The specific gateway.
- The gateway’s actual response text.
- The business’s retry policy.
- Whether a decline is considered hard or soft.
- Whether the user wants the sale canceled/voided.
- Whether recovery attempts should continue.

The user must provide the exact terms.

MCP can help evaluate risk, but cannot invent the kill terms.

---

### Kill Term Decision Rule

Use this rule:

```text
No explicit user-provided kill term = no kill term.
```

Use this additional safety rule:

```text
Explicit user-provided kill term that appears broad = warn user and require confirmation before including.
```

---

## Max Attempts

Max attempts can cancel/void a sale if declined Payment Profile attempts reach the configured number.

Important distinction:

A Payment Profile attempt is the completion of the entire flow, not each process-payment node inside the flow.

Example:

If the flow has 3 process-payment nodes and max attempts is 3, the customer may experience up to 9 declines before max attempts is reached.

MCP should explain this clearly when configuring max attempts.

---

# Custom Error Handling

Payment flows can return custom errors.

Developer guidance:

| Scenario | Customer-Facing Handling |
|---|---|
| API response `code` is not `1` and non-empty `custom_error` exists | Display `custom_error` to the customer. |
| API response `code` is not `1`, `error_code` is `E0690`, and non-empty `message` exists | Display `message` to the customer. |

Use custom errors carefully.

They should be clear, customer-safe, and not expose internal gateway or fraud logic.

---

# MCP Questions Before Creating a Payment Profile

Before creating, MCP should confirm:

```text
Has the Payment Profile overview been reviewed?
```


Before creating a Payment Profile, MCP should ask enough questions to build the correct flow.

Critical questions:

1. What initial version should be used in the description? Default should usually be `v1.0.0`.
2. Is this a simple or advanced Payment Profile?
3. What request types should this profile support?
   - Initial sale
   - Pending sale recovery
   - Subscription renewal
   - Trial expiration
4. Which gateway groups should be used for each business/corp route, and are any individual gateways explicitly required?
5. Should gateway selection be evenly distributed, random, round robin, or sort order?
6. Which gateway should be used as the failsafe gateway if normal selection produces no eligible gateway?
7. Should different campaigns route differently?
8. Should different currencies route differently?
9. Should different card types or BIN profiles route differently?
10. Should payment amount affect routing?
11. Should product group affect routing?
12. Should metadata affect routing?
13. Should customer group affect routing?
14. What should happen on decline?
15. Which exact user-provided gateway response terms should stop retries as kill terms, and has the user confirmed any broad terms after being warned?
16. Which gateway response terms should retry through another gateway?
17. How many payment attempts are allowed in a single flow?
18. Should a Function be used?
19. If a Function is used, should the flow wait for response or queue and continue?
20. What should happen if the Function fails or times out?
21. Should metadata be inserted?
22. Should custom error messages be returned?
23. Should the profile be created disabled first?

If the user cannot clearly answer these questions, MCP should create a simple disabled profile or ask for clarification rather than inventing advanced routing logic.
---

# MCP Safety Rules


## Do Not Cross Business/Corp Gateway Boundaries Accidentally

If the RevCent account contains gateways for multiple businesses, brands, stores, or corporations, MCP must be careful not to route payments through the wrong gateways.

Best practice:

```text
Organize gateways into gateway groups and route Payment Profiles through those gateway groups.
```

MCP should not mix gateways from different businesses/corps in the same route unless the user explicitly confirms that the cross-business/corp routing is intentional.

Before creating the flow, MCP should confirm:

- Which business/corp the Payment Profile is for.
- Which gateway group belongs to that business/corp.
- Which fallback/failsafe gateway belongs to that business/corp.
- Whether any cross-business/corp fallback behavior is intentional.


## Do Not Invent Payment Logic

MCP should not invent:

- Gateway IDs
- Gateway group IDs
- Retry rules
- Kill terms
- Gateway response terms
- Campaign routing rules
- Metadata routing rules
- Amount thresholds
- Function behavior
- Custom error messages

The user must provide these rules or the MCP must retrieve them from existing account configuration.

For kill terms specifically:

- MCP must never invent kill terms.
- MCP must only include kill terms explicitly stated by the user.
- If a user-provided kill term appears too broad or likely to cause false positives, MCP must warn the user before including it.
- MCP should require confirmation before including broad terms such as `card`, `declined`, `error`, `failed`, or other generic words.

---

## Prefer Simple Flow Unless Advanced Rules Are Explicit

If the user says:

```text
Create a payment profile that processes credit cards.
```

The MCP should create or propose a simple flow.

If the user says:

```text
Route USD to one gateway group, EUR to another, retry insufficient funds once, and abort stolen card declines.
```

Then an advanced flow may be appropriate.

---

## Create Disabled First

Recommended default:

```json
"enabled": false
```

The user can review/test before enabling.

---

---

# Visual Payment Flow Review Requirement for User-Interactive MCP Workflows

When the MCP is interacting with a human user, before calling `CreatePaymentProfile`, it should show the user a visual representation of the payment flow it intends to create.


This visual review requirement is specifically for user-interactive MCP workflows where a human is in the loop.

If the MCP is running in a fully automated workflow without direct user direction or review, a user-facing visual diagram is not truly required because there is no human available to approve, reject, or request changes. In that case, the MCP should still internally validate the flow, log or store a clear structured representation of the intended flow, and follow all safety rules before creating the Payment Profile.

Payment Profiles are logic flows that directly affect credit card payment processing. Humans usually understand flow logic more reliably when they can see it visually instead of only reading JSON.

MCP should not rely only on a JSON `payment_flow` array when asking the user to approve a Payment Profile. It should also show a diagram that clearly communicates:

- Where the flow starts.
- Which filters are checked.
- Which gateways or gateway groups are chosen.
- Where payment is processed.
- What happens on success.
- What happens on decline.
- What happens on Function success/failure.
- Where metadata is inserted.
- Where the flow aborts.
- Which paths use `output_1`.
- Which paths use `output_2`.
- Which gateway is the failsafe gateway.

The user should be able to approve, disapprove, or request changes based on the visual flow before the MCP creates the Payment Profile.

---

## Required MCP Behavior When Interacting With a User

When a human user is in the loop, before creating a Payment Profile, MCP should:

1. Build the proposed `payment_flow`.
2. Generate a visual depiction of the flow.
3. Show the visual depiction to the user.
4. Explain each path in plain language.
5. Highlight any high-risk areas:
   - Retry logic
   - Abort flow paths
   - Kill terms
   - Custom Function nodes
   - Missing or intentionally omitted failsafe gateways
   - Gateway response routing
   - Payment attempts after declines
6. Ask the user to approve or request changes.
7. Only call `CreatePaymentProfile` after the user approves the visual and logical flow.

Recommended approval prompt:

```text
Please review the payment-flow diagram below. This is the logic I will create in the Payment Profile. Confirm that the routing, retry behavior, abort paths, gateway choices, and failsafe gateway are correct, or tell me what to change before I create it.
```

---

---

## Automated / Non-Interactive MCP Workflows

If the MCP is operating automatically without a human user actively reviewing the flow, it does not need to display a visual diagram.

However, it should still create an internal or logged representation of the flow so that the flow can be audited later.

For automated workflows, MCP should still:

1. Validate that the flow is structurally correct.
2. Confirm there is exactly one `start_payment_request` node.
3. Confirm each `action_choose_gateway` node has a failsafe gateway unless intentionally omitted by prior configuration.
4. Confirm a gateway is chosen before payment is processed.
5. Confirm retry paths are limited.
6. Confirm abort paths are intentional.
7. Confirm Function nodes have safe `output_2` fallback behavior.
8. Confirm kill terms were explicitly provided by configuration or user instruction, never invented.
9. Log or store the generated node list and connection map.
10. Create the Payment Profile disabled unless the automation is explicitly authorized to enable it.

In other words:

```text
Human in loop = show visual diagram for review and approval.
No human in loop = no user-facing visual required, but internal validation and audit representation are still required.
```


## Recommended Visual Format: Mermaid Flowchart

When possible, MCP should use a Mermaid flowchart because it is readable in Markdown and can visually represent branches.

Use `output_1` and `output_2` labels explicitly.

Example:

```mermaid
flowchart TD
    A[start_payment_request] -->|output_1| B[action_choose_gateway<br/>Primary Gateway Group<br/>Failsafe: Gateway A]
    B -->|output_1| C[action_process_payment]
    C -->|output_1 success| D[Payment Approved<br/>Flow Ends]
    C -->|output_2 decline/error| E[action_abort_flow<br/>Return Gateway Decline]
```

Plain-language explanation:

```text
The payment request starts, chooses a gateway from the primary gateway group, uses Gateway A as the failsafe, and then processes payment. If payment succeeds, the flow ends successfully. If payment declines or errors, the flow ends with the gateway decline.
```

---

## Visual Example: Simple Payment Profile

Simple profile:

```text
start_payment_request → action_choose_gateway → action_process_payment
```

Mermaid diagram:

```mermaid
flowchart TD
    START[start_payment_request] -->|output_1| GATEWAY[action_choose_gateway<br/>Gateway or Gateway Group<br/>Failsafe Gateway Required]
    GATEWAY -->|output_1| PROCESS[action_process_payment]
    PROCESS -->|output_1 success| SUCCESS[Success<br/>Return Approved Payment]
    PROCESS -->|output_2 decline/error| DECLINE[Decline/Error<br/>Return Gateway Response]
```

What the user should review:

- Is the correct gateway or gateway group selected?
- Is the failsafe gateway correct?
- Should declines simply return the gateway response?
- Should there be retry logic?
- Should there be custom error handling?
- Should metadata be inserted?

---

## Visual Example: Retry Once Through Fallback Gateway

Example:

```mermaid
flowchart TD
    START[start_payment_request] -->|output_1| PRIMARY[action_choose_gateway<br/>Primary Gateway Group<br/>Failsafe: Gateway A]
    PRIMARY -->|output_1| PROCESS1[action_process_payment<br/>Attempt 1]

    PROCESS1 -->|output_1 success| SUCCESS[Success<br/>Flow Ends]
    PROCESS1 -->|output_2 decline/error| COUNT[filter_process_payment_count<br/>Count <= 1?]

    COUNT -->|output_1 yes| FALLBACK[action_choose_gateway<br/>Fallback Gateway Group<br/>Failsafe: Gateway B]
    COUNT -->|output_2 no| ABORT[action_abort_flow<br/>Stop Retry Attempts]

    FALLBACK -->|output_1| PROCESS2[action_process_payment<br/>Attempt 2]
    PROCESS2 -->|output_1 success| SUCCESS
    PROCESS2 -->|output_2 decline/error| ABORT
```

Plain-language explanation:

```text
The flow attempts payment once through the primary gateway group. If it declines, it checks whether this is still within the allowed process-payment count. If yes, it chooses a fallback gateway group and tries once more. If the fallback attempt declines, the flow aborts and returns an error/decline. Both choose gateway nodes should have failsafe gateways.
```

What the user should review:

- Is one retry allowed?
- Should the retry happen for all declines or only certain gateway responses?
- Is the fallback gateway group correct?
- Is the failsafe gateway correct for both gateway-selection nodes?
- Should hard declines skip the retry path?
- Should the abort node return a custom error?

---

## Visual Example: Decline Routing by Gateway Response

Example:

```mermaid
flowchart TD
    START[start_payment_request] -->|output_1| GATEWAY[action_choose_gateway<br/>Primary Gateway Group<br/>Failsafe: Gateway A]
    GATEWAY -->|output_1| PROCESS[action_process_payment]

    PROCESS -->|output_1 success| SUCCESS[Success<br/>Flow Ends]
    PROCESS -->|output_2 decline/error| HARD[filter_gateway_response<br/>User-provided hard-decline terms?]

    HARD -->|output_1 match| ABORT[action_abort_flow<br/>Stop Flow]
    HARD -->|output_2 no match| RETRY_GATEWAY[action_choose_gateway<br/>Fallback Gateway Group<br/>Failsafe: Gateway B]

    RETRY_GATEWAY -->|output_1| RETRY_PROCESS[action_process_payment]
    RETRY_PROCESS -->|output_1 success| SUCCESS
    RETRY_PROCESS -->|output_2 decline/error| ABORT
```

Important:

- The hard-decline gateway response terms must be explicitly provided by the user.
- MCP must not invent gateway response terms or kill terms.
- If any user-provided term appears broad, MCP must warn the user before including it.

What the user should review:

- Are the gateway response terms exact and intentional?
- Are any terms too broad?
- Should matching terms abort immediately?
- Should non-matching declines retry?
- Which gateway or gateway group should receive the retry?

---

## Visual Example: Function-Based Routing

Example:

```mermaid
flowchart TD
    START[start_payment_request] -->|output_1| GATEWAY[action_choose_gateway<br/>Primary Gateway<br/>Failsafe: Gateway A]
    GATEWAY -->|output_1| PROCESS[action_process_payment]

    PROCESS -->|output_1 success| SUCCESS[Success<br/>Flow Ends]
    PROCESS -->|output_2 decline/error| FUNC[action_custom_function<br/>Wait For Response<br/>Max 8 seconds]

    FUNC -->|output_1 function success| ROUTE{Function Decision}
    FUNC -->|output_2 function failure/timeout| SAFE[action_choose_gateway<br/>Safe Fallback Gateway<br/>Failsafe: Gateway B]

    ROUTE -->|Retry| FALLBACK[action_choose_gateway<br/>Function-selected Gateway]
    ROUTE -->|Abort| ABORT[action_abort_flow<br/>Custom Error if provided]

    FALLBACK -->|output_1| PROCESS2[action_process_payment]
    SAFE -->|output_1| PROCESS2

    PROCESS2 -->|output_1 success| SUCCESS
    PROCESS2 -->|output_2 decline/error| ABORT
```

What the user should review:

- Is a Function actually necessary?
- Should the flow wait for the Function response or queue and continue?
- What happens if the Function fails or times out?
- Does `output_2` from the Function route to a safe fallback?
- Can the Function select a gateway?
- Can the Function return a custom error?
- Is the Function response behavior clearly defined?

---

## ASCII Fallback Format

If Mermaid is not available, MCP should still show a plain-text visual representation.

Example:

```text
[start_payment_request]
        |
        | output_1
        v
[action_choose_gateway]
  - Gateway Group: Primary Gateways
  - Failsafe: Gateway A
        |
        | output_1
        v
[action_process_payment]
        |
        | output_1 success
        v
[Success / Approved]

[action_process_payment]
        |
        | output_2 decline/error
        v
[Decline / Return Gateway Response]
```

Even this simple representation is better than showing JSON only.

---

## Visual Review Checklist

When showing the visual payment flow, MCP should ask the user to verify:

1. Does the flow start correctly?
2. Does every intended path eventually process payment, abort, or intentionally return decline/error?
3. Does every `action_choose_gateway` node use the correct gateway group where possible, and are any individual gateways intentionally selected?
4. Does every `action_choose_gateway` node have a failsafe gateway, unless intentionally omitted?
5. Does every `action_process_payment` node have clear `output_1` and `output_2` behavior?
6. Is retry logic correct and limited?
7. Are gateway response filters correct?
8. Are kill terms explicitly user-provided and not invented?
9. Were broad user-provided kill terms warned about?
10. Are Function nodes necessary and safe?
11. Does every Function node have safe `output_2` fallback behavior?
12. Are abort nodes intentional?
13. Are custom errors accurate and customer-safe?
14. Are metadata insertions correct?
15. Should the profile be created disabled first?

---

## Visual Approval Requirement

MCP should treat visual approval as part of the Payment Profile creation process only when interacting with a human user.

Recommended final prompt before creation:

```text
I will create the Payment Profile exactly as shown in this diagram. Please approve it or tell me what to change. I will not create it until you confirm the flow logic is correct.
```

This is especially important in user-interactive workflows because Payment Profiles affect real credit card processing.

For automated workflows without a human in the loop, MCP should not wait for visual approval, but it should still perform internal validation and retain a structured representation of the generated flow.


## Show the Flow for Review

When interacting with a human user, before calling `CreatePaymentProfile`, MCP should display both a human-readable summary and a visual flow depiction.

The review should include:

- Flow purpose
- Mermaid or ASCII visual diagram
- Node list
- Node connections
- `output_1` paths
- `output_2` paths
- Gateway/gateway group IDs
- Failsafe gateway for each `action_choose_gateway` node
- Retry behavior
- Abort behavior
- Function behavior
- Expected success path
- Expected decline path

MCP should ask the user to confirm or revise the flow because incorrect logic can break payments. If the MCP is running in a non-interactive automated workflow, this user-facing review step is not required, but equivalent internal validation should still occur.

---

# Validation Checklist

Before creating the Payment Profile:

1. Description includes initial versioning, usually `v1.0.0`, plus created date, purpose, routing summary, flow type, and change summary.
2. If interacting with a human user, a visual flow diagram was shown for approval.
3. If interacting with a human user, the user approved the diagram or requested changes before creation.
4. If running automatically without a human in the loop, a structured internal representation of the flow was logged or retained.
5. There is exactly one `start_payment_request`.
6. Every node ID is unique.
7. Every connection references an existing node.
8. Every non-start node has `input_1`.
9. Start node has no inputs.
10. Choose Gateway happens before Process Payment.
11. Every Process Payment node has an intentional success path and decline path.
12. Retry paths are limited.
13. Decline paths either retry, abort, or intentionally end.
14. Every gateway group ID exists and belongs to the intended business/corp route.
15. Every individual gateway ID, if used, exists and is intentionally selected.
16. Gateway groups are preferred over individual gateways unless the user explicitly requires individual gateways.
17. Every gateway group used belongs to the intended business/corp routing context.
18. Every individual gateway ID, if used, was explicitly requested or confirmed by the user.
Every `action_choose_gateway` node has a failsafe gateway unless the user explicitly confirmed no failsafe should be used.
19. Filter priorities are intentional.
20. Merge filters only connect filter nodes through `output_3`.
21. Insert Metadata nodes do not accidentally stop the main flow.
22. Function nodes have `output_2` fallback if using wait-for-response.
23. Function timeout behavior is safe.
24. Abort flow paths are intentional.
25. Custom errors are customer-safe.
26. Kill terms, if used, were explicitly provided by the user; broad or false-positive-prone terms were flagged and confirmed before inclusion.
27. Max attempts behavior is understood.
28. The profile is created disabled unless the user explicitly wants it enabled.
---

# Output Schema

A successful `CreatePaymentProfile` response returns:

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

Fields:

| Field | Description |
|---|---|
| `api_call_id` | 20-character API call ID. |
| `api_call_unix` | Unix timestamp when the API call was initiated. |
| `code` | Response code. `1` indicates success. |
| `payment_profile_id` | 20-character Payment Profile ID. |
| `result` | Human-readable result message. |

---

# Quick Reference

Minimum safe profile:

```text
start_payment_request → action_choose_gateway → action_process_payment
```

Use simple profile when:

```text
No special routing is required.
```

Use advanced profile only when:

```text
The user provides exact payment-routing rules.
```

Most important rules:

```text
Start the description with version information, usually v1.0.0, so future edits and backups remain consistent.
A Payment Profile must ultimately attempt payment through a chosen gateway, abort intentionally, or return a deliberate decline/error result. Do not leave ambiguous or accidental flow paths.
```


---

# Overview Reference

AI/MCP should read the Payment Profile overview for broad conceptual understanding before creating, editing, or deeply reviewing Payment Profiles:

```text
https://revcent.com/documentation/markdown/mcp/operation/OverviewPaymentProfile.md
```


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