# RevCent MCP Guide: `GetPayPalTransaction`

Brief AI/MCP-focused guide for retrieving one RevCent PayPal Transaction.

---

## Operation Summary

Operation:

```text
GetPayPalTransaction
```

Title:

```text
Get A PayPal Transaction
```

Purpose:

```text
Retrieve the details of a specific PayPal Transaction.
```

A PayPal Transaction is a RevCent payment record representing PayPal payment activity associated with a customer, Sale, Product Sale, Shipment, Tax, Trial, Subscription, Subscription Renewal, Pending Refund, or other related commerce item.

Use `GetPayPalTransaction` when the exact 20-character RevCent PayPal Transaction ID is known and the user needs to inspect one PayPal payment record.

---

## Related Links

| Guide | Link |
|---|---|
| PayPal Transaction Overview | `https://revcent.com/documentation/markdown/mcp/operation/OverviewPayPalTransaction.md` |
| GetPayPalTransactions | `https://revcent.com/documentation/markdown/mcp/operation/GetPayPalTransactions.md` |
| SearchPayPalTransactions | `https://revcent.com/documentation/markdown/mcp/operation/SearchPayPalTransactions.md` |
| Offline Payment Overview | `https://revcent.com/documentation/markdown/mcp/operation/OverviewOfflinePayment.md` |
| Transaction Overview | `https://revcent.com/documentation/markdown/mcp/operation/OverviewTransaction.md` |
| Sale Overview | `https://revcent.com/documentation/markdown/mcp/operation/OverviewSale.md` |
| GetSale | `https://revcent.com/documentation/markdown/mcp/operation/GetSale.md` |
| Pending Refund Overview | `https://revcent.com/documentation/markdown/mcp/operation/OverviewPendingRefund.md` |
| GetPendingRefund | `https://revcent.com/documentation/markdown/mcp/operation/GetPendingRefund.md` |
| BigQueryRunQuery | `https://revcent.com/documentation/markdown/mcp/operation/BigQueryRunQuery.md` |

---

## When to Use

Use `GetPayPalTransaction` when:

- the user provides a RevCent PayPal Transaction ID,
- a related record contains a `paypal_transactions` array,
- the user needs to inspect a specific PayPal payment,
- support needs PayPal transaction amount/date/context,
- the user asks about a PayPal transaction ID generated by PayPal,
- AI/MCP needs PayPal account, customer, amount, refund, shop, or metadata context,
- related Sale/Product Sale/Shipping/Tax/Subscription/Trial/Pending Refund context must be traced.

---

## Input Schema

Required:

| Field | Type | Description |
|---|---:|---|
| `paypal_transaction_id` | string | 20-character RevCent PayPal Transaction ID. |

Example:

```json
{
  "paypal_transaction_id": "PPPPPPPPPPPPPPPPPPPP"
}
```

---

## Output Summary

`GetPayPalTransaction` can return:

| Field | Meaning |
|---|---|
| `id` | 20-character RevCent PayPal Transaction ID. |
| `created_date_unix` | Creation timestamp. |
| `amount_original_total` | Original calculated total when the item was first created. |
| `amount_total` | Current total after refunds and discounts. |
| `amount_gross` | Money actually transacted. |
| `amount_net` | Gross amount minus fees. |
| `amount_fees` | Calculated processor fees. |
| `amount_captured` | Captured but not yet settled amount. |
| `amount_settled` | Settled amount. |
| `amount_remaining` | Remaining amount to be processed. |
| `amount_refunded` | Current refunded amount. |
| `campaign_id` / `campaign_name` | Campaign associated with the transaction. |
| `customer` | Customer associated with the transaction. |
| `paypal_account` | PayPal Account ID, name, and PayPal account email. |
| `paypal_customer_id` | Customer ID generated by PayPal. |
| `paypal_transaction_amount` | PayPal transaction amount. |
| `paypal_transaction_date` | PayPal-generated transaction date in ISO8601 format. |
| `paypal_transaction_date_unix` | PayPal-generated transaction date as Unix timestamp. |
| `paypal_transaction_id` | Transaction ID generated by PayPal. |
| `third_party_shop` | Originating User Shop, if applicable. |
| `metadata` | Metadata name/value pairs. |

---

## 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` |
| `pending_refunds` | `GetPendingRefund` |
| `chargebacks` | `GetChargeback` |
| `fraud_detections` | `GetFraudDetection` |
| `api_calls` | `GetAPICall` |
| `ai_threads` | `GetAIThread` |
| `ai_assistants` | `GetAIAssistant` |

---

## PayPal Transaction vs Credit Card Transaction

Do not confuse PayPal Transactions with credit card Transactions.

| Item | Meaning |
|---|---|
| `PayPal Transaction` | PayPal payment record. Use `GetPayPalTransaction`. |
| `Transaction` | Credit-card transaction record. Use `GetTransaction`. |
| `Offline Payment` | Alternate/offline payment record. Use `GetOfflinePayment`. |
| `Pending Refund` | Refund tracking record. Use `GetPendingRefund`. |

Use the operation that matches the payment type.

---

## Customer-Facing AI Verification Warning

This operation may expose sensitive customer, PayPal, order, payment, refund, 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 PayPal Transaction before providing information, details, or taking action.

Recommended rule:

```text
Do not provide PayPal Transaction details to a public-facing visitor based only on the PayPal Transaction ID, PayPal-generated transaction ID, or a value the visitor supplied.
```

Use a secondary value from the retrieved PayPal Transaction response to verify identity.

Recommended verification examples:

| Visitor-Provided Input | Secondary Verification Value |
|---|---|
| RevCent PayPal Transaction ID | Customer email from `GetPayPalTransaction.customer.email`. |
| PayPal-generated transaction ID | Customer email or phone from the retrieved PayPal Transaction. |
| PayPal account/payment context | Customer email from the retrieved PayPal Transaction. |
| Customer name | Customer email or phone from the retrieved PayPal Transaction. |
| Sale/order context | Customer email from the retrieved PayPal Transaction or related Sale. |
| Metadata/external ID | Customer email or phone from the retrieved PayPal Transaction. |

Example safe flow:

```text
Visitor provides PayPal transaction/search input
    ↓
AI uses SearchPayPalTransactions and/or GetPayPalTransaction
    ↓
AI retrieves the PayPal Transaction
    ↓
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 PayPal-generated transaction ID, verify against the customer email returned by `GetPayPalTransaction` before discussing the transaction.

Do not disclose sensitive details such as:

- PayPal account internals,
- unrelated PayPal transaction details,
- payment processor internals 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 refunds, sale voids, subscription changes, shipment changes, dispute handling, or customer outreach, require explicit confirmation and follow the relevant operation-specific safety guidance.


---

## Critical Reporting Rule

This PayPal Transaction 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,
- PayPal revenue reports,
- PayPal refund reports,
- PayPal dispute reports,
- PayPal account performance reports,
- campaign/shop/customer PayPal metrics,
- payment-method comparison reports.

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 PayPal Transaction ID.” | Use `GetPayPalTransaction`. |
| “What PayPal-generated transaction ID is linked to this record?” | Use `GetPayPalTransaction`. |
| “What Sale is related to this PayPal Transaction?” | Use `GetPayPalTransaction`, then `GetSale` using related IDs. |
| “Has this PayPal transaction been refunded?” | Use `GetPayPalTransaction`, inspect amount fields and related Pending Refunds. |
| “How much PayPal revenue did we make last month?” | Use `BigQueryRunQuery`, not `GetPayPalTransaction`. |
| “Show PayPal performance by shop/campaign.” | Use `BigQueryRunQuery`, not `GetPayPalTransaction`. |

---

## Best Practices

1. Use `GetPayPalTransaction` only for one known RevCent PayPal Transaction ID.
2. Use `SearchPayPalTransactions` when the PayPal Transaction ID is unknown.
3. Use `GetPayPalTransactions` only for bounded operational list retrieval.
4. Use related IDs to retrieve Sale/Product Sale/Shipping/Tax/Subscription/Trial context where needed.
5. Inspect `amount_refunded` and related `pending_refunds` before discussing refund state.
6. Do not confuse PayPal Transactions with credit-card Transactions.
7. Verify customer identity before sharing PayPal Transaction details in customer-facing AI flows.
8. Use `BigQueryRunQuery` for all reporting and analytics.

---

## Final AI/MCP Instruction

Use `GetPayPalTransaction` to retrieve one specific PayPal Transaction by `paypal_transaction_id`.

In customer-facing AI flows, verify the visitor is related to the PayPal Transaction 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.