# RevCent MCP Guide: `RefundTransaction`

AI/MCP-focused guide for the RevCent `RefundTransaction` operation.

This file is intentionally brief. It explains when to use `RefundTransaction`, why it is considered a raw refund method, and when item-specific refund operations are preferred for better reporting and metrics.

---

## Operation Summary

Operation:

```text
RefundTransaction
```

Purpose:

```text
Refund a credit card transaction directly using the Transaction ID.
```

`RefundTransaction` is specifically for refunding a **credit card Transaction**.

It can be used to:

- refund a full credit card transaction,
- refund part of a credit card transaction,
- record an offsite credit card refund inside RevCent without contacting the gateway.

---

## Important Positioning

`RefundTransaction` is a **raw credit card refund method**.

It returns funds against the underlying credit card transaction, but it is not the best operation when the refund is clearly tied to a specific RevCent root item such as:

- a Sale,
- a Product Sale,
- a Shipment,
- Tax,
- a Subscription Renewal.

Use `RefundTransaction` when:

```text
The user simply wants to return funds from a credit card transaction,
and the specific root item is not known, not available, or not mentioned.
```

Do not treat `RefundTransaction` as the default refund method when better item-specific refund context is available.

---

## Reporting / Metrics Warning

`RefundTransaction` is not the recommended refund path if the business wants detailed metrics by item type.

Because it refunds the raw credit card Transaction, it may not give the same clean reporting detail as refunding the specific item that caused the refund.

For better per-item reporting, use item-specific operations:

| Refund Intent | Preferred Operation |
|---|---|
| Void or fully refund an entire Sale | `VoidSale` |
| Refund a specific Product Sale line item | `RefundProductSale` |
| Refund a Shipment / Shipping amount | `RefundShipment` |
| Refund Tax | `RefundTax` |
| Refund a Subscription Renewal | `RefundSubscriptionRenewal` |
| Refund raw credit card funds when item context is unknown | `RefundTransaction` |

Recommended rule:

```text
Known item-specific refund = use the item-specific refund operation.
Unknown/general/raw credit card refund = use RefundTransaction.
```

---

## Why Item-Specific Refunds Are Preferred

Item-specific refund operations preserve cleaner business reporting.

For example:

- `RefundProductSale` helps product/SKU refund metrics.
- `RefundShipment` helps shipping refund metrics.
- `RefundTax` helps tax refund metrics.
- `RefundSubscriptionRenewal` helps renewal refund metrics.
- `VoidSale` helps full-sale refund/void lifecycle reporting.

These operations help RevCent attribute the refund to the correct business object.

That makes future reports more useful, such as:

- refunds by product,
- refunds by shipping method,
- refunds by tax amount,
- refunds by subscription renewal,
- refunds by campaign,
- refunds by WooCommerce/User Shop,
- net revenue by item type,
- refund rate by item type.

Use `RefundTransaction` only when that item-level context is not known or not relevant.

---

## Input Schema

`RefundTransaction` input fields:

| Field | Type | Required | Description |
|---|---:|---:|---|
| `transaction_id` | string | Yes | 20-character credit card Transaction ID. |
| `amount` | number | No | Amount to refund. If omitted, the entire transaction amount is refunded. |
| `refunded_offsite` | boolean | No | If `true`, RevCent marks the refund internally but does not contact the gateway. Default is `false`. |

---

## Full Refund

If `amount` is not provided, RevCent refunds the entire Transaction.

Example:

```json
{
  "transaction_id": "TTTTTTTTTTTTTTTTTTTT"
}
```

Use this only when the user explicitly wants a full refund of the credit card Transaction.

---

## Partial Refund

If `amount` is provided, RevCent refunds only that amount.

Example:

```json
{
  "transaction_id": "TTTTTTTTTTTTTTTTTTTT",
  "amount": 25.00
}
```

Use this when the user wants to refund a specific dollar amount from the Transaction.

---

## Offsite Refund Recording

`refunded_offsite` lets RevCent record the refund internally without contacting the gateway.

Example:

```json
{
  "transaction_id": "TTTTTTTTTTTTTTTTTTTT",
  "amount": 25.00,
  "refunded_offsite": true
}
```

Use `refunded_offsite = true` only when the money was refunded outside RevCent, such as:

- Rapid Dispute Resolution,
- refund issued directly at the gateway,
- mailed check,
- external/manual refund process.

Important:

```text
refunded_offsite = true does not return money through the gateway.
```

It only records the refund state inside RevCent.

---

## Output Schema

A successful response can include:

| Field | Description |
|---|---|
| `api_call_id` | 20-character API call ID. |
| `api_call_unix` | Unix timestamp of the API call. |
| `code` | Response code. `1` indicates success. |
| `amount` | Amount refunded. |
| `origin_campaign_id` | Campaign ID associated with the original Transaction. |
| `origin_customer_id` | Customer ID associated with the original Transaction. |
| `origin_sale_id` | Sale ID associated with the original Transaction, if applicable. |
| `origin_transaction_id` | Original Transaction ID being refunded. |
| `pending_refund` | Pending Refund IDs created by the refund, if applicable. |
| `result` | Result message. |

---

## Recommended Decision Flow

```text
User wants a refund
    ↓
Is the refund clearly tied to a specific item?
    ↓
Yes:
    Use the specific refund operation:
        VoidSale
        RefundProductSale
        RefundShipment
        RefundTax
        RefundSubscriptionRenewal
    ↓
No / root item unknown / user only provided Transaction ID:
    Use RefundTransaction
```

---

## Pre-Refund Checklist

Before calling `RefundTransaction`, AI/MCP should confirm:

- the correct `transaction_id`,
- the customer/order context if available,
- whether the refund is full or partial,
- the exact `amount` if partial,
- whether the refund should be processed through the gateway,
- whether `refunded_offsite` is intentionally needed,
- the user understands this is a raw credit card refund,
- item-specific refund operations were considered if item context is known.

---

## Best Practices

1. Use `RefundTransaction` only for raw credit card refunds.
2. Prefer item-specific refund operations when the refund target is known.
3. Use `VoidSale` for full Sale void/refund flows.
4. Use `RefundProductSale` for product line item refunds.
5. Use `RefundShipment` for shipment/shipping refunds.
6. Use `RefundTax` for tax refunds.
7. Use `RefundSubscriptionRenewal` for subscription renewal refunds.
8. Omit `amount` only when a full Transaction refund is intended.
9. Use `amount` for partial refunds.
10. Use `refunded_offsite = true` only when the refund occurred outside RevCent or should not contact the gateway.

---

## Common Mistakes to Avoid

Do not:

- use `RefundTransaction` as the default refund path when item context is known,
- omit `amount` when the user only wants a partial refund,
- use `refunded_offsite = true` unless the gateway should not be contacted,
- expect `RefundTransaction` to provide the same per-item reporting clarity as item-specific refund operations,
- use `RefundTransaction` for PayPal or Offline Payment refunds,
- ignore `pending_refund` IDs returned by the operation,
- refund without explicit user/business confirmation.

---

## Final AI/MCP Instruction

`RefundTransaction` is a raw credit card refund operation.

Use it when the user simply wants to refund a credit card Transaction and the root item is unknown, unavailable, or not mentioned. If the refund is tied to a specific item, prefer `VoidSale`, `RefundProductSale`, `RefundShipment`, `RefundTax`, or `RefundSubscriptionRenewal` so RevCent can preserve better item-level refund reporting and metrics.


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