# RevCent MCP Overview: Fraud Detections AI/MCP-focused overview of Fraud Detections in RevCent and how they tie into Sentinel Anti Fraud. --- ## Purpose This guide explains how Fraud Detections work in RevCent, how they relate to Sentinel Anti Fraud, which MCP operations are relevant, and how AI/MCP should use BigQuery for reporting on fraud detections. Fraud Detections are important because they represent payment, sale, customer, visitor, or third-party fraud events that may affect risk decisions, reporting, customer support, chargeback prevention, and future fraud blocking. --- ## Core Concept A **Fraud Detection** is a RevCent record that identifies a sale, payment, customer, visitor, or external fraud event as fraudulent or suspected fraudulent. A Fraud Detection can be related to many other RevCent entities, including: ```text Sale Product Sale Credit Card Transaction PayPal Transaction Offline Payment Check Direct Shipment Tax Discount Trial Subscription Subscription Renewal Chargeback Pending Refund API Call Customer Third-Party Shop Third-Party Integration ``` Fraud Detections can be created manually/API-driven from an existing source item, or they can be created as part of an anti-fraud or third-party integration workflow. --- ## How Fraud Detections Tie Into Sentinel Anti Fraud Sentinel Anti Fraud is RevCent's anti-fraud layer. Sentinel can evaluate fraud risk using settings such as: ```text tracking visitor validation fraud firewall IP sale limits IP fraud detection IP chargeback detection IP whitelist IP blacklist country rejection datacenter/proxy/VPN checks ``` Fraud Detections are the records that preserve detected fraud events and make them usable for review, future prevention, customer support, reporting, and downstream automation. Conceptual relationship: ```text Checkout / payment attempt / sale event ↓ Sentinel Anti Fraud evaluates risk ↓ Fraud firewall or visitor validator may block or flag the event ↓ Fraud Alert or Fraud Detection may be created depending on the event and configuration ↓ Fraud Detection can be reviewed, edited, reported on, or used by future fraud rules ``` Sentinel settings determine whether certain fraud checks are enabled and how aggressively they behave. Fraud Detection records preserve the outcome and context of fraud events. --- ## Sentinel Settings Relevant operations: ```text GetSentinelSettings EditSentinelSettings ``` Use `GetSentinelSettings` to retrieve the current Sentinel Anti Fraud settings. Use `EditSentinelSettings` to update Sentinel settings when the user explicitly wants to change fraud rules. Important: ```text Editing Sentinel settings can affect live checkout behavior. ``` AI/MCP should not edit Sentinel settings casually. Changes can cause purchases to be blocked, fraud alerts to be created, or fraud detections to be generated. --- ## Sentinel Enabled State Sentinel has a top-level `enabled` setting. Important behavior: ```text If Sentinel is disabled, tracking visitor validator and fraud firewall settings are ignored. ``` AI/MCP should check whether Sentinel is enabled before assuming fraud firewall or tracking visitor rules are active. --- ## Tracking Visitor Validator The tracking visitor validator uses RevCent visitor tracking data to determine whether a purchase attempt should be treated as fraud. It can reject based on: ```text missing or non-existing visitor datacenter visitor proxy visitor VPN visitor visitor country ``` Important DNS warning: ```text If tracking visitor validator is enabled, DNS Tracking must be set up for all domains. ``` If DNS Tracking is not set up and tracking visitor validation rejects non-existing visitors, purchases without visitor IDs may be treated as fraud. AI/MCP should not enable strict visitor validation unless the domain/tracking setup is understood. --- ## Fraud Firewall The fraud firewall can prevent fraud purchases based on IP address and related history. It can block sale attempts before creating a sale or attempting payment when IP-based settings match. Fraud firewall capabilities include: ```text IP sale limit IP fraud detection match IP chargeback match IP whitelist IP blacklist ``` Important: ```text Fraud firewall can immediately reject sale attempts without creating a sale or attempting payment. ``` This makes it powerful but consequential. --- ## IP Sale Limit The IP sale limit is used to help prevent card testing and abusive repeat attempts. The schema guidance recommends: ```text max_count = 5 max_time_unit = minutes max_time_value = 30 add_fraud_alerts = true ``` Meaning: ```text If more than 5 sale attempts occur from the same IP within 30 minutes, the fraud firewall can block further attempts from that IP. ``` If `add_fraud_alerts` is enabled, related sales matching the time window can receive fraud alerts. --- ## IP Fraud Detection Matching Sentinel can reject a payment attempt if the IP address matches a previous Fraud Detection. This setting uses historical Fraud Detection data as an anti-fraud signal. Conceptual flow: ```text New payment attempt from IP address ↓ Sentinel checks whether that IP appears in an existing Fraud Detection ↓ If matched and setting is enabled, reject as fraud ``` This is one of the most direct ways Fraud Detection records feed back into Sentinel protection. --- ## IP Chargeback Matching Sentinel can also reject a payment attempt if the IP address matches a previous Chargeback. Conceptual flow: ```text New payment attempt from IP address ↓ Sentinel checks whether that IP appears in an existing Chargeback ↓ If matched and setting is enabled, reject as fraud ``` This helps prevent repeat fraud patterns associated with previous disputes. --- ## Fraud Alert vs Fraud Detection Fraud Alerts and Fraud Detections are related but different. | Concept | Purpose | |---|---| | Fraud Alert | Marks a Sale for manual review or risk attention before creating a Fraud Detection. | | Fraud Detection | A formal fraud detection record attached to the originating source/event. | Relevant operations: ```text AddFraudAlert RemoveFraudAlert CreateFraudDetection GetFraudDetection EditFraudDetection ``` Use `AddFraudAlert` when a Sale needs review but should not yet be formally recorded as fraud. Use `CreateFraudDetection` when the event should be recorded as fraud using an existing source ID. --- ## Fraud Detection Operations | Operation | Purpose | |---|---| | `GetFraudDetections` | Retrieve a paginated list of Fraud Detections for review or lookup. Not for reporting/aggregations. | | `CreateFraudDetection` | Create one Fraud Detection from an existing source ID. | | `GetFraudDetection` | Retrieve full details of one Fraud Detection. | | `EditFraudDetection` | Edit a Fraud Detection, such as marking false positive or adding case/ARN details. | | `SearchFraudDetections` | Search Fraud Detections by search term. | | `AddFraudAlert` | Add a fraud alert to an existing Sale for further review. | | `RemoveFraudAlert` | Remove a fraud alert from an existing Sale. | | `GetSentinelSettings` | Retrieve current Sentinel Anti Fraud settings. | | `EditSentinelSettings` | Edit Sentinel settings when explicitly requested. | | `GetBigQueryTables` | Retrieve BigQuery table schemas for reporting. | | `BigQueryRunQuery` | Run fraud detection reports and analytics. | --- ## Creating a Fraud Detection Use: ```text CreateFraudDetection ``` A Fraud Detection must be created from an existing source ID. `source_id` can be the ID of the originating: ```text API call Sale Transaction PayPal transaction Check Offline payment ``` Required field: ```text source_id ``` Optional fields include: ```text void_sale flag_similar_sale arn event_date fraud_detection_date case_number third_party_integration_id third_party_fraud_detection_id third_party_order_id metadata ``` --- ## CreateFraudDetection Safety `CreateFraudDetection` can have serious effects. Important: ```text void_sale = true can fully refund all entities of the sale and cannot be undone. ``` Only use `void_sale = true` when the user explicitly confirms they want the Sale voided/refunded as part of fraud detection creation. Also be careful with: ```text flag_similar_sale = true ``` This may add fraud alerts to similar Sales and should only be used when that behavior is intended. --- ## Example: Create Fraud Detection From Sale ```json { "source_id": "SSSSSSSSSSSSSSSSSSSS", "event_date": "2026-06-15T14:30:00Z", "fraud_detection_date": "2026-06-15T15:00:00Z", "case_number": "CASE-12345", "metadata": [ { "name": "review_source", "value": "manual_support_review" } ] } ``` Do not include `void_sale = true` unless explicitly confirmed. --- ## Editing a Fraud Detection Use: ```text EditFraudDetection ``` Supported edit fields include: ```text false_positive arn event_date fraud_detection_date case_number third_party_integration_id third_party_fraud_detection_id third_party_order_id ``` The most important review field is: ```text false_positive ``` Use `false_positive = true` when the related event was incorrectly considered fraud. Example: ```json { "fraud_detection_id": "FFFFFFFFFFFFFFFFFFFF", "false_positive": true } ``` --- ## Fraud Detection Details `GetFraudDetection` returns the full details of one Fraud Detection. Important fields can include: ```text id customer campaign_id campaign_name payment_type third_party_shop third_party_integration third_party_fraud_detection_id third_party_order_id details_response event_date fraud_detection_date false_positive origin_api_call metadata related sales related transactions related chargebacks related fraud detections related subscriptions/trials/shipments/taxes/discounts ``` Use the related IDs returned by `GetFraudDetection` to retrieve full related records with their specific Get operations, such as: ```text GetSale GetTransaction GetPayPalTransaction GetOfflinePayment GetChargeback GetShipment GetCustomer ``` --- ## Searching Fraud Detections Use: ```text SearchFraudDetections ``` when the user provides a search term such as: ```text customer email customer name phone address case number metadata value ``` Search results include matching Fraud Detection IDs and highlights. After search, use: ```text GetFraudDetection ``` to retrieve the full record before taking action. --- ## GetFraudDetections Is Not for Reporting Important: ```text Do not use GetFraudDetections for counting, aggregations, metrics, data mining, bulk retrieval, or report generation. ``` `GetFraudDetections` is for paginated review/listing and lookup. For reports, use: ```text GetBigQueryTables BigQueryRunQuery ``` AI/MCP does not need to tell the user it is switching to BigQuery. It should simply use the reporting-appropriate operation. --- ## BigQuery Reporting on Fraud Detections Use BigQuery when the user asks for reporting or analytics such as: ```text How many fraud detections did we have last month? Show fraud detections by campaign. What percentage were false positives? Which payment types have the most fraud detections? Show fraud detections by third-party shop. Trend fraud detections by day. Compare fraud detections to chargebacks. Which customers have multiple fraud detections? ``` Recommended reporting workflow: ```text 1. Use GetBigQueryTables. 2. Locate the fraud detection table and related table schemas. 3. Build a BigQuery Standard SQL query. 4. Use BigQueryRunQuery. 5. If the query errors, fix it and try again. ``` BigQuery table references must use: ```text `revcent.user.` ``` Example table reference: ```text `revcent.user.fraud_detection` ``` The exact table name should be confirmed with `GetBigQueryTables` before running the report. --- ## BigQuery Query Rules When using `BigQueryRunQuery`: ```text Use BigQuery Standard SQL. Surround table references with backticks. Use project ID revcent. Use dataset ID user. Avoid COALESCE. When using TIMESTAMP_SUB, only use INTERVAL in DAY. Optimize queries because query runs are limited to 30 seconds. If a query error occurs, fix the query and run it again. ``` --- ## Example BigQuery Report Patterns These examples are conceptual. AI/MCP should confirm table and field names with `GetBigQueryTables` before running. ### Fraud Detections by Day ```sql SELECT DATE(TIMESTAMP_SECONDS(created_date_unix)) AS fraud_detection_day, COUNT(*) AS fraud_detection_count FROM `revcent.user.fraud_detection` WHERE created_date_unix >= UNIX_SECONDS(TIMESTAMP_SUB(CURRENT_TIMESTAMP(), INTERVAL 30 DAY)) GROUP BY fraud_detection_day ORDER BY fraud_detection_day DESC ``` ### Fraud Detections by Campaign ```sql SELECT campaign_id, campaign_name, COUNT(*) AS fraud_detection_count FROM `revcent.user.fraud_detection` WHERE created_date_unix >= UNIX_SECONDS(TIMESTAMP_SUB(CURRENT_TIMESTAMP(), INTERVAL 30 DAY)) GROUP BY campaign_id, campaign_name ORDER BY fraud_detection_count DESC ``` ### False Positive Rate ```sql SELECT COUNT(*) AS total_fraud_detections, SUM(CASE WHEN false_positive = TRUE THEN 1 ELSE 0 END) AS false_positives, SAFE_DIVIDE(SUM(CASE WHEN false_positive = TRUE THEN 1 ELSE 0 END), COUNT(*)) AS false_positive_rate FROM `revcent.user.fraud_detection` WHERE created_date_unix >= UNIX_SECONDS(TIMESTAMP_SUB(CURRENT_TIMESTAMP(), INTERVAL 30 DAY)) ``` ### Fraud Detections by Payment Type ```sql SELECT payment_type_name, COUNT(*) AS fraud_detection_count FROM `revcent.user.fraud_detection` WHERE created_date_unix >= UNIX_SECONDS(TIMESTAMP_SUB(CURRENT_TIMESTAMP(), INTERVAL 30 DAY)) GROUP BY payment_type_name ORDER BY fraud_detection_count DESC ``` --- ## Fraud Detection Email Templates Fraud Detections can also tie into Email Templates and SMTP Messages. Relevant Email Template triggers include: ```text fraud_alert_create_success sentinel_alert_create_success fraud_detection_create_success ``` Use these when the user wants customer, internal, compliance, or risk team notifications around fraud events. Important distinction: ```text fraud_alert_create_success / sentinel_alert_create_success = alert/review style events fraud_detection_create_success = formal fraud detection created ``` AI/MCP should avoid exposing sensitive fraud/risk details in customer-facing emails unless the user explicitly intends that. --- ## Typical Human-in-the-Loop Workflows ### Review Fraud Detection ```text User asks about a fraud detection ↓ SearchFraudDetections or GetFraudDetection ↓ Retrieve related Sale/Transaction/Customer if needed ↓ Summarize fraud context ↓ Suggest next actions if asked ``` ### Mark False Positive ```text User says a fraud detection was wrong ↓ GetFraudDetection ↓ Confirm correct fraud_detection_id ↓ EditFraudDetection false_positive = true ↓ Create note / Project Note if tied to a Project or operational review ``` ### Create Fraud Detection From Sale ```text User says a Sale should be marked as fraud ↓ GetSale ↓ Confirm Sale and customer context ↓ Ask whether to void sale only if relevant ↓ CreateFraudDetection with source_id = sale_id ↓ Optionally AddFraudAlert to similar sales if explicitly requested ``` ### Report on Fraud Detections ```text User asks for counts, trends, rates, grouped metrics, or analysis ↓ GetBigQueryTables ↓ BigQueryRunQuery ↓ Summarize results ``` --- ## No-Human-in-the-Loop Guidance If an external AI/agent connects without a human in the loop: ```text Only create or edit Fraud Detections when the task payload provides explicit authorization and all required IDs/fields. ``` Do not guess: ```text source_id false_positive void_sale flag_similar_sale case_number third_party integration mapping reporting date range ``` If required information is missing, stop safely and return missing requirements. Never use `void_sale = true` without explicit workflow authorization. --- ## Human-in-the-Loop Confirmation Points Ask for confirmation before: ```text Creating a Fraud Detection Setting void_sale = true Setting flag_similar_sale = true Editing false_positive status Editing Sentinel settings Adding fraud alerts to similar sales Sending fraud-related emails Using sensitive fraud details in customer-facing communication ``` --- ## Project Association and Notes Fraud Detections may be related to a business/store Project through the associated Sale, Campaign, Product, Shop, Customer, or other entities. If working in a Project-based workflow, create concise Project Notes for significant fraud-risk changes. Good Project Note: ```text [YYYY-MM-DD] Reviewed fraud detections for Acme Skincare Changes: - Reviewed 3 Fraud Detections related to Campaign: Acme Skincare Main. - Marked 1 Fraud Detection as false positive. - Created 1 Fraud Detection from Sale SSSSSSSSSSSSSSSSSSSS. - Did not void the Sale. Follow-up: - Monitor fraud detections by campaign using BigQuery report next week. ``` Avoid one note per fraud detection unless each one has a materially different outcome. --- ## Best Practices 1. Use `GetFraudDetection` for individual record review. 2. Use `SearchFraudDetections` when the user provides a search term. 3. Use `GetFraudDetections` for paginated lookup, not reporting. 4. Use BigQuery for counts, trends, grouped metrics, false positive rates, and reporting. 5. Confirm `void_sale = true` explicitly because it cannot be undone. 6. Do not edit Sentinel settings without understanding live checkout impact. 7. Treat `false_positive` edits as important risk-data changes. 8. Use fraud alerts when a Sale needs review before formal fraud detection. 9. Use Fraud Detections as a source of future Sentinel risk blocking, especially IP-based matching. 10. Avoid exposing sensitive fraud logic or risk signals to customers. --- ## Final AI/MCP Instruction Fraud Detections are formal RevCent fraud records that can be created, retrieved, edited, searched, and reported on. Sentinel Anti Fraud uses fraud-related signals and settings to block or flag risky behavior, and historical Fraud Detections can feed future fraud prevention logic. Use Fraud Detection operations for specific records and workflows. Use BigQuery for fraud detection reporting, metrics, trends, and analysis. --- 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.