# RevCent MCP Guide: `GetTransactions`

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

---

## Operation Summary

Operation:

```text
GetTransactions
```

Purpose:

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

In RevCent, a `Transaction` is specifically a **credit card transaction**.

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

---

## Related Links

| Guide | Link |
|---|---|
| Transactions Overview | `https://revcent.com/documentation/markdown/mcp/operation/OverviewTransaction.md` |
| GetTransaction | `https://revcent.com/documentation/markdown/mcp/operation/GetTransaction.md` |
| SearchTransactions | `https://revcent.com/documentation/markdown/mcp/operation/SearchTransactions.md` |
| BigQueryRunQuery | `https://revcent.com/documentation/markdown/mcp/operation/BigQueryRunQuery.md` |

---

## When to Use

Use `GetTransactions` only for bounded operational retrieval.

Good uses:

- show recent credit card Transactions for a specific customer,
- retrieve Transactions in a narrow date window,
- review recent Transactions for a campaign/shop/gateway,
- locate a Transaction before using `GetTransaction`,
- operational support review with a strict date range, page, and limit.

Do not use this operation for reporting or analytics.

---

## Input Schema

Required fields:

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

Common optional filters:

| Field | 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. |
| `metadata_filter` | Filter by metadata name/value pairs. |
| `customer_id` | Filter by a specific Customer ID. |

Example:

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

## Customer-Facing AI Verification Warning

This operation may return sensitive customer/payment/order context across multiple Transactions.

If `GetTransactions` 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 Transaction(s) before providing details or taking action.

Recommended rule:

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

Even if the visitor provides a customer name, email, date range, last 4, or other lookup detail, that alone should not be treated as authorization to disclose Transaction information.

Safe customer-facing flow:

```text
Visitor provides lookup/filter input
    ↓
AI uses GetTransactions for a narrow operational lookup
    ↓
AI identifies likely Transaction(s)
    ↓
AI uses GetTransaction for the specific selected Transaction when needed
    ↓
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 transaction request | Customer email from the retrieved 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. |
| Last 4 / card hint | Customer email from the retrieved Transaction. |
| Shop/order context | Customer email or phone from the retrieved Transaction/Sale 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 for recent Transactions for a name or date range, verify against the customer email returned by `GetTransaction` or the retrieved Transaction details before discussing a specific Transaction.

Do not disclose sensitive details such as:

- full gateway responses,
- fraud/risk logic,
- full card data,
- unrelated customer details,
- internal notes not meant for customers,
- other related records unless the visitor is verified and authorized.

For consequential actions, such as refunds, cancellations, payment recovery, or subscription changes, require stronger confirmation and follow the relevant operation-specific safety guidance.


---

## Critical Reporting Rule

These Transaction lookup/search operations are **not** reporting tools.

Do not use this operation for:

- counting,
- aggregations,
- metrics,
- reporting,
- data mining,
- bulk retrieval,
- broad analysis,
- document property searches,
- revenue summaries,
- approval/decline rate reports,
- refund reports,
- gateway performance reports.

Use:

```text
BigQueryRunQuery
```

for those purposes.

Important AI/MCP behavior:

```text
If the AI/MCP client planned 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

`GetTransactions` is for operational retrieval, not analysis.

Correct split:

| Need | Correct Operation |
|---|---|
| Retrieve bounded recent Transactions | `GetTransactions` |
| Retrieve one known Transaction | `GetTransaction` |
| Search for a Transaction by term | `SearchTransactions` |
| Count Transactions | `BigQueryRunQuery` |
| Calculate approval/decline rate | `BigQueryRunQuery` |
| Report refunds/revenue/gateway performance | `BigQueryRunQuery` |
| Analyze by campaign/shop/gateway/payment profile | `BigQueryRunQuery` |

---

## Example: Correct Operational Use

```text
User: Show the most recent credit card transactions for customer C over the last 7 days.
```

Correct:

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

---

## Example: Incorrect Use

```text
User: What was my approval rate last month by gateway?
```

Incorrect:

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

Correct:

```text
Use BigQueryRunQuery.
```

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

---

## Best Practices

1. Use tight date ranges.
2. Use filters whenever possible.
3. Keep `limit` small and within schema limits.
4. Use `GetTransaction` for detail review after selecting a 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 Transaction details in customer-facing AI flows.
8. Use `BigQueryRunQuery` for all analytics.

---

## Final AI/MCP Instruction

Use `GetTransactions` only for bounded operational retrieval of credit card Transactions.

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