# RevCent MCP Operation: `CreateChargeback`

This document explains the `CreateChargeback` operation in depth so MCP clients can correctly create chargeback records in RevCent.

This guide is operation-specific, but it also explains the broader purpose of chargebacks in RevCent: monitoring disputes, reporting chargeback activity, tracking chargebacks per customer, preventing risky customers from repurchasing, coordinating with third-party chargeback management companies, and generating evidence through `CreateChargebackDocument`.

Sources:
- RevCent API/MCP schema for `CreateChargeback`
- RevCent API/MCP schema for `CreateChargebackDocument`
- RevCent Knowledge Base: [Chargebacks](https://kb.revcent.com/en/payments/credit-card/chargeback)
- RevCent Knowledge Base: [Automated Chargeback Management](https://kb.revcent.com/payments/credit-card/automated-chargeback-management)
- RevCent Knowledge Base: [Chargeback Documents](https://kb.revcent.com/en/tools/documents)
---

## Relevant RevCent Knowledge Base Pages

These KB pages provide additional context for chargebacks, automated chargeback management, and chargeback evidence documents:

| Topic | Link |
|---|---|
| Chargebacks | https://kb.revcent.com/en/payments/credit-card/chargeback |
| Automated Chargeback Management | https://kb.revcent.com/payments/credit-card/automated-chargeback-management |
| Chargeback Documents | https://kb.revcent.com/en/tools/documents |

## Operation Summary

`CreateChargeback` creates a chargeback record in RevCent.

A chargeback must be associated with a previous credit card transaction.

To associate the chargeback with the original transaction, provide either:

```text
transaction_id
```

or:

```text
gateway_transaction_id
```

A chargeback should not be created as an isolated record with no transaction relationship. The value of a chargeback record in RevCent comes from linking it back to the original transaction, customer, sale, products, shipping, gateway, campaign, and related ecommerce context.

Conceptual flow:

```text
Customer makes purchase
  ↓
Credit card transaction is created
  ↓
Issuer/customer creates dispute
  ↓
Merchant receives chargeback
  ↓
CreateChargeback creates chargeback record in RevCent
  ↓
Chargeback is linked to original transaction and related customer/sale data
  ↓
Chargeback can be monitored, reported on, fought, or used for customer-risk workflows
```

---

# Why Create a Chargeback in RevCent?

Creating a chargeback in RevCent allows the business to track and act on disputes.

A RevCent chargeback can support:

- Monitoring dispute volume
- Reporting chargeback rates and amounts
- Tracking chargebacks by customer
- Tracking chargebacks by campaign
- Tracking chargebacks by gateway or merchant account
- Tracking chargebacks by product or product group
- Tracking chargebacks by metadata or affiliate source
- Representment tracking
- Chargeback mitigation workflows
- Third-party chargeback management workflows
- Customer risk review
- Customer blocking or suppression
- Preventing chargeback customers from repurchasing
- Generating chargeback evidence with `CreateChargebackDocument`
- BigQuery reporting and business analysis

A chargeback record is not only a financial event. It is also a customer-risk, reporting, and evidence-management object.

---

# Critical Rule: Link the Chargeback to a Prior Credit Card Transaction

A chargeback must be associated with a previous credit card transaction.

Use one of these:

| Field | Use When |
|---|---|
| `transaction_id` | The RevCent transaction ID is known. Preferred when available. |
| `gateway_transaction_id` | The RevCent transaction ID is not known, but the gateway transaction ID is known. |

Do not provide neither.

Do not create a chargeback without a way to identify the original transaction.

The original transaction link is what allows RevCent to connect the chargeback to the broader ecommerce context.

---

## Preferred Identifier: `transaction_id`

Use `transaction_id` when the RevCent transaction ID is known.

Example:

```json
{
  "transaction_id": "XXXXXXXXXXXXXXXXXXXX",
  "amount": 99.95,
  "case_number": "CB-123456",
  "reason_code": "13.1",
  "chargeback_date": "2026-05-28T14:30:00Z",
  "received_date": "2026-05-29T09:00:00Z"
}
```

`transaction_id` must be a 20-character RevCent transaction ID.

---

## Fallback Identifier: `gateway_transaction_id`

Use `gateway_transaction_id` only when `transaction_id` is not available.

Example:

```json
{
  "gateway_transaction_id": "gw_txn_123456789",
  "amount": 99.95,
  "case_number": "CB-123456",
  "reason_code": "13.1",
  "chargeback_date": "2026-05-28T14:30:00Z",
  "received_date": "2026-05-29T09:00:00Z"
}
```

`gateway_transaction_id` is the transaction ID from the payment gateway.

Important:

```text
Only provide gateway_transaction_id if transaction_id is not present.
```

---

# Input Fields

## Field Summary

| Field | Type | Required by Schema | Practical Requirement | Description |
|---|---:|---:|---:|---|
| `transaction_id` | string | No | Required if `gateway_transaction_id` is not provided | RevCent transaction ID for the disputed transaction. |
| `gateway_transaction_id` | string | No | Required if `transaction_id` is not provided | Gateway transaction ID for the disputed transaction. |
| `amount` | number | No | Recommended | Chargeback amount. |
| `arn` | string | No | Optional | Acquirer reference number, if applicable. |
| `case_number` | string | No | Recommended when available | Chargeback case number. |
| `reason_code` | string | No | Recommended when available | Chargeback reason code. |
| `third_party_integration_id` | string | No | Optional | Third-party integration ID. |
| `third_party_chargeback_id` | string | No | Optional | External chargeback ID from chargeback management company. |
| `third_party_order_id` | string | No | Optional | External order ID from chargeback management company. |
| `chargeback_date` | string/date-time | No | Recommended | Date chargeback was created by issuer and/or customer. |
| `received_date` | string/date-time | No | Recommended | Date merchant received the chargeback. |
| `void_transaction` | boolean | No | High-risk optional | If true, automatically issues a full refund. Cannot be undone. |
| `representment` | object | No | Optional | Information about attempts to fight the chargeback. |
| `metadata` | array<object> | No | Optional | Custom name/value metadata. |

---

## `transaction_id`

The RevCent transaction ID for the chargeback-related transaction.

Use this whenever available.

Rules:

- Must be a 20-character RevCent transaction ID.
- Use instead of `gateway_transaction_id` when possible.
- Identifies the transaction being disputed.
- Allows RevCent to connect the chargeback to the correct customer, sale, gateway, and related records.

Example:

```json
{
  "transaction_id": "XXXXXXXXXXXXXXXXXXXX"
}
```

---

## `gateway_transaction_id`

The gateway transaction ID for the chargeback-related transaction.

Use this only if `transaction_id` is not present.

Rules:

- Only provide when RevCent `transaction_id` is not available.
- Should match the original payment gateway transaction ID.
- Used to associate the chargeback with the correct originating transaction.

Example:

```json
{
  "gateway_transaction_id": "gw_txn_123456789"
}
```

---

## `amount`

The chargeback amount.

Example:

```json
{
  "amount": 99.95
}
```

Guidance:

- Use the amount from the chargeback notice or third-party chargeback system.
- Should usually match the disputed amount, not necessarily the full original order amount if the dispute is partial.
- Use the correct decimal amount.
- Do not guess.

---

## `arn`

The acquirer reference number, if applicable.

Example:

```json
{
  "arn": "12345678901234567890123"
}
```

Use when the chargeback notice or chargeback management provider supplies an ARN.

The ARN can help reconcile the chargeback across the acquirer, payment processor, gateway, and third-party chargeback management systems.

---

## `case_number`

The chargeback case number, if applicable.

Example:

```json
{
  "case_number": "CB-123456789"
}
```

Use the case number from the issuer, processor, gateway, or chargeback management system.

This is useful for:

- Internal tracking
- Third-party chargeback management
- Representment workflows
- Support/risk review
- Matching external case records

---

## `reason_code`

The chargeback reason code, if applicable.

Example:

```json
{
  "reason_code": "13.1"
}
```

Reason codes help identify why the customer or issuer disputed the payment.

Examples of business meaning:

- Fraud-related dispute
- Product not received
- Product not as described
- Credit not processed
- Duplicate charge
- Subscription/billing dispute
- Authorization dispute

The exact reason-code system may vary by card network or provider. MCP should not invent reason codes. Use the reason code supplied by the chargeback notice or provider.

---

## `third_party_integration_id`

A 20-character third-party integration ID.

Example:

```json
{
  "third_party_integration_id": "XXXXXXXXXXXXXXXXXXXX"
}
```

Use when a third-party chargeback management provider or external system is creating or syncing the chargeback into RevCent.

This field helps RevCent identify which integration created or owns the external chargeback relationship.

---

## `third_party_chargeback_id`

The third-party integration chargeback ID.

Example:

```json
{
  "third_party_chargeback_id": "external_cb_123456"
}
```

Use when the chargeback is being created by, or synced from, a third-party chargeback management company.

This helps reconcile the RevCent chargeback with the external provider’s chargeback case.

---

## `third_party_order_id`

The third-party integration order ID.

Example:

```json
{
  "third_party_order_id": "external_order_987654"
}
```

Use when the chargeback management company or external system has its own order identifier.

This can help connect:

```text
RevCent chargeback
  ↔ external chargeback case
  ↔ external order record
  ↔ original sale/transaction
```

---

## `chargeback_date`

The date when the chargeback was created by the issuer and/or customer.

Format:

```text
ISO8601 date-time
```

Example:

```json
{
  "chargeback_date": "2026-05-28T14:30:00Z"
}
```

Use the date from the issuer, card network, gateway, or chargeback management provider.

This is important for:

- Chargeback aging
- Reporting by dispute creation date
- Representment deadlines
- Monitoring daily/weekly/monthly dispute volume
- Comparing chargeback date vs received date

---

## `received_date`

The date when the chargeback was received by the merchant.

Format:

```text
ISO8601 date-time
```

Example:

```json
{
  "received_date": "2026-05-29T09:00:00Z"
}
```

This may differ from `chargeback_date`.

Use it to track when the merchant actually became aware of the chargeback.

This matters for:

- Operational queues
- SLA tracking
- Representment timing
- Third-party management workflows
- Merchant reporting

---

# Critical Warning: `void_transaction`

`void_transaction` is a high-risk field.

Schema description:

```text
You can choose to void the transaction, which will automatically issue a full refund. Default is false. This cannot be undone.
```

Default:

```json
"void_transaction": false
```

Use extreme caution.

If set to:

```json
"void_transaction": true
```

RevCent will automatically issue a full refund by voiding the transaction.

This cannot be undone.

---

## Why `void_transaction` Should Almost Never Be `true`

In most chargeback situations, `void_transaction` should **not** be set to `true`.

A chargeback usually means the customer has already disputed the payment with their bank or card issuer, and the disputed amount is typically pulled back from the merchant through the chargeback process.

Because of that, automatically voiding or refunding the transaction at the same time can create a serious over-refund problem.

Conceptually:

```text
Customer paid $100
  ↓
Customer files chargeback
  ↓
Bank/card issuer returns or credits $100 through chargeback process
  ↓
If void_transaction = true, merchant may also refund/void another $100
  ↓
Customer may effectively receive $200 back on a $100 purchase
```

This is why `void_transaction` should almost never be used when creating a chargeback.

Creating the chargeback record is normally for tracking, reporting, customer history, representment, prevention, and evidence workflows.

It should not normally also refund the transaction.

Default behavior should be:

```json
"void_transaction": false
```

or the field should be omitted.

Only set:

```json
"void_transaction": true
```

when the user explicitly confirms that they understand the customer may already be receiving funds back through the chargeback process and that they still want to issue a separate full refund/void.


## When Not to Use `void_transaction`

MCP should almost never set `void_transaction` to `true`. It should only do so if the user explicitly instructs that the transaction should be voided/refunded and confirms they understand the risk of refunding a chargeback customer twice.

Do not infer this from:

- A chargeback existing
- A customer dispute
- A representment being lost
- A chargeback amount being full order amount
- A third-party system creating the chargeback
- A support note
- A general desire to “record the chargeback”

Creating a chargeback record and voiding/refunding a transaction are different actions. In most cases, the chargeback itself already causes the customer to receive funds back through their bank or card issuer, so an additional void/refund may cause the customer to receive more than they originally paid.

Default safe behavior:

```json
"void_transaction": false
```

or omit the field.

---

## Required Confirmation for `void_transaction: true`

If a human is interacting, MCP should clearly warn:

```text
Setting void_transaction to true will automatically issue a full refund by voiding the transaction. This cannot be undone. Chargebacks are usually already refunded or credited to the customer by their bank/card issuer, so setting this to true may cause the customer to receive back 2x the amount they actually paid. Please confirm that you understand this risk and still want to void/refund the transaction as part of creating this chargeback.
```

Only include:

```json
"void_transaction": true
```

after explicit confirmation.

---

# `representment`

`representment` contains details about any attempt to fight the chargeback.

Shape:

```json
"representment": {
  "initiated": true,
  "initiated_date": "2026-05-30T10:00:00Z",
  "completed": false,
  "completed_date": "2026-06-15T12:00:00Z",
  "outcome": "pending"
}
```

Representment fields:

| Field | Type | Description |
|---|---:|---|
| `initiated` | boolean | Whether representment has been initiated. Read-only once set. |
| `initiated_date` | string/date-time | Date representment was initiated. Read-only once set. |
| `completed` | boolean | Whether representment has completed with an outcome. Requires initiated to be true or previously true. Read-only once set. |
| `completed_date` | string/date-time | Date representment was completed with an outcome. Read-only once set. |
| `outcome` | string enum | Final representment outcome. Allowed: `pending`, `won`, `lost`. |

Allowed `outcome` values:

```text
pending
won
lost
```

---

## Representment Guidance

Representment should be used when the merchant, chargeback mitigation company, or internal team is fighting the chargeback.

Common lifecycle:

```text
Chargeback created
  ↓
Evidence requested
  ↓
CreateChargebackDocument generates evidence
  ↓
Representment initiated
  ↓
Outcome pending
  ↓
Representment completed
  ↓
Outcome won or lost
```

Important:

- `initiated` is read-only once set.
- `initiated_date` is read-only once set.
- `completed` is read-only once set.
- `completed_date` is read-only once set.
- `completed` requires representment to have been initiated or previously initiated.
- `outcome` should be used intentionally.

MCP should not set representment fields unless the user or external provider has provided accurate representment status.

---

## Create-Time Representment Examples

### No Representment Yet

```json
{
  "transaction_id": "XXXXXXXXXXXXXXXXXXXX",
  "amount": 99.95,
  "case_number": "CB-123456",
  "reason_code": "13.1"
}
```

### Representment Initiated

```json
{
  "transaction_id": "XXXXXXXXXXXXXXXXXXXX",
  "amount": 99.95,
  "case_number": "CB-123456",
  "reason_code": "13.1",
  "representment": {
    "initiated": true,
    "initiated_date": "2026-05-30T10:00:00Z",
    "outcome": "pending"
  }
}
```

### Representment Already Completed

```json
{
  "transaction_id": "XXXXXXXXXXXXXXXXXXXX",
  "amount": 99.95,
  "case_number": "CB-123456",
  "reason_code": "13.1",
  "representment": {
    "initiated": true,
    "initiated_date": "2026-05-30T10:00:00Z",
    "completed": true,
    "completed_date": "2026-06-15T12:00:00Z",
    "outcome": "won"
  }
}
```

Only use completed representment details when the outcome is already known.

---

# `metadata`

`metadata` is an array of name/value pairs.

Shape:

```json
"metadata": [
  {
    "name": "chargeback_source",
    "value": "third_party_provider"
  }
]
```

Each metadata object requires:

```text
name
value
```

Use metadata for custom business context that is not captured by standard fields.

Examples:

```json
[
  {
    "name": "chargeback_source",
    "value": "midigator"
  },
  {
    "name": "external_case_status",
    "value": "evidence_requested"
  },
  {
    "name": "risk_review_status",
    "value": "pending"
  },
  {
    "name": "representment_strategy",
    "value": "fight"
  },
  {
    "name": "evidence_requested",
    "value": "true"
  }
]
```

Metadata can help with:

- Third-party provider reconciliation
- Risk review
- Chargeback evidence tracking
- Reporting
- BigQuery grouping/filtering
- Workflow automation
- Customer-level chargeback risk
- Representment process tracking

---

# Example Requests

## Minimal Practical Request With RevCent Transaction ID

```json
{
  "transaction_id": "XXXXXXXXXXXXXXXXXXXX",
  "amount": 99.95,
  "case_number": "CB-123456789",
  "reason_code": "13.1",
  "chargeback_date": "2026-05-28T14:30:00Z",
  "received_date": "2026-05-29T09:00:00Z"
}
```

---

## Request With Gateway Transaction ID

```json
{
  "gateway_transaction_id": "gw_txn_123456789",
  "amount": 99.95,
  "arn": "12345678901234567890123",
  "case_number": "CB-123456789",
  "reason_code": "13.1",
  "chargeback_date": "2026-05-28T14:30:00Z",
  "received_date": "2026-05-29T09:00:00Z"
}
```

---

## Third-Party Chargeback Management Request

```json
{
  "transaction_id": "XXXXXXXXXXXXXXXXXXXX",
  "amount": 99.95,
  "arn": "12345678901234567890123",
  "case_number": "CB-123456789",
  "reason_code": "13.1",
  "third_party_integration_id": "YYYYYYYYYYYYYYYYYYYY",
  "third_party_chargeback_id": "external_cb_123456",
  "third_party_order_id": "external_order_987654",
  "chargeback_date": "2026-05-28T14:30:00Z",
  "received_date": "2026-05-29T09:00:00Z",
  "metadata": [
    {
      "name": "chargeback_source",
      "value": "third_party_provider"
    },
    {
      "name": "external_case_status",
      "value": "received"
    }
  ]
}
```

---

## Request With Representment Initiated

```json
{
  "transaction_id": "XXXXXXXXXXXXXXXXXXXX",
  "amount": 99.95,
  "case_number": "CB-123456789",
  "reason_code": "13.1",
  "chargeback_date": "2026-05-28T14:30:00Z",
  "received_date": "2026-05-29T09:00:00Z",
  "representment": {
    "initiated": true,
    "initiated_date": "2026-05-30T10:00:00Z",
    "outcome": "pending"
  },
  "metadata": [
    {
      "name": "representment_strategy",
      "value": "fight"
    },
    {
      "name": "evidence_requested",
      "value": "true"
    }
  ]
}
```

---

# Output Schema

A successful response returns:

```json
{
  "api_call_id": "XXXXXXXXXXXXXXXXXXXX",
  "api_call_unix": 1740000000,
  "code": 1,
  "chargeback_id": "YYYYYYYYYYYYYYYYYYYY",
  "result": "..."
}
```

Fields:

| Field | Description |
|---|---|
| `api_call_id` | 20-character API call ID. |
| `api_call_unix` | Unix timestamp when the API call was initiated. |
| `code` | API response code. `1` indicates success. |
| `chargeback_id` | 20-character chargeback ID created by the operation. |
| `result` | Human-readable result message. |

---

# After Creating a Chargeback

After a chargeback is created, the chargeback can become the anchor for additional workflows.

Possible follow-up actions:

- Retrieve the chargeback details.
- Create a chargeback document with `CreateChargebackDocument`, especially if the chargeback will be fought, represented, or sent to a mitigation company.
- Add metadata to the customer or chargeback.
- Add customer to a chargeback-related Customer Group.
- Disable or block the customer if business policy requires it.
- Trigger internal risk review.
- Trigger AI Assistant summary or recommendation.
- Notify a third-party chargeback management provider.
- Update representment status later with `EditChargeback`.
- Use BigQuery for reporting and trend analysis.

---

# `CreateChargebackDocument` Relationship

`CreateChargeback` records the dispute.

`CreateChargebackDocument` creates an evidence package for chargeback mitigation.

`CreateChargebackDocument` can search for the originating sale using:

```text
item_type
item_value
```

Allowed `item_type` values include:

```text
sale
transaction
shipping
fraud_detection
chargeback
```

When fighting a chargeback, a chargeback mitigation company can create a document using the chargeback or related item.

Example concept:

```json
{
  "item_type": "chargeback",
  "item_value": "CHARGEBACK_ID_OR_SEARCH_VALUE"
}
```

The document output can include:

- Document ID
- ZIP URL
- Raw document JSON
- Expiration date

The ZIP file contains:

- Friendly formatted `.docx`
- Raw `document_json` in `.json`

Important:

```text
Document URLs expire after 24 hours.
```

---

## Chargeback Evidence Use Case

A chargeback mitigation company can use this workflow:

```text
Chargeback is created in RevCent
  ↓
Provider calls CreateChargebackDocument using item_type = chargeback
  ↓
RevCent finds the originating sale
  ↓
RevCent creates evidence package
  ↓
Provider downloads ZIP with .docx and raw JSON
  ↓
Provider uses evidence in representment
  ↓
Representment status/outcome is updated in RevCent
```

Evidence can include:

- Customer details
- Sale details
- Product details
- Transaction details
- Gateway details
- Customer card reference/BIN details
- Shipping and tracking details
- Tracking visitor data
- IP/device details
- Fraud detection data
- Metadata
- Unique request ID
- Original API request context

This makes `CreateChargeback` and `CreateChargebackDocument` closely related in chargeback mitigation workflows.

---

---

# If Fighting the Chargeback: Use `CreateChargebackDocument`

If the chargeback being created is going to be fought, represented, or sent to a chargeback mitigation company, the MCP should refer to the RevCent KB pages for [Chargebacks](https://kb.revcent.com/en/payments/credit-card/chargeback), [Automated Chargeback Management](https://kb.revcent.com/payments/credit-card/automated-chargeback-management), and [Chargeback Documents](https://kb.revcent.com/en/tools/documents). The MCP should also consider using:

```text
CreateChargebackDocument
```

Creating the chargeback record with `CreateChargeback` stores the dispute in RevCent.

Creating a chargeback document with `CreateChargebackDocument` helps generate the evidence package needed to fight that chargeback.

These are related but different actions:

| Operation | Purpose |
|---|---|
| `CreateChargeback` | Creates the chargeback/dispute record in RevCent. |
| `CreateChargebackDocument` | Creates a chargeback mitigation evidence package from the originating sale. |

---

## Why This Matters

A chargeback record is useful for tracking, reporting, customer history, and representment status.

However, fighting a chargeback usually requires evidence.

`CreateChargebackDocument` helps generate that evidence by finding the originating sale and packaging related purchase details.

The document can help prove:

- The customer purchased the item.
- The sale occurred.
- The transaction was processed.
- The products purchased.
- The billing and shipping information used.
- The customer and purchase context.
- Tracking visitor details.
- IP/device information.
- Shipping and tracking information.
- Fraud detection context, when available.
- Gateway/transaction evidence.
- Customer card reference/BIN details.
- Metadata and unique request details.

This can help a merchant or chargeback mitigation company prepare a representment package.

---

## Recommended Workflow When Fighting a Chargeback

If the user says they want to fight, dispute, represent, or mitigate the chargeback, the MCP should think in this order:

```text
CreateChargeback
  ↓
Store chargeback_id
  ↓
CreateChargebackDocument using the chargeback or related item
  ↓
Download/use the ZIP evidence package
  ↓
Submit evidence through the merchant, gateway, processor, or chargeback mitigation company
  ↓
Update representment status/outcome later with EditChargeback
```

Example:

```text
Chargeback is created in RevCent
  ↓
MCP receives chargeback_id
  ↓
MCP may call CreateChargebackDocument with item_type = chargeback
  ↓
RevCent creates ZIP containing formatted .docx and raw JSON
  ↓
Evidence is used for representment
```

---

## `CreateChargebackDocument` Input Concept

`CreateChargebackDocument` creates a chargeback mitigation document from an originating sale by searching with:

```text
item_type
item_value
```

Allowed `item_type` values include:

```text
sale
transaction
shipping
fraud_detection
chargeback
```

If the chargeback was just created and the new `chargeback_id` is available, the MCP may use:

```json
{
  "item_type": "chargeback",
  "item_value": "XXXXXXXXXXXXXXXXXXXX"
}
```

where `item_value` is the newly created `chargeback_id`.

If the chargeback document should instead be based on a known sale or transaction, the MCP may use:

```json
{
  "item_type": "sale",
  "item_value": "SALE_ID_OR_SEARCH_VALUE"
}
```

or:

```json
{
  "item_type": "transaction",
  "item_value": "TRANSACTION_ID_OR_SEARCH_VALUE"
}
```

---

## Output of `CreateChargebackDocument`

A successful chargeback document response may include:

- Document ID
- Expiration date
- ZIP URL
- Raw document JSON
- Result message

The ZIP file contains:

```text
Friendly formatted .docx evidence document
Raw document_json .json file
```

Important:

```text
Document URLs expire after 24 hours.
```

If the document is needed by a chargeback mitigation company or internal dispute team, it should be downloaded and stored promptly.

---

## MCP Guidance

When creating a chargeback, MCP should ask or infer from the user’s stated intent:

```text
Is this chargeback only being recorded, or will it be fought/represented?
```

If the chargeback is only being recorded:

```text
CreateChargeback may be enough.
```

If the chargeback will be fought:

```text
CreateChargebackDocument should usually be considered after CreateChargeback.
```

MCP should not automatically assume every chargeback will be fought. Some chargebacks may only be recorded for reporting, monitoring, customer-risk tracking, or prevention.

But if the user says anything like:

```text
fight this chargeback
represent this chargeback
send this to a mitigation company
need evidence
need proof of purchase
need dispute documentation
```

then `CreateChargebackDocument` is likely relevant.


# Customer-Level Chargeback Tracking

Creating a chargeback in RevCent helps keep track of chargebacks per customer.

A customer with chargeback history may need different treatment than a customer with no dispute history.

Customer chargeback history can support:

- Risk review
- Manual support review
- Customer blocking
- Do-not-sell workflows
- Customer Group qualification
- BigQuery reporting
- AI Assistant summaries
- Third-party risk evaluation
- Suppression from marketing or sales outreach
- Prevention from repurchasing when appropriate

Examples of chargeback-related Customer Groups:

```text
Chargeback Customer
Repeat Chargeback Customer
Chargeback Risk
Do Not Sell
Manual Review Required
Fraud + Chargeback Review
Lost Representment Customer
Won Representment Customer
```

---

# Preventing Chargeback Customers From Repurchasing

A business may want to prevent customers with chargeback history from purchasing again.

Possible workflow:

```text
CreateChargeback
  ↓
Chargeback links to customer
  ↓
Customer is evaluated for risk
  ↓
Customer is added to Chargeback Risk / Do Not Sell / Manual Review group
  ↓
Future purchase workflows can treat customer differently
```

A more restrictive workflow:

```text
CreateChargeback
  ↓
Customer has repeated chargebacks or lost representment
  ↓
Customer is blocked or disabled according to business policy
  ↓
Future purchase attempts are prevented or reviewed
```

MCP should not automatically block a customer unless the user explicitly requests it or a defined business rule requires it.

Creating a chargeback and blocking a customer are separate actions.

---

# Monitoring and Reporting

`CreateChargeback` creates the data foundation for monitoring and reporting.

Use individual chargeback operations for:

- Creating chargeback records
- Viewing individual chargeback details
- Searching for specific chargebacks
- Updating representment status

Use BigQuery for:

- Counts
- Totals
- Rates
- Trends
- Grouping
- Chargeback rate by campaign
- Chargeback amount by gateway
- Chargeback rate by product
- Chargebacks by customer group
- Chargebacks by affiliate metadata
- Representment win/loss rate
- Chargebacks per customer
- Chargebacks by reason code
- Chargebacks by third-party management provider

Important:

```text
Do not use list operations for counting, aggregations, or metrics. Use BigQuery for reporting.
```

---

# MCP Decision Process

Before calling `CreateChargeback`, MCP should determine:

1. What original transaction is disputed?
2. Is the RevCent `transaction_id` known?
3. If not, is the `gateway_transaction_id` known?
4. What is the chargeback amount?
5. What is the case number?
6. What is the reason code?
7. What is the ARN, if available?
8. What is the chargeback date?
9. What is the received date?
10. Was the chargeback created by a third-party chargeback management company?
11. Are third-party IDs available?
12. Should metadata be included?
13. Has representment been initiated?
14. Has representment already completed?
15. Is the outcome pending, won, or lost?
16. Should the transaction be voided/refunded?
17. If `void_transaction` is true, has the user explicitly confirmed the irreversible refund/void?
18. Should a chargeback document be created afterward?
19. Should the customer be reviewed, grouped, disabled, or blocked?
20. Should this chargeback feed into reporting or external mitigation workflows?

---

# Validation Checklist

Before submitting `CreateChargeback`:

1. Either `transaction_id` or `gateway_transaction_id` is present.
2. Prefer `transaction_id` when available.
3. `gateway_transaction_id` is only used when `transaction_id` is unavailable.
4. `transaction_id`, if provided, is a 20-character RevCent transaction ID.
5. `amount` is accurate and not guessed.
6. `case_number` is included if available.
7. `reason_code` is included if available and not invented.
8. `arn` is included if available.
9. `chargeback_date` is ISO8601 if provided.
10. `received_date` is ISO8601 if provided.
11. Third-party fields are included only when relevant.
12. Metadata name/value pairs are valid.
13. Representment fields are accurate if included.
14. Representment outcome is one of `pending`, `won`, or `lost`.
15. Read-only-once-set representment fields are not casually populated.
16. `void_transaction` is omitted or false unless explicitly confirmed. It should almost never be true because the chargeback process usually already returns funds to the customer.
17. If `void_transaction` is true, the user understands it automatically issues a full refund, cannot be undone, and may cause the customer to receive back twice the amount they actually paid.
18. Follow-up actions are considered: evidence document, customer group, risk review, reporting, or external provider sync.

---

# Common Mistakes

## Mistake: Creating a Chargeback Without a Transaction Reference

Wrong:

```json
{
  "amount": 99.95,
  "case_number": "CB-123456"
}
```

Correct:

```json
{
  "transaction_id": "XXXXXXXXXXXXXXXXXXXX",
  "amount": 99.95,
  "case_number": "CB-123456"
}
```

or:

```json
{
  "gateway_transaction_id": "gw_txn_123456789",
  "amount": 99.95,
  "case_number": "CB-123456"
}
```

---

## Mistake: Guessing Reason Codes

Do not invent reason codes.

Use the reason code from:

- Issuer
- Gateway
- Processor
- Card network
- Chargeback management provider

---

## Mistake: Setting `void_transaction` Without Explicit Instruction

Wrong:

```json
{
  "transaction_id": "XXXXXXXXXXXXXXXXXXXX",
  "void_transaction": true
}
```

unless the user explicitly confirmed the irreversible refund/void and the risk of giving the chargeback customer back more than they originally paid.

Default safe behavior:

```json
{
  "transaction_id": "XXXXXXXXXXXXXXXXXXXX",
  "void_transaction": false
}
```

or omit `void_transaction`.

---

## Mistake: Treating Chargeback Creation as Customer Blocking

Creating a chargeback does not automatically mean the customer should be blocked.

Customer blocking, disabling, or group assignment should follow explicit business policy.

---

## Mistake: Forgetting Chargeback Documents

If the chargeback will be fought, consider creating evidence with:

```text
CreateChargebackDocument
```

A chargeback record tracks the dispute. A chargeback document packages evidence.

---

## Mistake: Using List Operations for Reporting

Do not use `GetChargebacks` to count or aggregate chargebacks.

Use BigQuery for reporting.

---

# Quick Reference

Minimum practical request:

```json
{
  "transaction_id": "XXXXXXXXXXXXXXXXXXXX",
  "amount": 99.95
}
```

Fallback transaction request:

```json
{
  "gateway_transaction_id": "gw_txn_123456789",
  "amount": 99.95
}
```

Recommended request:

```json
{
  "transaction_id": "XXXXXXXXXXXXXXXXXXXX",
  "amount": 99.95,
  "arn": "12345678901234567890123",
  "case_number": "CB-123456789",
  "reason_code": "13.1",
  "chargeback_date": "2026-05-28T14:30:00Z",
  "received_date": "2026-05-29T09:00:00Z",
  "metadata": [
    {
      "name": "risk_review_status",
      "value": "pending"
    }
  ]
}
```

Most important rules:

```text
A chargeback must be associated with a previous credit card transaction.
Use transaction_id when available.
Use gateway_transaction_id only when transaction_id is unavailable.
Do not set void_transaction to true except in rare, explicitly confirmed cases; chargebacks usually already return funds to the customer, and an additional void/refund can over-refund the customer.
Do not invent chargeback reason codes.
Use metadata for custom external or business context.
Use CreateChargebackDocument when evidence is needed, especially if the chargeback will be fought or represented.
Use BigQuery for chargeback reporting and metrics.
```


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