# RevCent Transactions Overview for AI/MCP

AI/MCP-focused overview for **Transactions** in RevCent.

This document explains what Transactions are, how credit-card captures/refunds are represented, how Transactions differ from PayPal and Offline Payments, and how AI/MCP clients should use `GetTransactions`, `GetTransaction`, `RefundTransaction`, and `SearchTransactions` safely.

---

## Core Concept

A RevCent **Transaction** is specifically a **credit card transaction**.

Transactions represent credit-card payment activity, including:

- attempts to capture funds,
- approved credit-card charges,
- declined credit-card charges,
- held transactions,
- gateway/processor errors,
- fraud-detected attempts,
- credit-card refund transactions,
- partial refunds,
- full refunds,
- offsite/reflected refunds,
- Payment Profile attempts,
- Subscription Renewal attempts,
- Salvage Transaction attempts.

Simple model:

```text
Transaction = credit card payment/refund record
PayPal Transaction = PayPal payment/refund record
Offline Payment = alternate/offline/third-party payment record
```

Do not use `Transaction` as a generic word for every payment type in RevCent.

In RevCent MCP/API context:

```text
Transaction means credit card transaction.
```

---

## Related Operation Links

| Operation | Link | Purpose |
|---|---|---|
| `GetTransactions` | `https://revcent.com/documentation/markdown/mcp/operation/GetTransactions.md` | Retrieve a bounded operational list of credit card Transactions. Not for reporting/aggregation. |
| `GetTransaction` | `https://revcent.com/documentation/markdown/mcp/operation/GetTransaction.md` | Retrieve one specific credit card Transaction by ID. |
| `RefundTransaction` | `https://revcent.com/documentation/markdown/mcp/operation/RefundTransaction.md` | Refund a credit card Transaction by ID, fully or partially. |
| `SearchTransactions` | `https://revcent.com/documentation/markdown/mcp/operation/SearchTransactions.md` | Search credit card Transactions using a full-text search term. |

---

## Related Overview Links

| Overview | Link | Why It Matters |
|---|---|---|
| Sales Overview | `https://revcent.com/documentation/markdown/mcp/operation/OverviewSale.md` | Transactions are commonly related to Sales and initial credit card payment attempts. |
| Product Sales Overview | `https://revcent.com/documentation/markdown/mcp/operation/OverviewProductSale.md` | Product Sale line items may be related to credit card Transactions. |
| Payment Profile Overview | `https://revcent.com/documentation/markdown/mcp/operation/OverviewPaymentProfile.md` | Payment Profiles can create credit card Transactions and gateway attempts. |
| Pending Sale Overview | `https://revcent.com/documentation/markdown/mcp/operation/OverviewPendingSale.md` | Processing Pending Sales can create Transactions. |
| Subscription Overview | `https://revcent.com/documentation/markdown/mcp/operation/OverviewSubscription.md` | Subscription Renewals can create credit card Transactions. |
| Subscription Renewal Overview | `https://revcent.com/documentation/markdown/mcp/operation/OverviewSubscriptionRenewal.md` | Renewal payment attempts can create Transactions. |
| Salvage Transaction Overview | `https://revcent.com/documentation/markdown/mcp/operation/OverviewSalvageTransaction.md` | Salvage recovery attempts can create or relate to Transactions. |
| Process Salvage Transaction | `https://revcent.com/documentation/markdown/mcp/operation/ProcessSalvageTransaction.md` | Processing salvage may create a Transaction when a credit card recovery attempt is made. |
| Tax Overview | `https://revcent.com/documentation/markdown/mcp/operation/OverviewTax.md` | Tax records can be related to Transactions and refunds. |
| Shipping Overview | `https://revcent.com/documentation/markdown/mcp/operation/OverviewShipping.md` | Shipments may be related to Sales or Renewals that have Transactions. |
| Shop Overview | `https://revcent.com/documentation/markdown/mcp/operation/OverviewShop.md` | WooCommerce/User Shop Sales can create credit card Transactions in RevCent. |
| Offline Payment Overview | `https://revcent.com/documentation/markdown/mcp/operation/OverviewOfflinePayment.md` | Offline/alternate payments are not credit card Transactions. |
| PayPal Transaction Overview | `https://revcent.com/documentation/markdown/mcp/operation/OverviewPayPalTransaction.md` | PayPal payment records are separate from credit card Transactions. |
| Sentinel Anti Fraud Overview | `https://revcent.com/documentation/markdown/mcp/operation/OverviewSentinelAntiFraud.md` | Fraud-detected payment attempts can affect Transactions and prevent gateway hits. |
| BigQueryRunQuery | `https://revcent.com/documentation/markdown/mcp/operation/BigQueryRunQuery.md` | Correct method for transaction reporting, metrics, aggregation, and data mining. |

---

## Transaction vs PayPal Transaction vs Offline Payment

RevCent separates payment record types.

| Payment Record Type | Meaning |
|---|---|
| `Transaction` | Credit card transaction. Used for card charges, declines, holds, gateway errors, and card refunds. |
| `PayPal Transaction` | PayPal payment/refund record. |
| `Offline Payment` | Alternate/offline/third-party payment record, such as mapped shop payment methods or supported alternative payment providers. |

AI/MCP rule:

```text
When the user says "transaction" in the context of RevCent operations, assume credit card Transaction unless the user specifically mentions PayPal or Offline Payment.
```

If the user asks about PayPal or alternate payments, use PayPal Transaction or Offline Payment operations instead.

---

## Why Transactions Matter

Transactions are the raw credit-card gateway activity behind much of RevCent's commerce lifecycle.

They help answer:

- Was the card charge approved?
- Was it declined?
- Was the transaction held?
- Did the gateway return an error?
- Was fraud detected?
- Was money captured?
- Was it settled?
- Was it refunded?
- Was the transaction part of an initial Sale?
- Was it part of a Subscription Renewal?
- Was it part of a Payment Profile flow?
- Was it part of a Pending Sale?
- Was it part of a Salvage Transaction?
- Which gateway processed it?
- What card was used?
- What customer was associated?
- What related Sale, Product Sale, Tax, Shipping, Subscription, Renewal, or Refund records exist?

Transactions are essential for support, payment troubleshooting, refund workflows, revenue recovery review, fraud analysis, and reporting.

---

## How Transactions Are Created

Transactions are created when RevCent processes a credit card request.

Common sources:

| Source | Example |
|---|---|
| Initial Sale | Customer buys through API, hosted flow, WooCommerce/User Shop, or RevCent checkout path. |
| Payment Profile | RevCent routes/attempts payment through Payment Profile logic. |
| Pending Sale Processing | `ProcessPendingSale` attempts to process stored cart/payment info. |
| Subscription Renewal | RevCent automatically attempts renewal billing for a subscription. |
| Trial Expiration | A trial converts/expires and payment is attempted. |
| Salvage Transaction Processing | RevCent attempts to recover declined/remaining revenue. |
| RefundTransaction | A credit-card refund is created or recorded. |

Transactions can be approved, declined, held, merchant-error, or fraud-detected depending on the gateway and RevCent result.

---

## Transaction Results and Codes

A Transaction includes both high-level result fields and detailed gateway fields.

### RevCent Payment Result Code

`code` can represent:

| Code | Meaning |
|---:|---|
| `0` | RevCent Error |
| `1` | Success |
| `2` | Decline |
| `3` | Processor Error |
| `4` | Processor Hold |
| `5` | Fraud Detected |

### Transaction Result

`result` can be:

```text
Approved
Declined
Held
Merchant Error
```

Additional boolean fields can include:

| Field | Meaning |
|---|---|
| `approved` | Whether the transaction was approved at the gateway. |
| `declined` | Whether the transaction was declined by the gateway. |
| `held` | Whether the transaction was held by the gateway. |
| `error` | Whether the transaction resulted in an error. |
| `captured` | Whether the transaction was captured at the gateway. |
| `settled` | Whether the transaction has been marked as settled. |
| `void` | Whether the transaction has been fully refunded with zero remaining. |

AI/MCP should inspect both high-level and gateway-level fields before summarizing a transaction.

---

## Gateway Fields

Transactions can include gateway details such as:

| Field | Meaning |
|---|---|
| `gateway_id` | User Gateway ID used for the transaction. |
| `gateway_name` | Gateway name. |
| `gateway_details.user_gateway` | User Gateway object. |
| `gateway_details.site_gateway` | Site Gateway object. |
| `gateway_transaction_id` | Originating gateway transaction ID. |
| `gateway_auth_code` | Authorization code from gateway. |
| `gateway_result_phrase` | Gateway result phrase. |
| `gateway_raw_response` | Stringified raw JSON response from gateway. |
| `gateway_avs_result_code` | AVS result code. |
| `gateway_cvv_result_code` | CVV result code. |
| `gateway_cavv_result_code` | CAVV result code. |

These fields are useful for payment support, gateway reconciliation, fraud/risk review, decline analysis, customer service, dispute review, and Payment Profile troubleshooting.

---

## Card Fields

Transactions can include a related `customer_card` object.

Useful fields:

| Field | Meaning |
|---|---|
| `id` | Customer Card ID. |
| `type` | Card type. |
| `first_6` | First 6 digits / BIN. |
| `last_4` | Last 4 digits. |
| `expiry_date` | Expiration date in MM/YY. |
| `expiry_month` | Expiration month. |
| `expiry_year` | Expiration year. |
| `is_default` | Whether the card is the customer's default payment method. |

Security note:

```text
Transactions do not expose full card numbers.
Use only masked/BIN/last-4 data for support and search.
```

---

## Amount Fields

Transactions include detailed amount fields.

| Field | Meaning |
|---|---|
| `amount` | Transaction amount. |
| `amount_original_total` | Original calculated total when the related item was first created. |
| `amount_total` | Current total after refunds and discounts. |
| `amount_gross` | Money actually transacted; payments minus refunded payments. |
| `amount_net` | Gross amount minus processor fees. |
| `amount_fees` | Calculated fees deducted by processor. |
| `amount_captured` | Captured but not yet settled amount. |
| `amount_settled` | Settled amount. |
| `amount_remaining` | Amount remaining to process, including salvage/trial-related remaining amounts where applicable. |
| `amount_refunded` | Refunded amount, including cancelled trial amounts. |

These fields are important for understanding the financial state of a transaction and related order lifecycle.

For reporting or aggregation across many transactions, use BigQuery.

---

## Transaction Context Flags

Transactions include flags that explain why or how the transaction was created.

| Field | Meaning |
|---|---|
| `sale_initial` | Transaction is part of an initial Sale. |
| `is_payment_profile` | Transaction is associated with a Payment Profile attempt. |
| `is_subscription` | Transaction is associated with a subscription. |
| `is_subscription_renewal` | Transaction is associated with a Subscription Renewal. |
| `is_salvage` | Transaction is a salvage transaction. |
| `has_salvage` | Transaction has an associated Salvage Transaction. |
| `is_refund` | Transaction is a refund transaction. |

These fields help AI/MCP classify the transaction's business purpose.

Example:

```text
sale_initial = true
approved = true
captured = true
is_subscription_renewal = false

This is an approved initial credit card sale transaction.
```

Another example:

```text
is_subscription_renewal = true
declined = true
has_salvage = true

This is a declined subscription renewal attempt with a related salvage recovery opportunity.
```

---

## Related Records

A Transaction can include related record ID arrays.

Related records may include:

| Field | Related Record Type |
|---|---|
| `sales` | Sale IDs |
| `product_sales` | Product Sale IDs |
| `shipping` | Shipping IDs |
| `tax` | Tax IDs |
| `discounts` | Discount IDs |
| `trials` | Trial IDs |
| `subscriptions` | Subscription IDs |
| `subscription_renewals` | Subscription Renewal IDs |
| `invoices` | Invoice IDs |
| `transactions` | Related credit card Transaction IDs |
| `paypal_transactions` | PayPal Transaction IDs |
| `offline_payments` | Offline Payment IDs |
| `check_directs` | Check Direct IDs |
| `salvage_transactions` | Salvage Transaction IDs |
| `pending_refunds` | Pending Refund IDs |
| `chargebacks` | Chargeback IDs |
| `fraud_detections` | Fraud Detection IDs |
| `ai_threads` | AI Thread IDs |
| `ai_assistants` | AI Assistant IDs |
| `api_calls` | API Call IDs |

Use these IDs to retrieve the full lifecycle around a credit card Transaction.

Example:

```text
GetTransaction
 ↓
sales[0]
 ↓
GetSale
 ↓
review full order context
```

---

## Customer Context

Transactions can include a related customer object.

Customer fields may include:

- customer ID,
- first name,
- last name,
- email,
- phone,
- address,
- internal ID,
- blocked/enabled state,
- metadata.

This allows support and AI workflows to connect payment activity to customer history.

Do not expose sensitive information unnecessarily in customer-facing contexts.

---

## Metadata

Transactions and customers can include metadata arrays.

Metadata is useful for:

- attribution,
- campaign tracking,
- external IDs,
- CRM references,
- AI workflow flags,
- support context,
- custom reporting.

Metadata comes as name/value pairs:

```json
{
 "name": "utm_source",
 "value": "google"
}
```

Use BigQuery for metadata reporting across many transactions.

---

## GetTransactions

Use:

```text
GetTransactions
```

to retrieve a bounded operational list of Transactions.

Required input:

| Field | Purpose |
|---|---|
| `date_start` | Date range start as Unix timestamp in seconds. |
| `date_end` | Date range end as Unix timestamp in seconds. |
| `limit` | Number of objects to return. Range 1 to 25. Default 25. |
| `page` | Pagination page. |

Optional filters:

| Filter | Purpose |
|---|---|
| `campaign_filter` | Filter by Campaign IDs. |
| `currency_filter` | Filter by ISO 4217 currency codes. |
| `shop_filter` | Filter by User Shop IDs. |
| `gateway_filter` | Filter by User Gateway IDs. |
| `payment_profile_filter` | Filter by Payment Profile IDs. |
| `method_filter` | Filter by transaction method. |
| `status_filter` | Filter by current status. |
| `result_filter` | Filter by gateway result when created. |
| `metadata_filter` | Filter by metadata name/value pairs. |
| `customer_id` | Filter by related Customer ID. |

Example:

```json
{
 "date_start": 1761955200,
 "date_end": 1764547200,
 "limit": 25,
 "page": 1,
 "customer_id": "CCCCCCCCCCCCCCCCCCCC"
}
```

Use this for bounded operational review, not reporting.

---

## GetTransactions Is Not for Reporting

`GetTransactions` must not be used for:

- counting,
- aggregation,
- metrics,
- data mining,
- bulk retrieval,
- document property search,
- revenue reports,
- decline-rate reports,
- gateway performance reports,
- refund reports.

Use:

```text
BigQueryRunQuery
```

for those use cases.

Correct rule:

```text
Operational bounded list = GetTransactions
Single transaction detail = GetTransaction
Manual/AI lookup by search term = SearchTransactions
Reporting / aggregation / metrics = BigQueryRunQuery
Bulk export = RevCent bulk export utility
```

---

## GetTransaction

Use:

```text
GetTransaction
```

to retrieve one specific Transaction by ID.

Required input:

| Field | Purpose |
|---|---|
| `transaction_id` | 20-character Transaction ID. |

Example:

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

Use `GetTransaction` when:

- transaction ID is known,
- user needs exact payment/gateway details,
- support needs to review a charge or decline,
- AI needs to inspect related lifecycle records,
- refund workflow needs the origin transaction,
- gateway/auth/AVS/CVV response needs review.

---

## SearchTransactions

Use:

```text
SearchTransactions
```

to search previously created Transactions using a full-text search term.

Required input:

| Field | Purpose |
|---|---|
| `search_term` | Single search term or phrase. |

Example:

```json
{
 "search_term": "customer@example.com"
}
```

Search results can include:

| Field | Meaning |
|---|---|
| `item_type` | Always `transaction`. |
| `id` | Transaction ID. |
| `created_date_unix` | Creation timestamp. |
| `first_name` / `last_name` | Customer name. |
| `email` | Customer email. |
| `card_id` | Customer Card ID. |
| `first_6` | Card BIN. |
| `last_4` | Card last 4. |
| `gateway_transaction_id` | Gateway transaction ID. |
| `request_type` | Request type that created the transaction. |
| `request_method` | Request method that created the transaction. |
| `approved` | Whether transaction was approved. |
| `metadata` | Metadata name/value pairs. |
| `url` | Direct RevCent details URL. |
| `highlights` | Fields/values that matched the search. |
| `score` | Search score; higher means a better match. |

Use `SearchTransactions` when the exact Transaction ID is unknown.

Common search terms:

```text
customer email
customer name
phone
last 4
first 6 / BIN
gateway transaction ID
metadata value
external ID
```

After search, use `GetTransaction` to retrieve the exact transaction before taking consequential action.

---

## SearchTransactions Safety Rule

Search results identify possible matches.

They are not authorization to refund, retry, or alter anything.

Correct flow:

```text
SearchTransactions
 ↓
Review possible matches
 ↓
Select correct transaction
 ↓
GetTransaction
 ↓
Confirm customer/order/payment context
 ↓
Take action only if appropriate
```

Do not refund directly from a search result without retrieving and confirming the transaction.

---

## RefundTransaction

Use:

```text
RefundTransaction
```

to refund a credit card Transaction directly by Transaction ID.

Required input:

| Field | Purpose |
|---|---|
| `transaction_id` | 20-character Transaction ID to refund. |

Optional input:

| Field | Purpose |
|---|---|
| `amount` | Amount to refund. If omitted, the entire transaction is refunded. |
| `refunded_offsite` | If true, RevCent records the refund internally without contacting the gateway. Default false. |

---

## Full Refund

If `amount` is omitted:

```text
RefundTransaction refunds the entire transaction amount.
```

Example:

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

Use only when a full refund is intended.

---

## Partial Refund

If `amount` is provided:

```text
RefundTransaction refunds only the specified amount.
```

Example:

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

Use only after confirming:

- refund amount,
- transaction amount,
- existing refunded amount,
- remaining refundable amount,
- customer/order context,
- business authorization.

---

## Offsite / Reflected Refund

`refunded_offsite` allows RevCent to record a refund internally without contacting the gateway.

If:

```json
{
 "refunded_offsite": true
}
```

then:

```text
RevCent marks all entities as having a refund, but does not contact the gateway to return money to the customer.
```

Use cases:

- Rapid Dispute Resolution,
- refund already handled directly at the gateway,
- refund paid by mailed check,
- external/manual refund process,
- accounting needs RevCent to reflect an off-platform refund.

Important:

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

Only use it when the money was already refunded or will be refunded outside RevCent.

Default:

```text
refunded_offsite = false
```

When false, RevCent attempts to refund through the gateway.

---

## RefundTransaction Output

Successful refund output can include:

| Field | Meaning |
|---|---|
| `api_call_id` | API call ID. |
| `api_call_unix` | Unix timestamp when the API call was initiated. |
| `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 as a result of the refund. |
| `result` | Result message. |

After refunding, retrieve related records as needed:

```text
GetTransaction
GetSale
GetPendingRefund
GetProductSale
GetTax
GetShipping
```

depending on the refund workflow.

---

## Refund Safety Workflow

Recommended flow before refunding:

```text
1. SearchTransactions or GetTransaction.
2. Confirm exact Transaction ID.
3. Confirm customer identity.
4. Confirm related Sale/order context.
5. Confirm transaction was approved/captured and refundable.
6. Check amount_refunded and remaining refundable amount.
7. Confirm full vs partial refund.
8. Confirm whether refund should be gateway-level or offsite/reflected.
9. Call RefundTransaction.
10. Retrieve Transaction/Sale/Pending Refund context to verify result.
11. Add notes/metadata or notify customer/internal team where appropriate.
```

---

## RefundTransaction vs Other Refund Operations

`RefundTransaction` refunds a credit-card transaction directly.

Other refund operations may exist for specific item types.

| Refund Need | Likely Operation |
|---|---|
| Refund credit card payment directly | `RefundTransaction` |
| Refund Product Sale line item | `RefundProductSale` |
| Refund Shipping | `RefundShipping` |
| Refund Tax | `RefundTax` |
| Reflect offsite credit card refund | `RefundTransaction` with `refunded_offsite = true` |

For full order refund workflows, AI/MCP should review the Sale/Product Sale/Tax/Shipping context so item-level records remain accurate.

---

## AI Assistant Use Cases

AI Assistants can use Transaction data for:

- failed payment review,
- decline reason classification,
- Payment Profile troubleshooting,
- salvage transaction eligibility review,
- high-value failed transaction escalation,
- refund request summaries,
- gateway error summaries,
- fraud-detected transaction routing,
- AI Memo creation,
- customer support notes,
- BigQuery-driven reporting workflows.

AI Assistants should not blindly refund transactions.

Refunds should require explicit business/user approval.

---

## AI Voice Agent Use Cases

AI Voice Agents may use Transaction context for customer support.

Inbound examples:

- customer asks why a card was charged,
- customer asks why a payment failed,
- customer asks about a refund,
- customer asks to update payment method after a failed transaction,
- customer calls about subscription renewal payment failure.

Outbound examples:

- failed Subscription Renewal recovery,
- Salvage Transaction recovery,
- high-value failed charge follow-up,
- payment update call.

Voice agents should verify customer identity before discussing transaction details.

They should not reveal sensitive gateway details, fraud rules, full card numbers, or internal risk logic.

Refund actions through voice should require clear business rules and explicit authorization.

---

## Transaction Reporting

Use:

```text
BigQueryRunQuery
```

for transaction reporting.

Common reports:

- transaction volume by day,
- approved vs declined transactions,
- approval rate by gateway,
- decline rate by Payment Profile,
- refund amount by day,
- refund rate by campaign,
- transaction revenue by shop,
- card transaction fees,
- net transaction revenue,
- subscription renewal transaction success rate,
- salvage recovery transaction performance,
- fraud-detected transaction attempts,
- card testing activity,
- gateway error rate,
- AVS/CVV result analysis,
- transactions by BIN/last-4 where appropriate,
- WooCommerce credit card transaction performance.

Do not use `GetTransactions` or `SearchTransactions` for these reports.

---

## Example BigQuery Report Ideas

Before running production queries, use `GetBigQueryTables` to confirm exact table and column names.

### Approved vs Declined Transactions by Day

```sql
SELECT
 DATE(TIMESTAMP_SECONDS(created_date_unix)) AS transaction_day,
 result,
 COUNT(*) AS transaction_count,
 SUM(amount) AS transaction_amount
FROM `revcent.user.transaction`
WHERE created_date_unix >= UNIX_SECONDS(TIMESTAMP_SUB(CURRENT_TIMESTAMP(), INTERVAL 30 DAY))
GROUP BY transaction_day, result
ORDER BY transaction_day DESC
```

### Refunds by Day

```sql
SELECT
 DATE(TIMESTAMP_SECONDS(created_date_unix)) AS refund_day,
 iso_currency,
 COUNT(*) AS refund_count,
 SUM(amount) AS refund_amount
FROM `revcent.user.transaction`
WHERE is_refund = TRUE
GROUP BY refund_day, iso_currency
ORDER BY refund_day DESC
```

### Gateway Approval Rate

```sql
SELECT
 gateway_name,
 COUNT(*) AS transaction_count,
 SUM(CASE WHEN approved = TRUE THEN 1 ELSE 0 END) AS approved_count,
 SUM(CASE WHEN declined = TRUE THEN 1 ELSE 0 END) AS declined_count
FROM `revcent.user.transaction`
GROUP BY gateway_name
ORDER BY transaction_count DESC
```

---

## Operational Lookup vs Search vs Reporting

| Need | Correct Operation |
|---|---|
| Retrieve one known Transaction | `GetTransaction` |
| Retrieve recent/bounded operational Transactions | `GetTransactions` |
| Search when ID is unknown | `SearchTransactions` |
| Refund a credit-card Transaction | `RefundTransaction` |
| Generate metrics/reports/aggregation | `BigQueryRunQuery` |
| Bulk export | RevCent bulk export utility |

---

## Best Practices

1. Treat Transactions as credit card records, not generic payments.
2. Use PayPal Transaction operations for PayPal records.
3. Use Offline Payment operations for alternate/offline payment records.
4. Use `SearchTransactions` when the Transaction ID is unknown.
5. Use `GetTransaction` before consequential actions.
6. Use `RefundTransaction` only after confirming transaction, customer, amount, and refund intent.
7. Omit `amount` only when a full refund is intended.
8. Provide `amount` for partial refunds.
9. Use `refunded_offsite = true` only when the refund is being recorded in RevCent but money is not being returned through the gateway.
10. Inspect `is_refund`, `amount_refunded`, and related records before refunding.
11. Use related IDs to retrieve Sale, Product Sale, Tax, Shipping, Subscription, Renewal, Salvage, and Pending Refund context.
12. Use BigQuery for transaction reporting and metrics.
13. Avoid using operational list/search endpoints for aggregation.

---

## Common Mistakes to Avoid

Do not:

- treat PayPal or Offline Payments as credit card Transactions,
- refund from search results without confirming with `GetTransaction`,
- omit `amount` when only a partial refund is intended,
- set `refunded_offsite = true` unless the gateway should not be contacted,
- use `GetTransactions` for reporting or counting,
- use `SearchTransactions` for data mining,
- ignore related Sale/Product Sale/Tax/Shipping records during refund workflows,
- expose sensitive gateway/raw response details to customers,
- assume declined transactions are refundable,
- assume every refund immediately settles,
- ignore Pending Refund IDs returned by refund operations.

---

## AI/MCP Decision Guide

| User Intent | Correct Action |
|---|---|
| Explain Transactions | Describe them as credit card payment/refund records. |
| Find a transaction by customer/card/gateway ID | Use `SearchTransactions`, then `GetTransaction`. |
| Retrieve one transaction | Use `GetTransaction`. |
| Retrieve recent operational transactions | Use `GetTransactions` with date range, limit, page, and filters. |
| Refund a full credit card transaction | Use `RefundTransaction` without `amount` after confirmation. |
| Refund part of a credit card transaction | Use `RefundTransaction` with `amount` after confirmation. |
| Record a refund that occurred outside RevCent/gateway | Use `RefundTransaction` with `refunded_offsite = true` after confirmation. |
| Report transaction metrics | Use `BigQueryRunQuery`. |
| Investigate failed renewal transaction | Get Transaction, then related Subscription Renewal/Subscription/Salvage records. |
| Investigate WooCommerce credit-card payment | Search/Get Transaction, then related Sale and Shop context. |
| Investigate PayPal payment | Use PayPal Transaction operations, not Transaction operations. |
| Investigate alternate payment | Use Offline Payment operations, not Transaction operations. |

---

## Final AI/MCP Instruction

Transactions in RevCent are specifically credit card transactions.

Use `GetTransaction` for one known Transaction, `GetTransactions` for bounded operational retrieval, and `SearchTransactions` when the exact Transaction ID is unknown. Use `RefundTransaction` to refund a credit card Transaction fully or partially. If `amount` is omitted, the transaction is refunded entirely. If `refunded_offsite = true`, RevCent records the refund internally without contacting the gateway.

Do not use Transaction operations for PayPal or Offline Payment records. Do not use `GetTransactions` or `SearchTransactions` for reporting, aggregation, metrics, or data mining. Use `BigQueryRunQuery` for transaction reports and analytics.


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