# RevCent MCP Guide: `GetPendingRefund`

Brief AI/MCP-focused guide for retrieving one RevCent Pending Refund.

---

## Operation Summary

Operation:

```text
GetPendingRefund
```

Title:

```text
Get A Pending Refund
```

Purpose:

```text
Retrieve the details of a pending refund using the Pending Refund ID.
```

A Pending Refund is RevCent's internal refund-tracking record created by refund or void operations.

Simple model:

```text
Refund / Void operation
    ↓
Pending Refund record is created
    ↓
Processor refund happens immediately or later depending on payment type and settlement rules
```

Use `GetPendingRefund` when the exact 20-character Pending Refund ID is known and the user needs to inspect one refund-tracking record.

---

## Related Links

| Guide | Link |
|---|---|
| Pending Refund Overview | `https://revcent.com/documentation/markdown/mcp/operation/OverviewPendingRefund.md` |
| GetPendingRefunds | `https://revcent.com/documentation/markdown/mcp/operation/GetPendingRefunds.md` |
| SearchPendingRefunds | `https://revcent.com/documentation/markdown/mcp/operation/SearchPendingRefunds.md` |
| VoidSale | `https://revcent.com/documentation/markdown/mcp/operation/VoidSale.md` |
| RefundTransaction | `https://revcent.com/documentation/markdown/mcp/operation/RefundTransaction.md` |
| RefundProductSale | `https://revcent.com/documentation/markdown/mcp/operation/RefundProductSale.md` |
| RefundShipment | `https://revcent.com/documentation/markdown/mcp/operation/RefundShipment.md` |
| RefundTax | `https://revcent.com/documentation/markdown/mcp/operation/RefundTax.md` |
| RefundSubscriptionRenewal | `https://revcent.com/documentation/markdown/mcp/operation/RefundSubscriptionRenewal.md` |
| BigQueryRunQuery | `https://revcent.com/documentation/markdown/mcp/operation/BigQueryRunQuery.md` |

---

## When to Use

Use `GetPendingRefund` when:

- the user provides a Pending Refund ID,
- a refund/void operation returned a `pending_refund` ID,
- support needs to check refund status,
- AI/MCP needs to inspect `processed`, `status`, or `refunded_offsite`,
- the user asks whether a refund has processed,
- the user asks why a refund is still pending,
- related Sale, Product Sale, Shipping, Tax, Subscription Renewal, Transaction, PayPal Transaction, Offline Payment, or Check context is needed.

---

## Input Schema

Required:

| Field | Type | Description |
|---|---:|---|
| `pending_refund_id` | string | 20-character Pending Refund ID. |

Example:

```json
{
  "pending_refund_id": "PPPPPPPPPPPPPPPPPPPP"
}
```

---

## Output Summary

`GetPendingRefund` can return:

| Field | Meaning |
|---|---|
| `id` | 20-character Pending Refund ID. |
| `amount` | Refund amount. |
| `created_date_unix` | When the Pending Refund was created. |
| `updated_date_unix` | When the Pending Refund was last updated. |
| `campaign_id` / `campaign_name` | Campaign associated with the refund. |
| `customer` | Customer associated with the refund. |
| `gateway_id` / `gateway_name` | Gateway associated with the refund, if applicable. |
| `iso_currency` | Three-character ISO 4217 currency code. |
| `live_mode` | Whether the item was created in live or test mode. |
| `payment_type` | 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 status of the pending refund. |
| `web_user` | Web user who created the refund, if applicable. |
| `third_party_shop` | Originating User Shop, if applicable. |
| `metadata` | Metadata name/value pairs. |
| Related arrays | Sales, Product Sales, Shipping, Tax, Trials, Subscriptions, Subscription Renewals, Transactions, PayPal Transactions, Offline Payments, Check Directs, Salvage Transactions, Pending Refunds, Chargebacks, Fraud Detections, API Calls, AI records. |

---

## Pending vs Processed

A Pending Refund can be:

```text
processed = false
```

or:

```text
processed = true
```

Meaning:

| Field State | Meaning |
|---|---|
| `processed = false` | Refund record exists, but processor-level refund may not yet be complete. |
| `processed = true` | Refund has been processed at the payment processor, or the offsite refund record has been completed depending on workflow. |
| `refunded_offsite = true` | RevCent is recording a refund handled outside the processor/gateway flow. |

Important:

```text
A Pending Refund does not always mean something is wrong.
```

For credit cards, the original transaction may need to settle before the refund can be processed.

---

## Related Item Arrays

Use related IDs with the correct detail operation:

| Related Array | Detail Operation |
|---|---|
| `sales` | `GetSale` |
| `product_sales` | `GetProductSale` |
| `shipping` | `GetShipment` |
| `tax` | `GetTax` |
| `trials` | `GetTrial` |
| `subscriptions` | `GetSubscription` |
| `subscription_renewals` | `GetSubscriptionRenewal` |
| `transactions` | `GetTransaction` |
| `paypal_transactions` | `GetPayPalTransaction` |
| `offline_payments` | `GetOfflinePayment` |
| `check_directs` | `GetCheckDirect` |
| `salvage_transactions` | `GetSalvageTransaction` |
| `chargebacks` | `GetChargeback` |
| `fraud_detections` | `GetFraudDetection` |
| `api_calls` | `GetAPICall` |

---

## Customer-Facing AI Verification Warning

This operation may expose sensitive customer, order, refund, payment, gateway, subscription, trial, shipping, tax, or lifecycle context.

If this operation is used inside a customer-facing AI flow, such as:

- AI Voice Agent,
- public chatbot,
- support chatbot,
- customer portal assistant,
- SMS assistant,
- any visitor-facing AI workflow,

the AI/MCP client should verify the visitor is actually related to the Pending Refund before providing information, details, or taking action.

Recommended rule:

```text
Do not provide Pending Refund details to a public-facing visitor based only on the Pending Refund ID or a value the visitor supplied.
```

Use a secondary value from the retrieved Pending Refund response to verify identity.

Recommended verification examples:

| Visitor-Provided Input | Secondary Verification Value |
|---|---|
| Pending Refund ID | Customer email from `GetPendingRefund.customer.email`. |
| Customer name | Customer email or phone from the retrieved Pending Refund. |
| Phone number | Customer email from the retrieved Pending Refund. |
| Sale / order / refund context | Customer email from the retrieved Pending Refund or related Sale. |
| Metadata/external ID | Customer email or phone from the retrieved Pending Refund. |

Example safe flow:

```text
Visitor provides refund/search input
    ↓
AI uses SearchPendingRefunds and/or GetPendingRefund
    ↓
AI retrieves the Pending Refund
    ↓
AI asks the visitor to verify a secondary value from the retrieved record, such as customer email
    ↓
Only after verification:
        provide limited appropriate details
        or take an allowed action
```

Important:

```text
The secondary verification value should come from the retrieved RevCent record, not only from the visitor's original search or lookup input.
```

For example, if the visitor provides a Pending Refund ID, verify against the customer email returned by `GetPendingRefund` before discussing refund status.

Do not disclose sensitive details such as:

- payment processor internals,
- gateway details beyond what is appropriate for customer support,
- full payment details,
- unrelated order/subscription/trial details,
- fraud/risk logic,
- full customer details,
- unrelated customer records,
- internal notes not meant for customers,
- other related records unless the visitor is verified and authorized.

For consequential actions, such as additional refunds, sale voids, product/shipping/tax refunds, subscription changes, or customer outreach, require explicit confirmation and follow the relevant operation-specific safety guidance.


---

## Critical Reporting Rule

This Pending Refund lookup/search operation is **not** a reporting tool.

Do not use this operation for:

- counting,
- aggregations,
- metrics,
- reporting,
- data mining,
- bulk retrieval,
- broad analysis,
- document property searches,
- refund volume reports,
- pending-vs-processed refund reports,
- refund timing reports,
- processor settlement reports,
- refund by payment type reports,
- campaign/shop/product/customer refund metrics.

Use:

```text
BigQueryRunQuery
```

for those purposes.

Important AI/MCP behavior:

```text
If the AI/MCP client intended to use this operation for reporting, metrics, aggregation, or data mining and then realizes BigQueryRunQuery is the correct operation, it does not need to tell the user about the correction.

It should simply use BigQueryRunQuery instead.
```

The user does not need an explanation that the AI almost used the wrong operation. The correct behavior is to quietly choose the correct operation.


---

## Correct Use vs Incorrect Use

| User Intent | Correct Action |
|---|---|
| “Show me this Pending Refund ID.” | Use `GetPendingRefund`. |
| “Has this refund processed?” | Use `GetPendingRefund` and inspect `processed`, `status`, and `refunded_offsite`. |
| “Why is my refund still pending?” | Use `GetPendingRefund`, then related payment/refund records if needed. |
| “How many refunds are pending?” | Use `BigQueryRunQuery`, not `GetPendingRefund`. |
| “Show pending refund volume by payment type.” | Use `BigQueryRunQuery`, not `GetPendingRefund`. |

---

## Best Practices

1. Use `GetPendingRefund` only for one known Pending Refund ID.
2. Use `SearchPendingRefunds` when the Pending Refund ID is unknown.
3. Use `GetPendingRefunds` only for bounded operational list retrieval.
4. Inspect `processed`, `status`, and `refunded_offsite` before explaining refund state.
5. Use related IDs to retrieve Sale/Product Sale/Shipping/Tax/Transaction context where needed.
6. Verify customer identity before sharing Pending Refund details in customer-facing AI flows.
7. Use `BigQueryRunQuery` for all reporting and analytics.

---

## Final AI/MCP Instruction

Use `GetPendingRefund` to retrieve one specific Pending Refund by `pending_refund_id`.

In customer-facing AI flows, verify the visitor is related to the Pending Refund using a secondary value from the retrieved record, such as `customer.email`, before providing details or taking action.

Do not use this operation for reporting, metrics, counting, aggregation, data mining, or broad analysis. If the task is reporting-related, silently use `BigQueryRunQuery` instead.


---
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.