# RevCent Payment Profiles Overview for MCP This document gives an MCP-oriented overview of RevCent Payment Profiles: what they do, why they matter, how they help ecommerce businesses process credit card payments, and how MCP systems should think about creating or editing them. Sources: - RevCent API/MCP schemas: - `CreatePaymentProfile` - `EditPaymentProfile` - `GetPaymentProfile` - `GetPaymentProfiles` - RevCent Knowledge Base: Payment Profile — `https://kb.revcent.com/en/payments/credit-card/next-gen-payment-profile` --- ## What Is a Payment Profile? A Payment Profile is a payment-routing flow used to process credit card payments. It defines the logic RevCent follows when a payment request is initiated. That logic can be simple, such as choosing one gateway group and processing payment, or advanced, such as routing by request type, campaign, currency, amount, customer group, metadata, gateway response, or custom Function results. A Payment Profile ultimately answers the question: ```text When this customer attempts to pay by credit card, how should RevCent route and process the payment? ``` At a minimum, a usable payment-processing flow must: 1. Start the payment request. 2. Choose a gateway or gateway group. 3. Process the payment. Conceptual minimum: ```text Payment Request → Choose Gateway → Process Payment ``` If the flow never chooses a gateway or never reaches a process-payment node, the credit card payment may never be attempted. --- ## Why Payment Profiles Matter Payment Profiles are critical payment infrastructure. They control: - Which gateways are used. - Which gateway groups are used. - Whether payment routing changes by business/corp, brand, campaign, currency, product, customer group, or metadata. - Whether a transaction is attempted. - Whether a declined transaction is retried. - Whether a different gateway is used after a decline. - Whether a flow aborts. - Whether custom errors are returned. - Whether metadata is inserted. - Whether a custom Function is run. - Whether subscription renewals or trial expirations use different routing than initial sales. This makes Payment Profiles one of the most important configuration areas in an ecommerce account. Incorrect Payment Profile logic can break checkout, cause valid payments to fail, route payments through the wrong merchant account, or cause gateway retry behavior that the business did not intend. --- # What Payment Profiles Do for Ecommerce Businesses Ecommerce businesses use Payment Profiles to turn payment processing rules into a structured flow. A Payment Profile can help a business: - Process initial credit card sales. - Process subscription renewals. - Process trial expirations. - Recover pending sales. - Route different brands or corporations to the correct gateways. - Separate high-risk and low-risk traffic. - Route domestic and international traffic differently. - Use different gateway groups by campaign or traffic source. - Retry recoverable declines through a fallback path. - Stop payment attempts for hard declines. - Insert metadata about payment-routing decisions. - Run Functions for advanced routing logic. - Return more helpful custom errors. - Reduce gateway overuse by distributing volume. - Improve approval rates through intentional gateway routing. - Avoid mixing gateways across businesses/corps inside the same RevCent account. --- ## Ecommerce Examples | Business Need | How a Payment Profile Helps | |---|---| | Standard checkout | Choose the correct gateway group and process payment. | | Multiple businesses in one account | Route Business A payments through Business A gateway groups and Business B payments through Business B gateway groups. | | Subscription billing | Use request-type routing so renewals can use different gateways than initial sales. | | Trial billing | Route trial expiration payments differently from initial checkout. | | Declined payment recovery | Retry recoverable declines through fallback gateway groups. | | Campaign routing | Route specific campaigns or traffic sources to specific gateway groups. | | Currency routing | Route USD, EUR, GBP, or other currencies to appropriate gateways. | | High-risk routing | Route riskier campaigns/products to gateway groups intended for that traffic. | | Gateway volume balancing | Use gateway selection methods to reduce overuse of a single gateway. | | Business reporting | Insert metadata to record which branch, gateway, or rule was used. | --- # Payment Profiles Are Flow Logic, Not Just Settings A Payment Profile is not simply a static payment setting. It is a node-based execution flow. When the profile is triggered, RevCent starts at the start node and follows node outputs until the flow: - Processes a payment successfully. - Processes a payment and returns a decline/error. - Routes to another node. - Aborts intentionally. - Ends because no next node exists. This means the Payment Profile should be designed like a decision tree. Every path should be intentional. --- ## Minimum Payment Flow A basic Payment Profile should include: ```text start_payment_request ↓ output_1 action_choose_gateway ↓ output_1 action_process_payment ``` This means: 1. The flow starts when a payment request begins. 2. RevCent chooses a gateway or gateway group. 3. RevCent processes the payment through the chosen gateway. --- ## Simple Flow Visual ```mermaid flowchart TD START[start_payment_request] -->|output_1| CHOOSE[action_choose_gateway
Gateway Group
Failsafe Gateway] CHOOSE -->|output_1| PROCESS[action_process_payment] PROCESS -->|output_1 success| APPROVED[Approved
Flow Ends] PROCESS -->|output_2 decline/error| DECLINED[Declined/Error
Return Response] ``` --- # Simple vs Advanced Payment Profiles ## Simple Payment Profile A simple Payment Profile is appropriate when the business only needs straightforward payment processing. Use simple profiles when: - There is one normal gateway group. - No special routing is needed. - No retry logic is needed. - No custom Function is needed. - No request-type, campaign, currency, metadata, product group, customer group, or amount routing is needed. - The user wants the safest and easiest-to-understand payment flow. Simple profile example: ```text Start payment request → Choose gateway group → Process payment ``` Best for: - Standard ecommerce checkout. - New accounts. - Small businesses. - Test configurations. - Businesses that do not yet have advanced routing needs. --- ## Advanced Payment Profile An advanced Payment Profile is appropriate when payment routing needs to change based on business rules. Use advanced profiles when the business needs: - Different gateway groups for different businesses/corps. - Different gateways by campaign. - Different gateways by currency. - Different gateways by card type. - Different gateways by BIN profile. - Different routing by product group. - Different routing by customer group. - Different routing by payment amount. - Different routing by metadata. - Different routing by request type. - Different logic for initial sale, subscription renewal, trial expiration, or pending sale recovery. - Decline routing based on gateway response. - Retry logic after certain declines. - Abort logic for hard stops. - Custom Functions for advanced decisions. Advanced profile example: ```text Start payment request ↓ Filter request type ↓ Filter currency / campaign / metadata ↓ Choose gateway group ↓ Process payment ↓ If declined, evaluate gateway response ↓ Retry, abort, or choose a fallback gateway group ``` Advanced profiles should only be created when the business rules are explicit. MCP should never invent advanced payment routing logic. --- # Gateway Groups Are Preferred Gateway groups should generally be preferred over individual gateways as the selection source. Best practice: ```text Use gateway groups whenever possible. ``` The reason is operational safety. A single RevCent account may contain gateways for multiple: - Businesses - Corporations - Brands - Stores - Campaign types - Currencies - Risk levels - Merchant accounts - Payment 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 in the same RevCent account. --- ## Why Gateway Groups Help Gateway groups help prevent: - 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. - Fallback routing selecting a gateway that should not apply to the business/corp. Instead of hard-coding individual gateway IDs throughout the flow, a Payment Profile can select from a gateway group that already represents the correct routing boundary. --- ## Gateway Group Organization Examples | Gateway Group Type | Example | |---|---| | Business/corp | `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 Gateways` | | Risk level | `Low Risk Gateways`, `High Risk Gateways` | | Campaign type | `Affiliate Gateways`, `Paid Search Gateways` | | Fallback | `Primary Gateways`, `Fallback Gateways` | --- # Failsafe Gateways A choose-gateway node should almost always have a failsafe gateway. A failsafe gateway is the fallback gateway used when normal gateway selection cannot find an eligible gateway. Gateway selection can fail when: - All selected gateways are disabled. - A gateway group has no eligible enabled gateways. - Revenue rules exclude gateways. - Time rules exclude gateways. - Preference rules eliminate available gateways. - Exclusion rules eliminate available gateways. - Last-approved or last-declined selection has no matching prior gateway. - Gateway configuration changes after the profile is created. Without a failsafe gateway, gateway selection may terminate the flow and return an error instead of attempting payment through a safe fallback. Recommended rule: ```text Every action_choose_gateway node should include a failsafe gateway unless the user explicitly confirms no failsafe should be used. ``` The failsafe gateway should belong to the same business/corp routing context as the gateway group. 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 cross-business/corp fallback routing is explicitly intended. --- # Common Payment Profile Node Categories Payment Profile flows are built from node types. ## Start Node | Node Type | Purpose | |---|---| | `start_payment_request` | Begins the flow when the Payment Profile is triggered. Only one start node can exist. | --- ## Action Nodes | Node Type | Purpose | |---|---| | `action_choose_gateway` | Selects the gateway or gateway group to use. | | `action_process_payment` | Processes the payment through the chosen gateway. | | `action_abort_flow` | Stops the flow and returns an error/decline result. | | `action_insert_metadata` | Inserts metadata on the side without controlling the main flow path. | | `action_custom_function` | Runs a Function for advanced flow logic. | --- ## Filter Nodes | Node Type | Purpose | |---|---| | `filter_request_type` | Routes by request type, such as initial sale, renewal, trial expiration, or pending sale recovery. | | `filter_campaign` | Routes by campaign. | | `filter_currency` | Routes by currency. | | `filter_card_type` | Routes by card brand/type. | | `filter_bin_profile` | Routes by BIN profile. | | `filter_customer_group` | Routes by customer group. | | `filter_product_group` | Routes by product group. | | `filter_payment_amount` | Routes by payment amount. | | `filter_metadata` | Routes by metadata. | | `filter_gateway_response` | Routes by gateway response text after a payment attempt. | | `filter_attempt_count` | Routes by completed Payment Profile attempts for the entity. | | `filter_process_payment_count` | Routes by number of process-payment nodes executed in the current flow. | | `filter_merge_filters` | Combines multiple filters into an AND condition. | --- # Outputs: `output_1`, `output_2`, and `output_3` Use output names exactly. Do not rely on visual color terminology. | Output | Meaning | |---|---| | `output_1` | Success, passed, true, or matched path depending on node type. | | `output_2` | Decline, error, failed, false, or not-matched path depending on node type. | | `output_3` | Used by `filter_merge_filters` to connect filter nodes into an AND condition. | Examples: - `action_process_payment.output_1` = payment succeeded. - `action_process_payment.output_2` = payment declined or gateway error occurred. - `filter_currency.output_1` = currency matched. - `filter_currency.output_2` = currency did not match. - `action_custom_function.output_1` = Function executed successfully. - `action_custom_function.output_2` = Function failed or timed out. --- # Request Types Payment Profiles may handle different types of payment requests. Common request types include: | Request Type | Meaning | |---|---| | Initial Sale | Customer is making an initial purchase. | | Pending Sale Profile Recovery | A pending sale is being recovered or reprocessed. | | Subscription Renew | A recurring subscription renewal is being billed. | | Trial Expire | A trial is expiring and payment is being attempted. | Different request types may require different routing. For example: - Initial sales may use one gateway group. - Renewals may use another gateway group. - Trial expirations may use a more conservative flow. - Pending sale recovery may use different retry or fallback behavior. --- # Decline and Retry Logic Payment Profiles can define what happens after a payment declines. Possible decline behavior: - Return the gateway decline directly. - Retry through another gateway group. - Evaluate the gateway response. - Abort the flow. - Run a custom Function. - Insert metadata. - Return a custom error. Retry logic must be limited and intentional. Use `filter_process_payment_count` to prevent too many gateway attempts inside a single flow. Do not create retry loops. --- ## Gateway Response Routing Gateway response filters can route based on the most recent gateway response. Use cases: - Retry soft declines. - Abort hard declines. - Route specific gateway responses to a fallback gateway group. - Return custom error messaging. - Send certain responses through a Function for deeper analysis. MCP should not invent gateway response terms. The user should provide the exact terms, or they should come from actual gateway/account data. --- # Kill Terms Kill terms stop the payment flow if a declined gateway response contains specific words or phrases. Kill terms are powerful and risky. They can stop a payment flow and may cancel or void the related sale. Rules: - The user must explicitly state any kill terms. - MCP must never invent kill terms. - MCP must not infer kill terms from general payment knowledge. - MCP must warn the user if a provided term appears too broad or likely to cause false positives. - Broad user-provided terms should require confirmation before inclusion. - If no explicit user-provided kill term exists, use no kill term. Potentially broad terms include: ```text card declined failed error invalid payment insufficient do not honor ``` A broad term can match many gateway responses and may stop retry logic more often than intended. --- # Custom Functions in Payment Profiles Payment Profiles can run Functions through `action_custom_function`. This is advanced and should be used carefully. Functions may be used to: - Make custom routing decisions. - Call an external risk system. - Parse complex gateway responses. - Choose a gateway dynamically. - Return a custom error. - Override gateway selection. - Insert additional business-specific logic. Function run methods include: | Run Method | Meaning | |---|---| | Queue And Continue | Function runs separately and the payment flow continues without waiting. | | Wait For Response | Payment flow waits for the Function response and uses it to determine next behavior. | When using wait-for-response: - Connect `output_2` fallback. - Keep the Function fast. - Avoid slow external calls where possible. - Define timeout behavior. - Test thoroughly. - Understand that Function failure may affect payment processing. --- # Metadata in Payment Profiles Payment Profiles can insert metadata through `action_insert_metadata`. Use metadata to record: - Which gateway group was used. - Which gateway was selected. - Which branch of the flow was used. - Whether a fallback route was triggered. - Which decline path was followed. - Which retry path was used. - Which custom Function decision occurred. Important: `action_insert_metadata` runs on the side and has no outputs. The main payment path must continue separately. Do not route only to metadata insertion and accidentally stop the payment flow. --- # Versioning and Descriptions Payment Profile descriptions should include versioning from creation. Recommended initial version: ```text v1.0.0 ``` Versioning is useful because Payment Profiles often evolve over time. A versioned description helps future edit workflows: - Understand the current flow version. - Match backups to profile states. - Track what changed between versions. - Support rollback. - Identify which version introduced an issue. Recommended description structure: ```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. ``` When editing later, backup filenames should include the version. Example: ```text payment_profile_backup__v1.0.0_.json ``` --- # Visual Review for Human Users When an MCP is interacting with a human user, it should show a visual representation of the proposed Payment Profile flow before creation or major edits. Humans often understand flow logic better visually than by reading JSON. A visual review should show: - Start node. - Gateway/gateway group selection. - Failsafe gateway. - Payment process node. - Success path. - Decline path. - Retry paths. - Abort paths. - Function nodes. - Metadata insertion. - `output_1` and `output_2` paths. Example: ```mermaid flowchart TD START[start_payment_request] -->|output_1| CHOOSE[action_choose_gateway
Business A Gateway Group
Failsafe: Gateway A] CHOOSE -->|output_1| PROCESS[action_process_payment] PROCESS -->|output_1 success| SUCCESS[Approved
Flow Ends] PROCESS -->|output_2 decline/error| DECLINE[Declined/Error
Return Gateway Response] ``` If the MCP is running fully automated without a human in the loop, a user-facing visual is not required. However, it should still internally validate and retain/log a structured representation of the flow. --- # Creating vs Editing Payment Profiles ## Creating a New Payment Profile Creating is safer when: - A new payment strategy is being tested. - The current production profile should not be disturbed. - The requested change is large or structural. - The user wants to test before enabling. - A new business/corp route is being introduced. - A new gateway group strategy is being created. Best practice: ```text Create disabled → review → test → enable intentionally ``` --- ## Editing an Existing Payment Profile Editing is riskier because the profile may already be used in production. Before editing: 1. Retrieve the existing profile. 2. Save a local JSON backup. 3. If a human user is involved, have the user save a local backup too. 4. Use versioned backup filenames. 5. Show before/after flow if changing payment flow. 6. Validate all paths. 7. Consider disabling during structural changes if appropriate. 8. Verify the profile after editing. Editing consequences can include broken checkout, wrong gateway routing, failed renewals, excessive retries, or unintended abort behavior. --- # Ecommerce Use Cases ## Standard Checkout Profile Purpose: ```text Process normal initial credit card sales. ``` Typical flow: ```text start_payment_request → action_choose_gateway → action_process_payment ``` Recommended: - Use gateway group. - Use failsafe gateway. - Create disabled first. - Keep simple unless advanced routing is required. --- ## Subscription Renewal Profile Purpose: ```text Process recurring subscription renewals. ``` May include: - `filter_request_type` - Renewal-specific gateway group - Gateway preference based on prior approval - Limited decline handling - Metadata insertion for renewal route used Important: Renewal routing may need to differ from initial checkout routing. --- ## Trial Expiration Profile Purpose: ```text Process payment when a trial expires. ``` May include: - Request-type filter - Trial-specific gateway group - Conservative retry logic - Custom errors - Metadata insertion --- ## Multi-Business / Multi-Corp Profile Purpose: ```text Route different businesses/corps to the correct gateway groups. ``` May include: - Campaign filters - Metadata filters - Product group filters - Business-specific gateway groups - Business-specific failsafe gateways Best practice: ```text Do not mix gateways across businesses/corps unless explicitly intended. ``` --- ## Currency-Based Profile Purpose: ```text Route payments by currency. ``` Example: ```text USD → US Gateway Group EUR → EU Gateway Group GBP → UK Gateway Group ``` Use when different merchant accounts or gateways are better suited for different currencies. --- ## Decline Recovery Profile Purpose: ```text Retry recoverable declines through fallback routing. ``` May include: - `action_process_payment` - `filter_gateway_response` - `filter_process_payment_count` - fallback gateway group - `action_abort_flow` Important: Retry logic must be limited. Hard-decline terms must not be invented. --- ## High-Risk Campaign Profile Purpose: ```text Route high-risk campaign traffic through designated gateways. ``` May include: - Campaign filters - Metadata filters - Gateway groups for high-risk traffic - Abort paths - Metadata insertion - Possibly Function-based logic Important: Do not route high-risk traffic through gateway groups meant for low-risk traffic. --- # MCP Planning Questions Before creating or editing a Payment Profile, MCP should ask: 1. What is the Payment Profile used for? 2. Is this a new profile or an edit to an existing one? 3. Is the profile for one business/corp or multiple businesses/corps? 4. Which gateway groups should each business/corp use? 5. Are any individual gateways explicitly required? 6. What failsafe gateway should each choose-gateway node use? 7. Which request types should the profile support? 8. Should routing differ by campaign, currency, product group, customer group, metadata, amount, BIN profile, or card type? 9. Should declined payments retry? 10. Which declines should stop immediately? 11. Are kill terms needed? If yes, what exact user-provided terms? 12. Are any provided kill terms broad enough to require warning? 13. How many process-payment attempts are allowed in one flow? 14. Should a custom Function run? 15. What happens if the Function fails or times out? 16. Should metadata be inserted? 17. Should the profile be created disabled first? 18. What version should be included in the description? --- # MCP Safety Principles ## Do Not Invent Payment Logic MCP should not invent: - Gateway group IDs - Gateway IDs - Failsafe gateways - Routing rules - Retry rules - Kill terms - Gateway response terms - Custom Function behavior - Amount thresholds - Metadata routing - Custom errors The user must provide the rules, or the MCP must retrieve them from account configuration. --- ## Prefer Simple Unless Advanced Rules Are Explicit Simple profile: ```text start_payment_request → action_choose_gateway → action_process_payment ``` Advanced profile only when the user has clear business rules. --- ## Create Disabled First Recommended default: ```json "enabled": false ``` This allows review and testing before live use. --- ## Back Up Before Editing Before editing an existing Payment Profile: - Retrieve current settings. - Save a versioned JSON backup. - Ask the human user to save a local backup if a human is in the loop. - Show before/after flow for payment-flow changes. - Keep backup available for rollback. --- ## Validate Every Flow Path Before creating or editing, MCP should verify: - Exactly one start node exists. - Gateway is chosen before payment is processed. - Gateway groups are preferred. - Failsafe gateway exists unless intentionally omitted. - Every retry path is limited. - Every abort path is intentional. - Every Function has safe timeout/error behavior. - Metadata insertion does not stop the main path. - Kill terms are explicitly user-provided. - Broad kill terms are warned about. - Every path processes, aborts, or deliberately returns decline/error. --- # Quick Decision Guide | Business Goal | Payment Profile Design | |---|---| | Standard checkout | Simple flow with one gateway group and failsafe gateway. | | Multiple businesses/corps | Gateway groups organized by business/corp. | | Subscription billing | Request-type routing for subscription renewals. | | Trial billing | Request-type routing for trial expiration. | | Currency routing | Currency filter to route to appropriate gateway groups. | | Campaign routing | Campaign or metadata filters to select gateway groups. | | Decline recovery | Gateway response filters and limited retry paths. | | High-risk routing | Campaign/product/metadata filters and dedicated gateway groups. | | Custom external logic | Function node with safe fallback. | | Reporting flow decisions | Insert metadata on routing decisions. | --- # Summary A Payment Profile is the logic RevCent uses to route and process credit card payments. It is useful for ecommerce businesses because it can: - Process standard payments. - Organize gateways by business/corp. - Route traffic to the right gateway groups. - Support subscriptions and trials. - Handle recoverable declines. - Protect against unsafe routing. - Insert useful metadata. - Use Functions for advanced logic. - Support scalable payment-processing strategies. The most important MCP rule is: ```text Payment Profile logic must be intentional, reviewed, and safe. The profile should ultimately process payment through a chosen gateway, abort intentionally, or return a deliberate decline/error result. ``` --- 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.