# RevCent Pending Refunds Overview This document explains Pending Refunds in RevCent: what they are, why they exist, how they are created by refund and void operations, how they relate to different payment types, how settlement affects credit-card refunds, and how ecommerce businesses should use pending refund data for support, operations, accounting, and reporting. This is a broad overview, not an operation-specific MCP guide. Sources: - RevCent operation schema for `GetPendingRefunds` - RevCent operation schema for `VoidSale` - RevCent operation schema for `RefundTransaction` - RevCent operation schema for `RefundProductSale` - RevCent operation schema for `RefundTax` - RevCent operation schema for `RefundShipment` - RevCent BigQuery guidance from `BigQueryRunQuery` / `GetBigQueryTables` --- # What Is a Pending Refund? A Pending Refund is RevCent's internal refund record created when a refund or void operation needs to return money, mark a refund, or track a refund workflow. A pending refund is a refund in an initial pending state until RevCent is able to directly issue or complete the refund at the payment processor level. Important concept: ```text Pending Refund = refund record created immediately Processor refund = actual refund completed at the payment processor level ``` A pending refund lets RevCent preserve the refund request even when the payment processor cannot immediately accept or complete the refund. --- # Why Pending Refunds Exist Some payment processors do not allow immediate refunds. For example, a credit-card transaction may need to settle with the merchant gateway before a refund can be issued. If the original transaction is still unsettled, the gateway may reject an immediate refund attempt. RevCent solves this by creating a Pending Refund record first. Conceptual flow: ```text Refund or void operation is called ↓ RevCent creates Pending Refund record ↓ If processor can be refunded now, RevCent processes the refund ↓ If processor cannot be refunded yet, Pending Refund remains pending ↓ Once the processor allows the refund, RevCent processes it ↓ Pending Refund is updated as processed ``` This gives RevCent a durable refund queue and audit trail. --- # Pending Refunds Across Payment Types All supported payment types can create Pending Refunds when refunded. Supported payment types include: ```text Credit Card PayPal Offline Payment Check ``` The `GetPendingRefunds` schema exposes the `payment_type` object with these payment type names. This means a business can have Pending Refund records for: ```text Credit card transaction refunds. PayPal transaction refunds. Check payment refunds. Offline payment refunds. ``` Even though the actual processor behavior may differ by payment type, RevCent uses Pending Refunds as the common refund-tracking layer. --- # Credit Card Settlement Behavior Credit card transactions often cannot always be refunded immediately. Some gateways require the original transaction to settle before a refund can be issued. When a credit-card refund or void operation is called: ```text 1. RevCent creates a Pending Refund. 2. If the transaction is already settled and refundable, RevCent can issue the refund at the gateway. 3. If the transaction has not settled yet, the Pending Refund waits. 4. RevCent automatically processes the Pending Refund once the credit card transaction has settled with the merchant gateway. ``` This is the key purpose of Pending Refunds for credit-card payments. Important: ```text A Pending Refund does not necessarily mean something is wrong. It may simply mean RevCent is waiting until the processor allows the refund. ``` --- # Pending Refunds and Processor Timing Different payment processors have different refund rules. Examples: ```text A credit-card gateway may require settlement before refunding. A PayPal refund may be sent through PayPal refund capabilities when available. An offline payment refund may represent the refunding of an associated offline payment record or external payment context. A check refund may represent a refund against a check-direct payment. ``` RevCent creates Pending Refunds to normalize refund tracking across these payment sources. The key idea: ```text Refund request is recorded immediately. Actual payment-processor refund may happen immediately or later. ``` --- # How Refund and Void Operations Create Pending Refunds When calling refund or void operations, RevCent returns the IDs of any Pending Refunds created. The returned field is commonly: ```text pending_refund ``` This is an array of 20-character Pending Refund IDs. Example conceptual output: ```json { "code": 1, "amount": 25.00, "pending_refund": [ "XXXXXXXXXXXXXXXXXXXX" ], "result": "..." } ``` MCP/AI should capture these IDs because they are the refund-tracking records. --- # Operations That Create Pending Refunds Refund and void operations that can create Pending Refunds include: ```text VoidSale RefundTransaction RefundProductSale RefundTax RefundShipment ``` Other refund workflows may also create Pending Refunds when refunding PayPal transactions, checks, offline payments, subscription renewals, or related entities. The important MCP/AI rule: ```text When a refund or void operation returns pending_refund IDs, those IDs represent the created refund tracking records. ``` --- # VoidSale and Pending Refunds `VoidSale` voids a sale in its entirety. Schema behavior: ```text If the sale is pending, VoidSale cancels the pending sale. If the sale is paid, VoidSale fully refunds all associated payments on the non-pending sale. If the sale is paid, all product sales, shipping, and tax are refunded in their entirety. ``` `VoidSale` can return: ```text pending_refund product_sale_refunded shipping_refunded tax_refunded subscription_cancelled trial_cancelled ``` This means a full sale void can create multiple Pending Refunds depending on the sale contents and payment sources. Use `VoidSale` when the business intends to cancel/void/refund the entire sale, not just one line item. --- # RefundTransaction and Pending Refunds `RefundTransaction` refunds a credit-card transaction directly using the transaction ID. Input: ```text transaction_id amount optional refunded_offsite optional ``` If `amount` is omitted: ```text The entire transaction amount is refunded. ``` If `amount` is provided: ```text Only that amount is refunded. ``` `RefundTransaction` returns: ```text pending_refund ``` which contains any Pending Refund IDs created by the refund. This operation is credit-card specific. Use it when the business wants to refund a specific credit-card transaction. --- # RefundProductSale and Pending Refunds `RefundProductSale` refunds a specific product sale using the product sale ID. Input: ```text product_sale_id amount optional refunded_offsite optional ``` If `amount` is omitted: ```text The entire product sale amount is refunded. ``` If `amount` is provided: ```text Only that amount is refunded. ``` `RefundProductSale` returns: ```text pending_refund ``` This operation is often better than direct transaction refunding when the refund should be tied to a product sale line item. Use it for: ```text Refunding one product in an order. Partial product refund. Product-specific customer support refunds. Refunding product value while leaving shipping/tax intact. ``` --- # RefundTax and Pending Refunds `RefundTax` refunds a tax record using the tax ID. Input: ```text tax_id amount optional ``` If `amount` is omitted: ```text The entire tax amount is refunded. ``` If `amount` is provided: ```text Only that amount is refunded. ``` `RefundTax` returns: ```text pending_refund ``` Use it when the business needs to refund tax separately from product or shipping. --- # RefundShipment and Pending Refunds `RefundShipment` refunds a shipment/shipping charge using the shipping ID. Input: ```text shipping_id amount optional ``` If `amount` is omitted: ```text The entire shipping amount is refunded. ``` If `amount` is provided: ```text Only that amount is refunded. ``` `RefundShipment` returns: ```text pending_refund ``` Use it when the business needs to refund shipping without refunding the full sale. --- # Refunds for Offline Payments Offline payments can also create Pending Refunds when refunded. However, offline payments are normally refunded through the entity the offline payment is associated with, such as: ```text VoidSale RefundProductSale RefundTax RefundShipment ``` The offline payment itself represents a payment source or alternate payment record. When refunding an offline-payment-backed sale or associated entity, RevCent can create a Pending Refund with: ```text payment_type.name = Offline Payment ``` This gives RevCent a consistent refund tracking record even when the underlying payment source is external or alternate. --- # Refunds for PayPal Payments PayPal transactions can create Pending Refunds when refunded. A PayPal-related Pending Refund may include: ```text payment_type.name = PayPal paypal_transactions related IDs paypal_account filtering/reporting context ``` PayPal refunds are important because they connect PayPal payment activity to the same RevCent refund tracking layer used by other payment types. This allows the business to review PayPal refunds alongside credit-card, check, and offline payment refunds. --- # Refunds for Checks Check payments can create Pending Refunds when refunded. A check-related Pending Refund may include: ```text payment_type.name = Check check_directs related IDs ``` This allows check refund activity to remain visible in the same pending refund system as other payment methods. --- # Refunded Offsite Some refund operations support: ```text refunded_offsite ``` Examples: ```text RefundTransaction RefundProductSale ``` When `refunded_offsite = true`, RevCent marks the related entities as refunded, but does not contact the gateway to return money to the customer. This is useful when the refund was handled outside RevCent. Examples: ```text Rapid Dispute Resolution. Mailed check. Manual bank adjustment. External processor refund. PayPal dashboard refund handled outside RevCent. Other offsite refund process. ``` Important: ```text refunded_offsite = true means RevCent is recording the refund for system/reporting consistency, not sending money through the gateway. ``` A Pending Refund can indicate: ```text refunded_offsite = true ``` so MCP/AI should not assume every Pending Refund resulted in a processor-level API refund. --- # Pending Refund Fields `GetPendingRefunds` can return fields such as: | Field | Meaning | |---|---| | `id` | Pending Refund ID. | | `created_date_unix` | When the Pending Refund was created. | | `updated_date_unix` | When the Pending Refund was last updated. | | `amount` | Refund amount. | | `campaign_id` | Campaign associated with the refund. | | `campaign_name` | Campaign name. | | `customer` | Customer associated with the refund. | | `gateway_id` | Gateway associated with the refund, if applicable. | | `gateway_name` | Gateway name associated with the refund, if applicable. | | `iso_currency` | Three-character ISO 4217 currency code. | | `live_mode` | Whether the refund is live or test mode. | | `payment_type` | Payment type object: Credit Card, PayPal, Offline Payment, or Check. | | `processed` | Whether the refund has been processed at the payment processor. | | `refund_transaction_id` | Credit-card transaction ID being refunded, if applicable. | | `success_transaction_id` | Credit-card refund transaction ID, if applicable. | | `refunded_offsite` | Whether the refund was processed offsite and will not be sent to the processor. | | `status` | Current pending refund status. | | `web_user` | Web user who created the refund, if applicable. | | `third_party_shop` | Originating shop, if applicable. | | `metadata` | Metadata on the pending refund. | --- # Related Items on Pending Refunds Pending Refund records may include related item IDs. Related arrays can include: ```text sales product_sales shipping tax discounts trials subscriptions subscription_renewals invoices license_keys transactions ai_threads ai_assistants paypal_transactions offline_payments check_directs salvage_transactions pending_refunds chargebacks fraud_detections api_calls ``` These relationships help MCP/AI trace a refund back to the original business context. Examples: ```text sales → retrieve sale with GetSale. product_sales → retrieve product sale with GetProductSale. shipping → retrieve shipment with GetShipment. tax → retrieve tax with GetTax. transactions → retrieve credit-card transaction with GetTransaction. paypal_transactions → retrieve PayPal transaction context when available. offline_payments → retrieve offline payment with GetOfflinePayment. check_directs → retrieve check with GetCheckDirect. api_calls → retrieve API call with GetAPICall. ``` --- # Pending Refund Lifecycle A typical Pending Refund lifecycle looks like this: ```text 1. User, API, AI Assistant, AI Voice Agent, Function, or web user requests a refund/void. 2. Refund or void operation is called. 3. RevCent creates one or more Pending Refund records. 4. The refund record starts in a pending/unprocessed state. 5. If the payment processor can be refunded immediately, RevCent processes it. 6. If the payment processor cannot refund yet, RevCent waits. 7. For credit cards, RevCent automatically processes the pending refund once the original transaction has settled with the merchant gateway. 8. The Pending Refund updates to processed when the processor-level refund is completed. 9. Related records remain linked for customer support, accounting, reporting, and audit. ``` --- # Pending vs Processed A Pending Refund can have: ```text processed = false ``` or: ```text processed = true ``` Meaning: | processed | Meaning | |---:|---| | `false` | Refund exists but has not yet been processed at the payment processor. | | `true` | Refund has been processed at the payment processor, or the offsite refund record has been completed depending on workflow. | MCP/AI should check: ```text status processed refunded_offsite success_transaction_id ``` before explaining whether a refund actually left through the processor. --- # Pending Refund Status `GetPendingRefunds` exposes a `status` field. Status should be treated as the current refund state. The exact status values may depend on processor/payment type/workflow. MCP/AI should use the returned status value rather than guessing. Examples of questions status can answer: ```text Is the refund still pending? Was it processed? Was it recorded as offsite? Did it fail or require attention? ``` --- # Why Pending Refunds Are Useful Pending Refunds are useful because they provide a consistent refund tracking layer. Without Pending Refunds: ```text A refund request might fail immediately if the processor cannot refund yet. The user might need to remember to retry later. Support may not know whether a refund was requested. Refund reporting may miss delayed processor actions. ``` With Pending Refunds: ```text Refund request is recorded immediately. RevCent can process the refund when allowed. Customer support can see that the refund was initiated. Finance can audit refund timing. AI/automation can monitor unprocessed refunds. BigQuery can report pending refund volume. ``` --- # Ecommerce Benefits ## Customer Support Visibility Support teams can tell whether a refund was requested even if the processor has not yet completed it. Useful support questions: ```text Has the customer's refund been requested? Is the refund waiting for settlement? Was it refunded offsite? Was it processed at the gateway? Which sale/product/shipping/tax record was refunded? ``` --- ## Accounting and Finance Pending Refunds help finance teams understand timing differences between: ```text Refund requested. Refund processed. Refund settled/confirmed by processor. Refund recorded offsite. ``` This helps reconcile money movement with support activity and RevCent records. --- ## Payment Processor Reality Payment processors may enforce timing rules. Pending Refunds let RevCent handle those realities without losing the refund intent. Key example: ```text Credit card transaction not settled yet → RevCent creates Pending Refund → RevCent automatically processes refund after settlement. ``` --- ## Refund Audit Trail Pending Refunds provide an audit trail for who or what initiated a refund. Pending Refunds can show: ```text Customer. Campaign. Payment type. Gateway. Web user. Third-party shop. Metadata. Related sale/product/shipping/tax/transaction/API call IDs. ``` This is valuable for: ```text Support audits. Finance audits. Risk reviews. Refund-abuse detection. Chargeback mitigation. Customer service performance analysis. ``` --- ## AI and Automation Pending Refunds can be used by AI workflows and automation. Examples: ```text AI Assistant reviews pending refunds older than X days. AI Memo is created if refund backlog spikes. Function notifies support if processor refunds are still unprocessed. AI Voice Agent can explain refund status to a customer when appropriate. Metadata can tag refunds by reason or support workflow. BigQuery reports refund delays by payment type. ``` --- # Retrieval: GetPendingRefunds Use: ```text GetPendingRefunds ``` to retrieve a small paginated list of Pending Refunds. Required inputs: ```text date_start date_end limit page ``` Optional filters: ```text campaign_filter currency_filter gateway_filter payment_type_filter paypal_account_filter metadata_filter customer_id ``` Use `GetPendingRefunds` when: ```text The user wants a small list of pending refunds. The user wants recent pending refunds in a timeframe. The user wants to filter pending refunds by customer, payment type, campaign, gateway, PayPal account, currency, or metadata. The user needs to find a pending refund ID. ``` Do not use `GetPendingRefunds` for metrics, reporting, aggregation, counting, data mining, dashboards, or bulk retrieval. Use: ```text BigQueryRunQuery ``` for those use cases. --- # Reporting and Metrics For reporting, metrics, counts, aggregation, dashboards, or data mining, MCP/AI should use: ```text BigQueryRunQuery ``` not `GetPendingRefunds`. Relevant reporting questions include: ```text How many pending refunds are unprocessed? How many refunds are waiting by payment type? How much refund volume is pending? How long do credit-card refunds take to process after creation? Refund volume by campaign. Refund volume by gateway. Refund volume by PayPal account. Refund volume by third-party shop. Refund volume by customer. Refunds processed offsite. Refunds tied to AI Assistants or API calls. Pending refund backlog over time. ``` Use: ```text GetBigQueryTables ``` before writing production SQL. Expected table reference pattern: ```sql `revcent.user.pending_refund` ``` MCP/AI should confirm the exact pending refund table schema with `GetBigQueryTables` before production queries. --- # Example BigQuery: Unprocessed Pending Refunds Schema-dependent example. Confirm fields with `GetBigQueryTables` before production use. ```sql SELECT payment_type, COUNT(*) AS refund_count, SUM(amount) AS total_amount FROM `revcent.user.pending_refund` WHERE created_at >= TIMESTAMP_SUB(CURRENT_TIMESTAMP(), INTERVAL 30 DAY) AND processed = false GROUP BY payment_type ORDER BY total_amount DESC ``` --- # Example BigQuery: Refund Volume by Campaign Schema-dependent example. Confirm fields with `GetBigQueryTables`. ```sql SELECT campaign, COUNT(*) AS refund_count, SUM(amount) AS total_refund_amount FROM `revcent.user.pending_refund` WHERE created_at >= TIMESTAMP_SUB(CURRENT_TIMESTAMP(), INTERVAL 30 DAY) GROUP BY campaign ORDER BY total_refund_amount DESC ``` --- # Example BigQuery: Offsite Refunds Schema-dependent example. Confirm fields with `GetBigQueryTables`. ```sql SELECT DATE(created_at) AS refund_date, COUNT(*) AS offsite_refund_count, SUM(amount) AS offsite_refund_amount FROM `revcent.user.pending_refund` WHERE created_at >= TIMESTAMP_SUB(CURRENT_TIMESTAMP(), INTERVAL 30 DAY) AND refunded_offsite = true GROUP BY refund_date ORDER BY refund_date DESC ``` --- # Example BigQuery: Refund Processing Lag Schema-dependent example. Confirm timestamp fields with `GetBigQueryTables`. ```sql SELECT payment_type, COUNT(*) AS processed_refunds, AVG(TIMESTAMP_DIFF(updated_at, created_at, HOUR)) AS avg_hours_to_process FROM `revcent.user.pending_refund` WHERE created_at >= TIMESTAMP_SUB(CURRENT_TIMESTAMP(), INTERVAL 30 DAY) AND processed = true GROUP BY payment_type ORDER BY avg_hours_to_process DESC ``` This can help identify whether certain gateways, payment types, or workflows experience refund delays. --- # When to Use Refund Operations vs Pending Refunds Use refund/void operations when the user wants to initiate a refund. Examples: ```text RefundTransaction RefundProductSale RefundTax RefundShipment VoidSale ``` Use Pending Refund retrieval/reporting when the user wants to review the refund record after initiation. Examples: ```text Show recent pending refunds. Check whether this refund was processed. Find refunds for this customer. Report unprocessed refunds by payment type. Audit refunds created by a support user. ``` --- # Operational Best Practices ## Capture Returned Pending Refund IDs When a refund or void operation returns: ```text pending_refund ``` MCP/AI should capture and report those IDs. Example: ```text Refund requested successfully. Pending Refund created: XXXXXXXXXXXXXXXXXXXX. ``` ## Explain Processor Timing If the refund is still pending, explain that processor timing may be involved. For credit cards: ```text RevCent automatically processes the Pending Refund once the original credit-card transaction has settled with the merchant gateway. ``` ## Do Not Promise Immediate Money Movement A successful refund operation does not always mean the processor-level refund completed instantly. Correct: ```text The refund request was created and a Pending Refund exists. It will be processed when the payment processor allows the refund. ``` Incorrect: ```text The money has definitely already been returned. ``` ## Use Offsite Refunds Carefully If `refunded_offsite = true`, RevCent records the refund but does not send money through the gateway. Use only when the refund was truly handled outside RevCent. ## Use the Right Refund Level Choose the operation that matches the business action: | Goal | Operation | |---|---| | Refund whole paid sale | `VoidSale` | | Refund one credit-card transaction directly | `RefundTransaction` | | Refund product line item | `RefundProductSale` | | Refund tax | `RefundTax` | | Refund shipping | `RefundShipment` | ## Use BigQuery for Reporting Do not use `GetPendingRefunds` for metrics or data mining. Use `BigQueryRunQuery`. --- # Customer Communication Guidance Pending Refunds can be confusing to customers. If a refund is pending, customer-facing explanations should be clear: ```text The refund has been initiated in RevCent. Some processors do not allow the refund to be issued until the original payment has settled. RevCent will process the refund automatically once the processor allows it. ``` Do not overpromise: ```text The refund is already back in your bank account. ``` Better: ```text The refund has been initiated. The time it takes to appear on your statement depends on the payment processor and bank after processing. ``` --- # MCP/AI Guidance When helping a user with Pending Refunds: 1. Understand whether the user wants to initiate a refund or inspect/report on existing refunds. 2. Use refund/void operations to initiate refunds. 3. Capture returned `pending_refund` IDs. 4. Explain that Pending Refunds are refund records created immediately. 5. Explain that processor-level completion may happen immediately or later. 6. For credit cards, explain that RevCent automatically processes pending refunds once the original transaction settles with the merchant gateway. 7. Use `GetPendingRefunds` only for small paginated retrieval. 8. Use `BigQueryRunQuery` for metrics, reporting, aggregation, dashboards, or data mining. 9. Check `processed`, `status`, `refunded_offsite`, and `success_transaction_id` before explaining completion. 10. Use related item IDs to retrieve the associated sale/product/shipment/tax/transaction/PayPal/offline/check context. 11. Avoid promising that money has already moved unless the record shows the refund was processed. 12. Distinguish between refund requested, pending refund created, processor refund processed, and offsite refund recorded. --- # Common Mistakes ## Mistake: Assuming Pending Means Failed Wrong: ```text The refund is pending, so something went wrong. ``` Correct: ```text Pending may simply mean RevCent is waiting until the processor allows the refund, such as after credit-card settlement. ``` --- ## Mistake: Promising Immediate Refund Completion Wrong: ```text The customer has definitely already received the money. ``` Correct: ```text The refund has been requested/created. Check processed/status/success transaction fields to know whether processor-level refund completed. ``` --- ## Mistake: Using GetPendingRefunds for Reporting Wrong: ```text Page through GetPendingRefunds to calculate monthly refund totals. ``` Correct: ```text Use BigQueryRunQuery against the pending refund data. ``` --- ## Mistake: Refunding the Wrong Level Wrong: ```text Void the entire sale when only shipping should be refunded. ``` Correct: ```text Use RefundShipment for shipping, RefundTax for tax, RefundProductSale for product line item, RefundTransaction for direct transaction refund, or VoidSale for full-sale void/refund. ``` --- ## Mistake: Misunderstanding Refunded Offsite Wrong: ```text refunded_offsite = true sent the refund to the payment processor. ``` Correct: ```text refunded_offsite = true records the refund in RevCent but does not contact the gateway to return money. ``` --- # Summary A Pending Refund is RevCent's refund-tracking record created when a refund or void operation is called. All supported payment types can create Pending Refunds when refunded: ```text Credit Card PayPal Offline Payment Check ``` Refund and void operations such as: ```text VoidSale RefundTransaction RefundProductSale RefundTax RefundShipment ``` can return: ```text pending_refund ``` which contains the IDs of created Pending Refund records. Pending Refunds exist because some payment processors do not allow immediate refunds. For credit-card transactions, RevCent automatically processes a Pending Refund once the original credit-card transaction has settled with the merchant gateway. Use Pending Refunds to track: ```text Refund requested. Refund amount. Payment type. Customer. Campaign. Gateway or PayPal account context. Offsite refund status. Processor-level processing status. Related sale/product/shipping/tax/transaction/offline/check/PayPal records. ``` Use: ```text GetPendingRefunds ``` for small paginated retrieval. Use: ```text BigQueryRunQuery ``` for reporting, metrics, aggregations, dashboards, and data mining. Used correctly, Pending Refunds give ecommerce businesses a reliable refund audit trail and help bridge the timing gap between a refund request and processor-level refund completion. --- 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.