# RevCent MCP Guide: `SearchChargebacks`

AI/MCP-focused guide for searching RevCent Chargebacks.

---

## Related Documentation

| Guide | Link | Why It Matters |
|---|---|---|
| Chargeback Overview | `https://revcent.com/documentation/markdown/mcp/operation/OverviewChargeback.md` | Broad explanation of Chargebacks, dispute lifecycle, representment context, related records, and best practices. |
| GetChargeback | `https://revcent.com/documentation/markdown/mcp/operation/GetChargeback.md` | Retrieve one specific Chargeback by ID. |
| GetChargebacks | `https://revcent.com/documentation/markdown/mcp/operation/GetChargebacks.md` | Retrieve a bounded operational list of Chargebacks. Not for reporting/metrics. |
| SearchChargebacks | `https://revcent.com/documentation/markdown/mcp/operation/SearchChargebacks.md` | Search Chargebacks when the Chargeback ID is unknown. |
| GetCustomer | `https://revcent.com/documentation/markdown/mcp/operation/GetCustomer.md` | Retrieve the Customer related to the Chargeback. |
| GetSale | `https://revcent.com/documentation/markdown/mcp/operation/GetSale.md` | Retrieve related Sale context. |
| GetTransaction | `https://revcent.com/documentation/markdown/mcp/operation/GetTransaction.md` | Retrieve related credit-card Transaction context. |
| BigQueryRunQuery | `https://revcent.com/documentation/markdown/mcp/operation/BigQueryRunQuery.md` | Correct operation for Chargeback reporting, metrics, aggregation, and data mining. |


---

## Operation Summary

Operation:

```text
SearchChargebacks
```

Title:

```text
Search Chargebacks
```

Purpose:

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

Use `SearchChargebacks` when the exact Chargeback ID is unknown and the user provides a search term such as customer email, customer name, card last 4, card first 6/BIN, gateway transaction ID, metadata value, case-related context, or another searchable phrase.

---

## When to Use

Use `SearchChargebacks` for targeted lookup when the Chargeback ID is unknown.

Good search terms may include:

- customer email,
- customer first/last name,
- card ID,
- first 6/BIN,
- last 4,
- gateway transaction ID,
- metadata value,
- external/customer/internal identifier.

After finding a likely match:

```text
SearchChargebacks
    ↓
Review result/highlights/score
    ↓
GetChargeback
    ↓
Confirm exact Chargeback before action
```

---

## Input Schema

| Field | Type | Required | Description |
|---|---:|---:|---|
| `search_term` | string | Yes | 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 `chargeback`. |
| `id` | 20-character Chargeback ID. |
| `created_date_unix` | Chargeback creation timestamp. |
| `first_name` / `last_name` | Customer name. |
| `email` | Customer email. |
| `card_id` | 20-character Customer Card ID. |
| `first_6` | First 6 digits of the credit card used. |
| `last_4` | Last 4 digits of the credit card used. |
| `gateway_transaction_id` | Originating gateway transaction ID. |
| `metadata` | Metadata name/value pairs. |
| `url` | Direct RevCent chargeback details URL. |
| `highlights` | Search-highlighted fields and values. |
| `score` | Search score; higher is a better match. |

---

## Search Safety Rule

Search results are possible matches.

They are not enough to perform consequential actions.

Before discussing chargeback details, refunding, changing customer status, modifying subscriptions, escalating support, or making dispute-related decisions:

```text
SearchChargebacks
    ↓
Select likely result
    ↓
GetChargeback
    ↓
Confirm customer, amount, case/gateway context, and related records
    ↓
Only then take action if appropriate
```

Do not take chargeback, customer, refund, subscription, or account actions directly from a search result.

---

## Customer-Facing AI Verification Warning

`SearchChargebacks` can locate sensitive chargeback records. Search results are possible matches, not proof that the visitor is authorized.

If this operation is used inside a customer-facing AI flow, such as an AI Voice Agent, public chatbot, customer portal assistant, SMS assistant, support chatbot, or other visitor-facing AI workflow, AI/MCP should verify that the visitor is actually related to the resulting Chargeback before providing information, details, or taking action.

Recommended rule:

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

Safe customer-facing flow:

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

Recommended secondary verification values include customer email, customer phone, or another record-backed value from `GetChargeback.customer`.

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

Do not take refund, customer, dispute, subscription, or account actions directly from search results.


---

## Critical Reporting Rule

This Chargeback 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,
- chargeback rate reports,
- chargeback volume reports,
- chargeback amount reports,
- representment/win-loss reports,
- campaign/shop/gateway/customer chargeback analytics,
- method/status breakdown reports,
- card BIN or last-4 analysis.

Use:

```text
BigQueryRunQuery
```

for those purposes.

Important AI/MCP behavior:

```text
If AI/MCP 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 AI/MCP 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 Chargeback for this customer email.” | Use `SearchChargebacks`, then `GetChargeback`. |
| “Find the Chargeback for this gateway transaction ID.” | Use `SearchChargebacks`, then verify with `GetChargeback`. |
| “Find the chargeback related to card ending 4242.” | Use `SearchChargebacks`, then `GetChargeback` and verify the customer. |
| “How many chargebacks mention X?” | Use `BigQueryRunQuery`, not `SearchChargebacks`. |
| “Analyze chargebacks by metadata value.” | Use `BigQueryRunQuery`, not `SearchChargebacks`. |
| “Find chargeback rate by card BIN.” | Use `BigQueryRunQuery`, not `SearchChargebacks`. |

---

## Example: Correct Lookup Flow

```text
User: Find the Chargeback for customer@example.com.
```

Correct:

```text
1. SearchChargebacks with search_term = "customer@example.com".
2. Review results.
3. GetChargeback for the correct result ID.
4. Summarize the exact Chargeback after verification.
```

---

## Example: Incorrect Reporting Flow

```text
User: Search all Chargebacks with gateway=Stripe and tell me dispute rate.
```

Incorrect:

```text
Use SearchChargebacks 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 customer email, gateway transaction ID, card ID, first 6, last 4, or unique metadata values over broad names.
3. Review `highlights` and `score`.
4. Use `GetChargeback` after selecting a result.
5. Do not use search results alone for chargeback, refund, customer, or subscription actions.
6. Do not use search for reporting or data mining.
7. Verify customer identity with a secondary value from `GetChargeback` before sharing details in customer-facing AI flows.
8. Use `BigQueryRunQuery` for metrics and analysis.

---

## Final AI/MCP Instruction

Use `SearchChargebacks` only for targeted full-text lookup of Chargebacks when the exact Chargeback ID is unknown.

In customer-facing AI flows, search results are not proof of authorization. After finding a likely match, use `GetChargeback` 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.