# RevCent PayPal Accounts Overview This document explains PayPal Accounts in RevCent: what they are, why ecommerce businesses should integrate their PayPal accounts, how RevCent connects PayPal activity into the broader RevCent ecosystem, and how PayPal transactions, refunds, disputes, shipping tracking, campaigns, shops, and reporting fit together. This is a generic overview, not an MCP operation-specific implementation guide. Sources: - RevCent operation schema for `CreatePayPalAccount` - RevCent operation schemas for `GetPayPalAccounts`, `GetPayPalAccount`, `EditPayPalAccount`, and `DeletePayPalAccount` - RevCent operation schema for `GetPayPalTransactions` - RevCent BigQuery guidance through `BigQueryRunQuery` / `GetBigQueryTables` --- # What Is a PayPal Account in RevCent? A PayPal Account in RevCent is a connected PayPal account that allows RevCent to interact with PayPal payment activity. Once a PayPal account is integrated, RevCent can centralize PayPal-related ecommerce activity alongside the rest of the RevCent system. A connected PayPal account can allow RevCent to: ```text Pull PayPal transaction data. Pull PayPal dispute information. Process PayPal refunds. Update shipment tracking information on PayPal transactions. Associate PayPal activity with campaigns. Associate PayPal activity with third-party shops. Connect PayPal activity to customers, sales, product sales, shipping, taxes, discounts, subscriptions, refunds, chargebacks, fraud detections, API calls, metadata, and reporting workflows. ``` The main purpose is to make PayPal activity part of the same RevCent business operating system used for credit cards, offline payments, customers, fulfillment, AI, metadata, notes, reporting, and automation. --- # Why Integrate PayPal Accounts in RevCent? Many ecommerce businesses accept PayPal as a payment option. Without integrating PayPal into RevCent, PayPal activity can become disconnected from the rest of the business. A disconnected PayPal workflow may force a business to switch between: ```text RevCent PayPal dashboard Third-party shop dashboard Fulfillment platform Support tools Reporting exports ``` By integrating PayPal accounts into RevCent, the business can keep PayPal activity connected to: ```text Customer history. Sale records. Campaign attribution. Third-party shop attribution. Shipping records. Refund workflows. Dispute monitoring. BigQuery reporting. AI Assistant workflows. AI Voice Agent workflows. Functions. Notes. Metadata. Internal operations. ``` This gives ecommerce teams better payment visibility, support visibility, and operational control. --- # PayPal Accounts as a Payment Integration Layer A PayPal Account in RevCent is not just a label. The account connection allows RevCent to interact with PayPal through secure credentials and relate PayPal data back to RevCent records. Conceptual flow: ```text User connects PayPal account in RevCent ↓ RevCent securely stores PayPal credentials through a Secure Form ↓ Customer pays with PayPal ↓ RevCent creates or associates PayPal transaction activity ↓ PayPal transaction can be linked to customer, sale, campaign, shop, and related records ↓ RevCent can support refunds, tracking updates, disputes, reporting, and automation ``` --- # Secure Credential Handling Creating or editing a PayPal Account requires sensitive PayPal credentials. RevCent uses a secure form workflow for credential collection. The `CreatePayPalAccount` operation requires use of: ```text CreateSecureForm ``` to create a secure form where the user provides the authentication values. The MCP/API should not ask the user to paste sensitive PayPal credentials directly into chat. Secure flow: ```text 1. MCP creates a secure form with CreateSecureForm. 2. RevCent provides a secure link for the user. 3. User enters PayPal credentials into the secure form. 4. User confirms completion. 5. MCP calls CreatePayPalAccount using secure_form_id. 6. RevCent internally decrypts and associates the credentials. ``` Important: ```text Use secure_form_id instead of passing credentials through AI/MCP chat. ``` This protects sensitive payment-provider credentials. --- # Core PayPal Account Fields PayPal Account operations expose fields such as: | Field | Purpose | |---|---| | `id` | 20-character PayPal Account ID. | | `name` | Internal RevCent name for the PayPal account. Must be unique. | | `description` | Internal description. | | `enabled` | Whether the PayPal Account is active/enabled. | | `paypal_account_email` | Email associated with the PayPal account in PayPal. | | `paypal_account_app_id` | App ID associated with the PayPal account, acquired when credentials are saved. | | `campaign` | Campaign ID associated with the PayPal account. | | `third_party_shop` | Shops/storefronts associated with the PayPal account. | | `transaction_confirmation` | Whether PayPal transactions require delayed confirmation before RevCent marks the sale paid. | | `add_tracking` | Whether RevCent should add shipment tracking information to PayPal transactions. | | `secure_form_id` | Secure form ID used when creating or updating credentials. | --- # Required Fields When Creating a PayPal Account `CreatePayPalAccount` requires: ```text name paypal_account_email campaign ``` In practice, MCP/AI should also usually understand and discuss: ```text enabled description third_party_shop transaction_confirmation add_tracking secure_form_id ``` because these fields affect how PayPal behaves inside RevCent. --- # Campaign Association A PayPal Account has an associated campaign. The campaign applies to PayPal transactions associated with the account. This matters because campaign attribution is central to ecommerce analysis. Examples: ```text PayPal transactions from Brand A campaign. PayPal transactions from a specific website. PayPal transactions from a specific funnel. PayPal transactions from a specific offer or product line. ``` Campaign association helps PayPal transactions participate in RevCent reporting and analysis. Possible reports: ```text PayPal revenue by campaign. PayPal refunds by campaign. PayPal dispute rate by campaign. PayPal transaction volume by campaign. PayPal net revenue by campaign. ``` --- # Third-Party Shop Association A PayPal Account can be associated with one or more third-party shops. The `third_party_shop` array links shop IDs to the PayPal account. This matters because ecommerce businesses may have: ```text Multiple storefronts. Multiple brands. Multiple domains. Multiple third-party carts. Multiple shops using different PayPal accounts. ``` By associating shops with the correct PayPal account, RevCent can correctly link PayPal transactions from those shops to the proper PayPal Account in RevCent. Example: ```text Shop A uses PayPal Account A. Shop B uses PayPal Account B. RevCent links PayPal transactions from each shop to the correct PayPal account. ``` This improves: ```text Attribution. Reporting. Customer support. Refund management. Dispute management. Operational clarity. ``` --- # Transaction Confirmation Setting `transaction_confirmation` controls whether RevCent waits for PayPal transaction confirmation before marking a sale as paid. Recommended default: ```text false ``` When `transaction_confirmation = false`: ```text RevCent creates the sale and marks it as paid immediately upon PayPal purchase. This is recommended. ``` When `transaction_confirmation = true`: ```text RevCent waits for PayPal transaction confirmation before marking the sale paid. This can take 2 to 4 hours because of lag within the PayPal API, not RevCent. ``` This is an important customer experience and fulfillment setting. If confirmation is delayed: ```text Order processing may be delayed. Fulfillment may be delayed. Customer service may see a lag between purchase and paid status. Revenue reporting may lag. ``` For most ecommerce workflows, immediate paid status is usually better unless the business has a specific reason to wait for PayPal confirmation. --- # Shipment Tracking Updates to PayPal `add_tracking` controls whether RevCent adds shipment tracking information to PayPal transactions when shipments are shipped. Recommended default: ```text true ``` When enabled: ```text RevCent can update PayPal transactions with shipment tracking information when shipments are shipped. ``` This is beneficial because PayPal tracking data can help with: ```text Customer transparency. PayPal transaction records. Dispute and claim defense. Delivery evidence. Support workflows. Chargeback/dispute prevention. Operational consistency. ``` For ecommerce businesses shipping physical products, enabling tracking updates is generally valuable. --- # PayPal Transactions in RevCent PayPal transactions are represented in RevCent as PayPal transaction records. A PayPal transaction can include: ```text PayPal transaction ID. PayPal customer ID. PayPal transaction date. PayPal transaction amount. Customer details. Campaign details. PayPal account details. Third-party shop details. Metadata. Amount totals. Fees. Refunded amount. Settled/captured/gross/net values. Related sale/product/shipping/tax/discount/refund/dispute/AI/API records. ``` This means PayPal activity can be analyzed and connected to the same business entities as other payment methods. --- # PayPal Transaction Financial Fields `GetPayPalTransactions` can return financial values such as: ```text amount_original_total amount_total amount_gross amount_net amount_fees amount_captured amount_settled amount_remaining amount_refunded paypal_transaction_amount ``` These fields can help businesses understand: ```text Original order value. Current total after refunds/discounts. Gross PayPal payments. Net amount after fees. PayPal fee impact. Refunded amount. Remaining amount. Settled/captured status. ``` For real reporting, use `BigQueryRunQuery` rather than paginated retrieval. --- # PayPal Refunds Through RevCent A key benefit of connecting PayPal accounts to RevCent is refund capability. The PayPal account schema describes linked PayPal accounts as enabling RevCent to process refunds. This means ecommerce teams can manage PayPal refunds through RevCent workflows rather than handling every PayPal refund manually in the PayPal dashboard. Benefits: ```text Centralized refund operations. Better support workflow. Better API audit trail. Cleaner customer history. Related sale/product/shipping/tax/refund records remain connected. AI Assistants and Functions can participate in refund review workflows when configured. BigQuery can analyze PayPal refund activity with the rest of revenue/refund reporting. ``` This helps RevCent serve as the operational system of record for PayPal payments, not just credit-card payments. --- # PayPal Disputes and Dispute Information The PayPal account schema states that linking PayPal allows RevCent to pull PayPal dispute information. This is useful because PayPal disputes can affect revenue, risk, support, and fulfillment operations. Benefits: ```text Monitor PayPal dispute activity from within RevCent. Connect disputes to customer history. Analyze disputes by campaign/shop/customer/product. Review dispute patterns. Use shipping tracking and customer/order evidence for dispute handling. Trigger internal workflows when disputes appear. ``` PayPal dispute data can be valuable for: ```text Risk teams. Customer support. Chargeback/dispute mitigation teams. Operations managers. AI Assistants that monitor dispute trends. Functions that notify teams or create metadata. ``` --- # PayPal Accounts and Customer History A connected PayPal account helps ensure PayPal purchases are connected to customer records. This allows support teams and AI workflows to understand that a customer may have: ```text Credit card purchases. PayPal purchases. Offline payment purchases. Refunds. Disputes. Shipments. Subscriptions. Notes. Metadata. AI interactions. ``` Centralized customer history is important because customers do not think in terms of internal payment systems. Customers ask: ```text Where is my order? Can I get a refund? Why was I charged? I paid with PayPal. Can you find it? I have a PayPal dispute. What happened? ``` With PayPal integrated, RevCent can provide better context to answer these questions. --- # PayPal Accounts and Third-Party Shops PayPal transactions may originate from third-party shops. Associating PayPal accounts with shops helps ensure RevCent links transactions correctly. This is especially important for: ```text Shopify-style shops. WooCommerce-style shops. Multiple storefronts. Multiple brand domains. Multiple PayPal accounts across brands. ``` Example: ```text A business has two brands: - Brand A uses PayPal Account A. - Brand B uses PayPal Account B. By linking each brand's third-party shop to the correct PayPal account, RevCent can keep PayPal transactions properly attributed. ``` This enables: ```text Revenue reports by shop. PayPal refunds by shop. Dispute rates by shop. Support context by store. Campaign/shop-level analysis. ``` --- # PayPal Accounts and Fulfillment PayPal integration can improve fulfillment workflows because RevCent can add shipment tracking information to PayPal transactions. When `add_tracking = true`, RevCent can update PayPal with tracking information when shipments are shipped. This is useful for: ```text Delivery proof. PayPal transaction visibility. Customer transparency. Dispute prevention. Support visibility. ``` For businesses shipping physical products, PayPal tracking updates are a major operational benefit. --- # PayPal Accounts and AI PayPal data can become useful context for RevCent AI workflows. AI Assistants may use PayPal-related data for: ```text Revenue analysis. Refund trend analysis. Dispute monitoring. Customer support summaries. Campaign/shop performance review. Risk analysis. Fulfillment issue investigation. ``` AI Voice Agents may use PayPal-related context when helping customers on the phone, depending on available system tools and workflow configuration. Examples: ```text Customer paid with PayPal and asks about shipment. AI Assistant analyzes PayPal refund trend by campaign. AI Assistant creates an AI Memo when PayPal disputes spike. Function triggers an internal alert when PayPal refund volume is abnormal. ``` --- # PayPal Accounts and Metadata PayPal transactions can include metadata. Metadata can be used for: ```text Provider-specific labels. External order references. Campaign/funnel attribution. Shop-specific reporting. Support workflow tags. AI outcome tagging. Dispute tracking. Refund reason tagging. ``` Example metadata: ```json { "name": "paypal_workflow", "value": "refund_review" } ``` Metadata can make PayPal activity easier to search, report, and automate. --- # Retrieving PayPal Accounts Use: ```text GetPayPalAccounts ``` to retrieve a paginated list of PayPal Accounts. Use: ```text GetPayPalAccount ``` to retrieve one specific PayPal Account by ID. These operations are useful for: ```text Checking whether PayPal is already integrated. Finding a PayPal Account ID. Reviewing enabled status. Reviewing campaign association. Reviewing third-party shop associations. Reviewing transaction confirmation and tracking settings. ``` --- # Creating PayPal Accounts Use: ```text CreatePayPalAccount ``` to create a new PayPal account connection. Important creation concepts: ```text The name must be unique. The PayPal account email must match the account in PayPal. A campaign is required. Secure credentials should be collected with CreateSecureForm. secure_form_id is used instead of sending credentials through AI/MCP chat. transaction_confirmation should usually be false. add_tracking should usually be true. third_party_shop should be configured when shop-originated PayPal transactions need correct attribution. ``` Required fields: ```text name paypal_account_email campaign ``` --- # Editing PayPal Accounts Use: ```text EditPayPalAccount ``` to update a PayPal Account. Only include fields that should be modified. Examples: ```text Update name. Update description. Enable or disable the account. Update campaign. Update third-party shop associations. Change transaction_confirmation. Change add_tracking. Update PayPal credentials through a new secure_form_id. ``` If changing PayPal credentials, use: ```text secure_form_id ``` from the secure form workflow. Do not pass credentials directly through AI/MCP chat. --- # Enabling and Disabling PayPal Accounts PayPal Accounts have an `enabled` field. Use `enabled` to control whether the PayPal account is active in RevCent. Conceptually: ```text enabled = true → account is active/usable. enabled = false → account is disabled. ``` Use cases for disabling: ```text PayPal credentials are invalid. Account is being replaced. Brand/storefront no longer uses that PayPal account. Testing or migration is in progress. Risk/compliance requires temporary suspension. ``` --- # Deleting PayPal Accounts Use: ```text DeletePayPalAccount ``` to delete a PayPal Account by ID. Deletion should be done carefully because PayPal Accounts may be associated with historical transactions, shops, campaigns, refunds, and disputes. Before deleting, consider whether disabling is more appropriate. --- # Retrieving PayPal Transactions Use: ```text GetPayPalTransactions ``` to retrieve a small paginated list of PayPal transactions. Required fields: ```text date_start date_end limit page ``` Optional filters include: ```text campaign_filter currency_filter shop_filter paypal_account_filter metadata_filter customer_id ``` Use `GetPayPalTransactions` when: ```text The user needs a small list of PayPal transaction records. The user wants to find a specific PayPal transaction. The user wants recent transactions for a customer, PayPal account, campaign, shop, or metadata value. ``` Do not use `GetPayPalTransactions` for reporting, metrics, data mining, aggregations, or bulk retrieval. Use: ```text BigQueryRunQuery ``` for reports and analytics. --- # Reporting on PayPal Activity For PayPal reports, use: ```text BigQueryRunQuery ``` PayPal reporting can include: ```text PayPal revenue by day. PayPal revenue by campaign. PayPal revenue by shop. PayPal revenue by PayPal account. PayPal fees by account. PayPal refunds by campaign/shop/account. PayPal dispute patterns. PayPal net revenue. PayPal gross revenue. PayPal transactions by customer. PayPal transactions by metadata. PayPal transaction volume by brand/store. ``` Use: ```text GetBigQueryTables ``` before writing production SQL to confirm table names and fields. Likely relevant tables include: ```sql `revcent.user.paypal_transaction` `revcent.user.paypal_account` `revcent.user.sale` `revcent.user.customer` `revcent.user.campaign` `revcent.user.third_party_shop` `revcent.user.pending_refund` `revcent.user.api_call` ``` MCP/AI should confirm the exact available tables and fields using `GetBigQueryTables`. --- # BigQuery Example: PayPal Transaction Volume by Account This is a conceptual query. Confirm field names with `GetBigQueryTables`. ```sql SELECT paypal_account, COUNT(*) AS transaction_count, SUM(amount_gross) AS gross_amount, SUM(amount_net) AS net_amount, SUM(amount_fees) AS fees_amount, SUM(amount_refunded) AS refunded_amount FROM `revcent.user.paypal_transaction` WHERE created_at >= TIMESTAMP_SUB(CURRENT_TIMESTAMP(), INTERVAL 30 DAY) GROUP BY paypal_account ORDER BY gross_amount DESC ``` --- # BigQuery Example: PayPal Revenue by Campaign This is a conceptual query. Confirm field names with `GetBigQueryTables`. ```sql SELECT campaign, COUNT(*) AS transaction_count, SUM(amount_gross) AS gross_amount, SUM(amount_net) AS net_amount, SUM(amount_refunded) AS refunded_amount FROM `revcent.user.paypal_transaction` WHERE created_at >= TIMESTAMP_SUB(CURRENT_TIMESTAMP(), INTERVAL 30 DAY) GROUP BY campaign ORDER BY gross_amount DESC ``` --- # BigQuery Example: PayPal Refund Activity This is a conceptual query. Confirm field names with `GetBigQueryTables`. ```sql SELECT DATE(created_at) AS refund_date, COUNT(*) AS transactions_with_refunds, SUM(amount_refunded) AS refunded_amount FROM `revcent.user.paypal_transaction` WHERE created_at >= TIMESTAMP_SUB(CURRENT_TIMESTAMP(), INTERVAL 30 DAY) AND amount_refunded > 0 GROUP BY refund_date ORDER BY refund_date DESC ``` --- # PayPal Accounts vs Credit Card Gateways PayPal Accounts and credit-card gateways solve different payment problems. | Feature | Purpose | |---|---| | PayPal Account | Connects PayPal payment/dispute/refund/tracking activity to RevCent. | | Credit Card Gateway | Processes credit-card payments through merchant/gateway routing. | Both are important for ecommerce businesses that accept multiple payment methods. PayPal integration lets PayPal activity live alongside credit card, offline payment, customer, fulfillment, metadata, and reporting data. --- # PayPal Accounts vs Offline Payments PayPal Accounts are for PayPal integration. Offline Payments are for alternate/external payment methods such as certain BNPL or manual/external payment flows. | Feature | Best For | |---|---| | PayPal Account | Native PayPal transaction, refund, dispute, and tracking integration. | | Offline Payment | Alternate/manual/third-party payment sources outside credit-card gateway flow. | PayPal should be integrated as a PayPal Account, not treated as generic offline payment, when using the PayPal features available in RevCent. --- # Ecommerce Benefits ## More Payment Options Customers often prefer PayPal. Integrating PayPal helps businesses support PayPal as a payment method while preserving RevCent visibility. ## Centralized Revenue View PayPal activity can be analyzed alongside credit card and other payment methods. ## Better Customer Support Support teams can see PayPal payment context in RevCent instead of switching systems. ## Refund Management Refunds can be handled through RevCent workflows rather than only through the PayPal dashboard. ## Dispute Visibility PayPal dispute information can be pulled into RevCent for monitoring and follow-up. ## Fulfillment Tracking RevCent can add tracking information to PayPal transactions when shipments are shipped. ## Campaign and Shop Attribution PayPal transactions can be associated with campaigns and third-party shops. ## AI and Automation AI Assistants, Functions, and reporting workflows can use PayPal data to detect risks, generate memos, trigger alerts, or support customers. ## BigQuery Reporting PayPal transactions can be used in reports for revenue, refunds, fees, disputes, campaigns, shops, customers, and metadata. --- # Best Practices ## Use Secure Forms for Credentials Never ask users to paste PayPal credentials into chat. Use: ```text CreateSecureForm → secure_form_id → CreatePayPalAccount / EditPayPalAccount ``` ## Use Unique and Descriptive Names Good: ```text Brand A PayPal - US Store Brand B PayPal - EU Store Main PayPal - WooCommerce ``` Poor: ```text PayPal Test Main ``` ## Assign the Correct Campaign Because the campaign applies to PayPal transactions associated with the account, choose the correct campaign carefully. ## Link the Correct Third-Party Shops Associate the PayPal account with the shops that actually use it. This prevents misattribution. ## Keep `transaction_confirmation` False Unless Needed Recommended: ```text transaction_confirmation = false ``` Only set true if the business intentionally wants to wait 2 to 4 hours for PayPal API confirmation before marking the sale paid. ## Keep `add_tracking` True for Shippable Businesses Recommended: ```text add_tracking = true ``` This helps PayPal receive shipment tracking details. ## Use BigQuery for Reporting Do not use `GetPayPalTransactions` for metrics, aggregation, data mining, or dashboards. Use: ```text BigQueryRunQuery ``` ## Confirm Schema Before SQL Use: ```text GetBigQueryTables ``` before writing final reports. --- # MCP/AI Guidance When helping a user with PayPal Accounts: 1. Determine whether the user wants to create, retrieve, edit, disable, delete, or report on PayPal data. 2. Use `GetPayPalAccounts` to see existing PayPal accounts. 3. Use `GetPayPalAccount` for one account by ID. 4. Use `CreatePayPalAccount` to create a new PayPal account. 5. Use `EditPayPalAccount` to update account settings or credentials. 6. Use `DeletePayPalAccount` only when deletion is explicitly desired and appropriate. 7. Use `CreateSecureForm` before collecting PayPal credentials. 8. Use `secure_form_id` instead of credentials in the request body. 9. Recommend `transaction_confirmation = false` unless there is a specific business reason. 10. Recommend `add_tracking = true` for businesses shipping physical products. 11. Ensure the correct campaign is selected. 12. Ensure third-party shops are associated correctly. 13. Use `GetPayPalTransactions` only for small paginated retrieval. 14. Use `BigQueryRunQuery` for reporting, metrics, aggregation, dashboards, and data mining. 15. Use PayPal account, campaign, shop, customer, metadata, sale, refund, and dispute context for ecommerce analysis. --- # Summary PayPal Accounts in RevCent allow ecommerce businesses to integrate PayPal activity into the broader RevCent ecosystem. A connected PayPal Account can allow RevCent to: ```text Pull PayPal transaction data. Pull PayPal dispute information. Process PayPal refunds. Update PayPal transactions with shipment tracking information. Associate PayPal activity with campaigns. Associate PayPal activity with third-party shops. Connect PayPal payments to customers, sales, refunds, disputes, fulfillment, metadata, AI, and BigQuery reporting. ``` The biggest benefits are: ```text Centralized payment visibility. Better support workflows. Better refund handling. Better dispute monitoring. Better campaign/shop attribution. Better fulfillment tracking. Better reporting. Better AI and automation context. ``` Used well, PayPal integration makes RevCent a stronger payment, operations, support, and analytics hub for ecommerce businesses that accept PayPal. --- 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.