# RevCent MCP Guide: `GetPayPalTransactions`

Brief AI/MCP-focused guide for retrieving a bounded operational list of RevCent PayPal Transactions.

---

## Operation Summary

Operation:

```text
GetPayPalTransactions
```

Title:

```text
Get PayPal Transactions
```

Purpose:

```text
Return a bounded list of previously created PayPal Transactions.
```

A PayPal Transaction is a RevCent payment record representing PayPal payment activity.

Use `GetPayPalTransactions` for narrow operational retrieval over a known date range and small page/limit.

Do not use it for reporting or analytics.

---

## Related Links

| Guide | Link |
|---|---|
| PayPal Transaction Overview | `https://revcent.com/documentation/markdown/mcp/operation/OverviewPayPalTransaction.md` |
| GetPayPalTransaction | `https://revcent.com/documentation/markdown/mcp/operation/GetPayPalTransaction.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` |
| Pending Refund Overview | `https://revcent.com/documentation/markdown/mcp/operation/OverviewPendingRefund.md` |
| BigQueryRunQuery | `https://revcent.com/documentation/markdown/mcp/operation/BigQueryRunQuery.md` |

---

## When to Use

Use `GetPayPalTransactions` only for bounded operational retrieval.

Good uses:

- show recent PayPal Transactions for a specific customer,
- retrieve PayPal Transactions in a narrow date window,
- review a small operational list for a PayPal account,
- review a small operational list for a shop/campaign,
- locate a RevCent PayPal Transaction ID before using `GetPayPalTransaction`,
- support a customer PayPal-payment question after verification.

Do not use this operation for reporting or analytics.

---

## Input Schema

Required fields:

| Field | Type | Description |
|---|---:|---|
| `date_start` | integer | Date range start as a Unix timestamp in seconds. |
| `date_end` | integer | Date range end as a Unix timestamp in seconds. |
| `limit` | integer | Number of records to return. Range 1 to 25. Default 25. |
| `page` | integer | Pagination page. |

Optional filters:

| Field | Purpose |
|---|---|
| `campaign_filter` | Filter by one or more Campaign IDs. |
| `currency_filter` | Filter by ISO 4217 currency code. |
| `shop_filter` | Filter by one or more User Shop IDs. |
| `paypal_account_filter` | Filter by one or more PayPal Account IDs. |
| `metadata_filter` | Filter by one or more metadata name/value pairs. |
| `customer_id` | Filter to records related to a specific Customer ID. |

Example:

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

---

## Output Summary

`GetPayPalTransactions` can return:

| Field | Meaning |
|---|---|
| `current_count` | Current number of items in this response. |
| `current_page` | Current page. |
| `total_count` | Total number of matching items for the operational query. |
| `total_pages` | Total pages for the operational query. |
| `results` | Array of PayPal Transaction objects. |

PayPal Transaction result objects can include amount fields, PayPal account, PayPal customer ID, PayPal-generated transaction ID/date, customer context, campaign, shop, metadata, and related record IDs.

---

## Important PayPal Fields

| Field | Meaning |
|---|---|
| `paypal_account` | PayPal account associated with the transaction. |
| `paypal_account.id` | 20-character PayPal Account ID. |
| `paypal_account.name` | PayPal account name. |
| `paypal_account.paypal_account_email` | Email associated with the PayPal account. |
| `paypal_customer_id` | Customer ID generated by PayPal. |
| `paypal_transaction_id` | Transaction ID generated by PayPal. |
| `paypal_transaction_amount` | PayPal transaction amount. |
| `paypal_transaction_date` | PayPal-generated transaction date. |
| `paypal_transaction_date_unix` | PayPal-generated transaction date as Unix timestamp. |

---

## Customer-Facing AI Verification Warning

This operation may return sensitive customer, PayPal, order, payment, refund, subscription, trial, shipping, tax, or lifecycle context across multiple PayPal Transactions.

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(s) before providing information, details, or taking action.

Recommended rule:

```text
Do not provide PayPal Transaction details to a public-facing visitor based only on visitor-provided filters or lookup input.
```

Even if the visitor provides a customer name, email, date range, phone number, order reference, PayPal transaction reference, or other lookup detail, that alone should not be treated as authorization to disclose PayPal Transaction information.

Safe customer-facing flow:

```text
Visitor provides lookup/filter input
    ↓
AI uses GetPayPalTransactions for a narrow operational lookup
    ↓
AI identifies likely PayPal Transaction(s)
    ↓
AI uses GetPayPalTransaction for the specific selected PayPal Transaction
    ↓
AI verifies the visitor against a secondary value from the retrieved record
    ↓
Only after verification:
        provide limited appropriate details
        or take an allowed action
```

Recommended secondary verification values:

| Visitor-Provided Input | Secondary Verification Value |
|---|---|
| Date range or recent PayPal transaction request | Customer email from the retrieved PayPal Transaction. |
| Customer name | Email, phone, or another value already on the retrieved customer record. |
| Customer email | Secondary phone, order-related value, or another record-backed verification value where available. |
| Phone number | Customer email from the retrieved PayPal Transaction. |
| PayPal transaction/order context | Customer email or phone from the retrieved PayPal Transaction context. |

Important:

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

For example, if the visitor asks about recent PayPal transactions for a name, order, or date range, verify against the customer email returned by `GetPayPalTransaction` before discussing a specific 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.


---

## Built-In Usage Warning

`GetPayPalTransactions` is for operational retrieval, not analysis.

Correct split:

| Need | Correct Operation |
|---|---|
| Retrieve bounded recent PayPal Transactions | `GetPayPalTransactions` |
| Retrieve one known PayPal Transaction | `GetPayPalTransaction` |
| Search for a PayPal Transaction by term | `SearchPayPalTransactions` |
| Count PayPal Transactions | `BigQueryRunQuery` |
| Calculate PayPal revenue/refunds | `BigQueryRunQuery` |
| Report PayPal account performance | `BigQueryRunQuery` |
| Report PayPal metrics by campaign/shop/customer/product | `BigQueryRunQuery` |

---

## Example: Correct Operational Use

```text
User: Show recent PayPal Transactions for customer C over the last 7 days.
```

Correct:

```text
Use GetPayPalTransactions with customer_id, date_start, date_end, limit, and page.
```

---

## Example: Incorrect Reporting Use

```text
User: How much PayPal revenue did we make last month by shop?
```

Incorrect:

```text
Loop through GetPayPalTransactions pages and calculate manually.
```

Correct:

```text
Use BigQueryRunQuery.
```

AI/MCP should simply run `BigQueryRunQuery` and not explain that it almost used `GetPayPalTransactions`.

---

## Best Practices

1. Use tight date ranges.
2. Use filters whenever possible.
3. Keep `limit` within schema limits.
4. Use `GetPayPalTransaction` for detail review after selecting a PayPal Transaction.
5. Do not loop through pages to build metrics.
6. Do not use this operation for reporting or data mining.
7. Verify customer identity before sharing PayPal Transaction details in customer-facing AI flows.
8. Use `BigQueryRunQuery` for all analytics.

---

## Final AI/MCP Instruction

Use `GetPayPalTransactions` only for bounded operational retrieval of PayPal Transactions.

In customer-facing AI flows, verify the visitor is related to the returned PayPal Transaction(s) using a secondary value from the retrieved record, such as customer email, before providing details or taking action.

Never use it for reporting, metrics, aggregation, counting, broad analysis, data mining, or bulk export. If the user intent is analytical, silently switch to `BigQueryRunQuery`.


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