# RevCent MCP Operation: `GetOfflinePayment` This document explains how MCP/AI clients should use the `GetOfflinePayment` operation in RevCent. `GetOfflinePayment` retrieves the details of a specific offline payment using the offline payment ID. Before working with offline payments, MCP/AI should read the Offline Payment overview: https://revcent.com/documentation/markdown/mcp/operation/OverviewOfflinePayment.md The overview explains what offline payments are, how they work, supported third-party offline payment integrations, and how offline payments fit into RevCent's ecommerce/payment ecosystem. Sources: - RevCent operation schema for `GetOfflinePayment` - RevCent operation schema for `GetOfflinePayments` - RevCent operation guidance for `BigQueryRunQuery` - RevCent Offline Payment Overview: https://revcent.com/documentation/markdown/mcp/operation/OverviewOfflinePayment.md --- ## Operation Summary `GetOfflinePayment` retrieves one specific offline payment. Use this operation when: ```text The offline_payment_id is already known. The user wants details of one offline payment. The MCP needs to inspect the payment amount/status/customer/provider context. The MCP needs related item IDs before deciding how to refund or investigate the payment. ``` Do not use `GetOfflinePayment` for: ```text Reporting across many offline payments. Counting offline payments. Aggregations. Metrics. Data mining. Bulk retrieval. Provider-level analytics. Campaign/shop/payment source reports. ``` For those use cases, use: ```text BigQueryRunQuery ``` --- # Required Input | Field | Type | Required | Description | |---|---:|---:|---| | `offline_payment_id` | string | Yes | 20-character offline payment ID. | Example request: ```json { "offline_payment_id": "XXXXXXXXXXXXXXXXXXXX" } ``` --- # What the Response Contains `GetOfflinePayment` returns a detailed offline payment object. Important fields include: | Field | Description | |---|---| | `id` | 20-character offline payment ID. | | `created_date_unix` | When the offline payment was created. | | `updated_date_unix` | When the offline payment was last updated. | | `amount` | Offline payment amount. | | `status` | Offline payment status. | | `campaign_id` | Associated campaign ID. | | `campaign_name` | Associated campaign name. | | `customer` | Customer object associated with the offline payment. | | `third_party_integration` | Third-party payment integration context, if applicable. | | `third_party_shop` | Originating user shop/storefront, if applicable. | | `metadata` | Metadata name/value pairs attached to the offline payment. | The response can also include arrays of related item IDs, such as: ```text sales product_sales shipping tax discounts trials subscriptions subscription_renewals invoices license_keys transactions paypal_transactions offline_payments check_directs salvage_transactions pending_refunds chargebacks fraud_detections api_calls ``` These related IDs are important because many actions, including refunds, happen through the associated entity rather than through the offline payment record itself. --- # Understanding Offline Payments An offline payment is a RevCent payment record for a payment that was completed outside the normal RevCent credit-card gateway transaction flow. Examples include: ```text Affirm Afterpay Amazon Pay Klarna Sezzle Manual/external payment methods Third-party shop payment sources Other alternate payment providers ``` Offline payments allow RevCent to preserve payment context even when the payment was not processed as a standard RevCent credit-card transaction. The offline payment record can still be associated with: ```text Customer Sale Product sale Shipping Tax Discount Invoice Third-party shop Third-party integration Metadata ``` If subscription-related IDs appear in an offline payment response, treat them as contextual relationships only. Offline payments are not subscription-capable payment methods; only credit card sales/payments are subscription capable. --- # Third-Party Integration Context If the offline payment is associated with a third-party provider, the response may include: ```text third_party_integration.id third_party_integration.name third_party_integration.third_party.id third_party_integration.third_party.name ``` This identifies which configured third-party provider/account is associated with the payment. Example conceptual object: ```json { "third_party_integration": { "id": "USER_THIRD_PARTY_INTEGRATION_ID", "name": "Klarna Main Account", "third_party": { "id": "SITE_THIRD_PARTY_INTEGRATION_ID", "name": "Klarna" } } } ``` MCP/AI should inspect this field when the user asks: ```text Which provider was used? Was this a Klarna/Sezzle/Affirm/Afterpay/Amazon Pay payment? Which third-party integration is connected to this payment? Can this payment be managed/refunded through RevCent? ``` --- --- # Offline Payments Are Not Compatible With Subscription Billing Offline payments should not be used as the payment method for subscription billing. Important: ```text Subscriptions and subscription billing are not compatible with offline payments. Only credit card sales/payments are subscription capable in RevCent. ``` This means MCP/AI should not recommend or attempt to configure an offline payment method as the billing source for a recurring subscription, subscription renewal, or trial expiration billing flow. Offline payments are useful for: ```text One-time alternate payment records. Third-party payment sources such as Affirm, Afterpay, Amazon Pay, Klarna, and Sezzle. Manual or external payment flows. Third-party shop payment context. Customer/order/payment visibility. Offline payment retrieval, support, reconciliation, and reporting. ``` But subscription billing requires credit card payment capability. --- ## How to Interpret Subscription-Related IDs Offline payment schemas may expose related arrays such as: ```text subscriptions subscription_renewals ``` These relationships should not be interpreted to mean that offline payments are a valid recurring billing method. They may provide relationship/context visibility, but they do not make offline payments subscription-capable. MCP/AI should explain this clearly when a user asks whether Klarna, Affirm, Sezzle, Afterpay, Amazon Pay, or another offline payment source can be used for subscription renewals. Correct guidance: ```text Offline payments can represent alternate/third-party payment sources. Credit card payments are required for subscription-capable billing. ``` # Refunding Offline Payments Important: ```text Do not refund an offline payment by trying to refund the offline payment record itself. ``` If the user wants to refund an offline payment, the refund should be performed against the associated entity that the offline payment is connected to. Relevant refund/void operations include: ```text VoidSale RefundProductSale RefundTax RefundShipment ``` Examples: ```text If the offline payment is associated with a sale and the entire sale should be voided/refunded, use VoidSale when appropriate. If a specific product sale should be refunded, use RefundProductSale. If tax should be refunded, use RefundTax. If shipping should be refunded, use RefundShipment with the shipping_id. If partially refunding, provide amount; if amount is omitted, the shipment will be refunded entirely. ``` MCP/AI should use the related item arrays returned by `GetOfflinePayment` to identify what entity or entities are associated with the offline payment. For example: ```text offline_payment.sales[] → retrieve the sale and consider VoidSale if appropriate. offline_payment.product_sales[] → retrieve the product sale and consider RefundProductSale. offline_payment.tax[] → retrieve the tax and consider RefundTax. offline_payment.shipping[] → retrieve the shipping/shipment and consider RefundShipment. ``` --- # Why Refunds Are Done Through Associated Entities An offline payment may represent the payment source, but the actual refundable business object may be: ```text Sale Product sale Tax Shipping ``` Refunding through the associated entity keeps RevCent's records aligned with: ```text Sale totals Product sale totals Shipping totals Tax totals Customer history Revenue reporting Third-party payment provider refund actions ``` For supported third-party offline payment integrations, RevCent can communicate with the provider so the user does not need to log into the third-party provider dashboard to perform the refund separately. --- # Recommended Refund Workflow When the user asks to refund an offline payment: ```text 1. Call GetOfflinePayment with the offline_payment_id. 2. Review amount, status, customer, third_party_integration, metadata, and related item IDs. 3. Identify the associated refundable entity: - sale - product_sale - tax - shipping 4. Retrieve the associated entity details if needed. 5. Choose the correct refund/void operation: - VoidSale - RefundProductSale - RefundTax - RefundShipment 6. Do not try to refund the offline payment record directly. 7. If a supported third-party integration is involved, RevCent can manage the provider-side refund through the associated refund operation. ``` --- # Related Record Retrieval `GetOfflinePayment` often returns related item IDs. MCP/AI should retrieve related details when needed. Examples: | Related array | Retrieve with | |---|---| | `sales` | `GetSale` | | `product_sales` | `GetProductSale` | | `shipping` | `GetShipment` | | `tax` | `GetTax` | | `subscriptions` | `GetSubscription` | | `subscription_renewals` | `GetSubscriptionRenewal` | | `pending_refunds` | `GetPendingRefund` | | `chargebacks` | `GetChargeback` | | `fraud_detections` | `GetFraudDetection` | Use the related IDs to understand the full business context. --- --- # Customer-Facing AI Verification Warning Offline payment records can expose sensitive customer, order, payment, provider, shop, refund, subscription-context, shipment, tax, and lifecycle information. If `GetOfflinePayment` is used inside a customer-facing AI flow, such as: ```text AI Voice Agent Public chatbot Customer portal assistant SMS assistant Any visitor-facing AI workflow ``` MCP/AI should verify that the visitor is actually related to the offline payment before providing information, details, or taking action. Important: ```text Do not provide offline payment details to a public-facing visitor based only on the offline_payment_id or a value the visitor supplied. ``` A visitor-provided value can be guessed, mistyped, shared, or discovered. It should not be treated as proof of authorization. Recommended customer-facing flow: ```text Visitor provides offline payment / order / provider / search input ↓ MCP/AI retrieves the offline payment with GetOfflinePayment ↓ MCP/AI reviews the customer object returned in the GetOfflinePayment response ↓ MCP/AI verifies the visitor using a secondary value from the retrieved RevCent record ↓ Only after verification: provide limited appropriate details or take an allowed action ``` Recommended secondary verification values include: | Visitor-Provided Input | Secondary Verification Value | |---|---| | `offline_payment_id` | Customer email from the `GetOfflinePayment.customer.email` response. | | Customer name | Customer email or phone from the retrieved offline payment. | | Phone number | Customer email from the retrieved offline payment. | | Provider name, such as Klarna or Affirm | Customer email or phone from the retrieved offline payment. | | Shop/order context | Customer email from the retrieved offline payment or related Sale. | | Metadata/external ID | Customer email or phone from the retrieved offline payment. | The secondary verification value should come from the retrieved RevCent record, not only from the visitor's original input. Example: ```text If the visitor provides an offline_payment_id, MCP/AI should retrieve the offline payment and verify the visitor against the customer email returned by GetOfflinePayment before discussing payment details. ``` Do not disclose sensitive details such as: ```text Full customer address Provider-side/internal payment details Third-party integration configuration Unrelated Sale/Product Sale/Subscription/Trial details Refund workflow details beyond what is appropriate for support Fraud/risk logic Internal notes or metadata not meant for customers Other related records unless the visitor is verified and authorized ``` For consequential actions, such as refunds, sale voids, product refunds, tax refunds, shipment refunds, subscription changes, or customer account changes, require explicit confirmation and use the appropriate operation-specific safety guidance. # Common Use Cases ## View One Offline Payment User asks: ```text Show me this offline payment. ``` Use: ```text GetOfflinePayment ``` ## Determine Provider User asks: ```text Was this paid through Klarna? ``` Use: ```text GetOfflinePayment ``` Then inspect: ```text third_party_integration ``` ## Investigate Customer Payment User asks: ```text What offline payment did this customer use for this order? ``` Use: ```text GetOfflinePayment ``` Then inspect: ```text customer sales product_sales third_party_integration third_party_shop metadata ``` ## Prepare a Refund User asks: ```text Refund this offline payment. ``` Use: ```text GetOfflinePayment ``` Then refund the associated entity using: ```text VoidSale RefundProductSale RefundTax RefundShipment ``` Do not refund the offline payment object itself. --- # GetOfflinePayment vs GetOfflinePayments vs BigQueryRunQuery | Goal | Use | |---|---| | Retrieve one known offline payment by ID | `GetOfflinePayment` | | Retrieve a filtered paginated list of offline payments | `GetOfflinePayments` | | Count offline payments | `BigQueryRunQuery` | | Sum offline payment volume | `BigQueryRunQuery` | | Report by provider/campaign/shop/customer/metadata | `BigQueryRunQuery` | | Data mining / analytics | `BigQueryRunQuery` | | Bulk retrieval/export-style analysis | `BigQueryRunQuery` or bulk export utility guidance | --- # Validation Checklist Before calling `GetOfflinePayment`: 1. `offline_payment_id` is known. 2. `offline_payment_id` is 20 characters. 3. The user wants details for one offline payment. 4. If the user wants reporting/metrics/data mining, use `BigQueryRunQuery` instead. 5. If the user wants to refund, plan to refund the associated entity, not the offline payment record. 6. Review related IDs to identify the correct sale/product/tax/shipping entity. 7. Review `third_party_integration` when provider context matters. 8. Review `metadata` when external references or custom business context may matter. 9. If the user asks about subscription billing, explain that offline payments are not subscription compatible; only credit card sales/payments are subscription capable. --- # Key Takeaways ```text GetOfflinePayment retrieves one offline payment by ID. ``` ```text Offline payments represent external/manual/alternate payment sources such as Affirm, Afterpay, Amazon Pay, Klarna, Sezzle, and third-party shop payment methods. ``` ```text Offline payment records can include amount, status, customer, campaign, shop, metadata, third-party integration, and related item IDs. ``` ```text To refund an offline payment, refund the associated entity using VoidSale, RefundProductSale, RefundTax, or RefundShipment. ``` ```text Offline payments are not compatible with subscription billing; only credit card sales/payments are subscription capable. ``` ```text Do not use GetOfflinePayment/GetOfflinePayments for reporting or analytics; use BigQueryRunQuery. ``` ```text MCP/AI should read the Offline Payment overview before working deeply with offline payment workflows: https://revcent.com/documentation/markdown/mcp/operation/OverviewOfflinePayment.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.