# RevCent MCP Guide: `SearchTransactions`

Brief AI/MCP-focused guide for searching RevCent credit card Transactions.

---

## Operation Summary

Operation:

```text
SearchTransactions
```

Purpose:

```text
Search previously created Transactions using a search term.
```

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

Use `SearchTransactions` when the exact Transaction ID is unknown and the user provides a search term such as customer email, customer name, last 4, BIN, gateway transaction ID, or metadata value.

---

## 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` |
| GetTransactions | `https://revcent.com/documentation/markdown/mcp/operation/GetTransactions.md` |
| BigQueryRunQuery | `https://revcent.com/documentation/markdown/mcp/operation/BigQueryRunQuery.md` |

---

## When to Use

Use `SearchTransactions` for targeted lookup when the Transaction ID is unknown.

Good search terms:

- customer email,
- customer name,
- customer phone,
- card last 4,
- card first 6/BIN,
- gateway transaction ID,
- metadata value,
- external ID,
- request type or method.

After finding a likely match:

```text
SearchTransactions
    ↓
Review result/highlights/score
    ↓
GetTransaction
    ↓
Confirm exact transaction before action
```

---

## Input Schema

Required:

| Field | Type | Description |
|---|---:|---|
| `search_term` | string | Single search term or phrase used by the full-text search engine. |

Example:

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

---

## Output Summary

Search results can include:

| Field | Meaning |
|---|---|
| `item_type` | Always `transaction`. |
| `id` | 20-character Transaction ID. |
| `created_date_unix` | Transaction 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 the Transaction was approved. |
| `metadata` | Metadata name/value pairs. |
| `url` | Direct RevCent details URL. |
| `highlights` | Fields and values matched by the search. |
| `score` | Search score. Higher means a better match. |
---

## Customer-Facing AI Verification Warning

This operation can help locate sensitive customer/payment/order context.

If `SearchTransactions` 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 resulting Transaction before providing details or taking action.

Recommended rule:

```text
Do not provide Transaction details to a public-facing visitor based only on the search input they supplied.
```

Search inputs can be guessed, mistyped, shared, or discovered. A search result is only a possible match, not proof that the visitor is authorized.

Safe customer-facing flow:

```text
Visitor provides search input
    ↓
AI runs SearchTransactions
    ↓
AI selects likely result
    ↓
AI runs GetTransaction for the selected Transaction
    ↓
AI verifies the visitor against a secondary value from the GetTransaction response
    ↓
Only after verification:
        provide limited appropriate details
        or take an allowed action
```

Recommended secondary verification values:

| Search Input | Secondary Verification Value |
|---|---|
| Last 4 / BIN / card hint | Customer email from `GetTransaction.customer.email`. |
| Gateway transaction ID | Customer email or phone from `GetTransaction`. |
| Customer name | Email, phone, or another value already on the retrieved customer record. |
| Metadata/external ID | Customer email or phone from the retrieved Transaction. |
| Transaction ID | Customer email from the retrieved Transaction. |

Important:

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

For example, if the visitor searches by last 4, do not reveal matching transaction details until they verify a customer email or other secondary value returned by `GetTransaction`.

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.


---

## Search Safety Rule

Search results are possible matches.

They are not enough to perform consequential actions.

Before refunding or making decisions:

```text
SearchTransactions
    ↓
Select likely result
    ↓
GetTransaction
    ↓
Confirm customer, amount, status, gateway, card, and related records
    ↓
Only then take action
```

Do not refund directly from a search result.

---

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


---

## Correct Use vs Incorrect Use

| User Intent | Correct Action |
|---|---|
| “Find the transaction for this customer email.” | Use `SearchTransactions`, then `GetTransaction`. |
| “Find the transaction with this gateway transaction ID.” | Use `SearchTransactions`, then `GetTransaction`. |
| “Search for this last 4.” | Use `SearchTransactions`, then verify with `GetTransaction`. |
| “How many transactions mention X?” | Use `BigQueryRunQuery`, not `SearchTransactions`. |
| “Analyze transactions by metadata value.” | Use `BigQueryRunQuery`, not `SearchTransactions`. |
| “Find refund rate by customer source.” | Use `BigQueryRunQuery`, not `SearchTransactions`. |

---

## Example: Correct Lookup Flow

```text
User: Find the transaction for gateway transaction ID abc123.
```

Correct:

```text
1. SearchTransactions with search_term = "abc123".
2. Review results.
3. GetTransaction for the correct result ID.
4. Summarize the exact Transaction.
```

---

## Example: Incorrect Reporting Flow

```text
User: Search all transactions with utm_source=google and tell me total revenue.
```

Incorrect:

```text
Use SearchTransactions repeatedly and aggregate results manually.
```

Correct:

```text
Use BigQueryRunQuery.
```

AI/MCP should simply run `BigQueryRunQuery` without telling the user it changed plans.

---

## Best Practices

1. Use specific search terms.
2. Prefer gateway transaction ID, email, or unique metadata values over broad names.
3. Review `highlights` and `score`.
4. Use `GetTransaction` after selecting a result.
5. Do not use search results alone for refunds.
6. Do not use search for reporting or data mining.
7. Verify customer identity with a secondary value from `GetTransaction` before sharing details in customer-facing AI flows.
8. Use `BigQueryRunQuery` for metrics and analysis.

---

## Final AI/MCP Instruction

Use `SearchTransactions` only for targeted full-text lookup of credit card Transactions when the exact Transaction ID is unknown.

In customer-facing AI flows, search results are not proof of authorization. After finding a likely match, use `GetTransaction` and verify the visitor with a secondary value from the retrieved record, such as `customer.email`, before providing details or taking action.

Do not use it for reporting, metrics, aggregation, counting, broad analysis, or data-mining. If the user's intent is analytical, 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.