# RevCent MCP Operation: `CreateChargebackDocument`

This document explains the `CreateChargebackDocument` operation in depth so MCP clients can correctly create chargeback mitigation documents in RevCent.

This guide is operation-specific, but it also explains the broader purpose of chargeback documents in RevCent: generating purchase evidence that can help a merchant, internal risk team, or chargeback mitigation company fight a chargeback.

Sources:
- RevCent API/MCP schema for `CreateChargebackDocument`
- RevCent API/MCP schema for `CreateChargeback`
- RevCent API/MCP schema for `EditChargeback`
- 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)

---

## Operation Summary

`CreateChargebackDocument` creates a chargeback mitigation document from an originating sale.

It searches for the originating sale using:

```text
item_type
item_value
```

The document contains detailed information about the originating sale and related evidence, including purchase details, customer details, transaction information, tracking visitor information, shipping information, fraud detection context, and other supporting data.

The output includes:

- A document ID
- A ZIP URL
- An expiration date
- Raw `document_json`
- A result message

The ZIP file contains:

```text
A friendly formatted .docx file
Raw document_json in a .json file
```

Important:

```text
All document URLs expire after 24 hours.
```

---

# What Is a Chargeback Document?

A chargeback document is an evidence package used for chargeback mitigation.

It is not general system documentation.

It is a dispute-response document designed to help prove details about the originating sale.

A chargeback document can help show:

- The customer purchased an item.
- The sale occurred.
- The transaction was attempted or approved.
- The product details associated with the purchase.
- The billing and shipping details used.
- The shipping/tracking status, if applicable.
- The customer’s tracking visitor details.
- IP/device/visitor context.
- Fraud detection details, if available.
- Payment/gateway/transaction context.
- Customer card reference and BIN details, if available.
- Metadata and unique request context.

This makes the document especially important when a chargeback is being fought through representment.

---

# Why Chargeback Documents Matter

Fighting a chargeback usually requires evidence.

A merchant or chargeback mitigation company may need to provide proof that:

```text
The customer made the purchase.
The product or service was sold.
The transaction was processed.
The item was shipped or delivered.
The billing/shipping/customer details were captured.
The visitor and device context support the purchase.
The merchant has transaction and order records.
```

`CreateChargebackDocument` helps package this evidence from RevCent into a usable format.

Instead of manually gathering sale, customer, shipping, transaction, fraud, and tracking data from many places, the MCP can create a chargeback document that includes a formatted `.docx` file and raw JSON.

---

# When to Use `CreateChargebackDocument`

Use `CreateChargebackDocument` when a chargeback needs supporting evidence.

Common situations:

- A chargeback is being fought.
- A representment package is being prepared.
- A chargeback mitigation company needs evidence.
- A merchant needs purchase proof.
- A dispute response needs shipping/tracking details.
- A risk team needs to review the originating sale.
- A customer has disputed a transaction and evidence is required.
- A chargeback exists and the business wants to decide whether to fight it.
- A third-party chargeback provider is requesting order evidence.

Do not use `CreateChargebackDocument` for general reporting. Use BigQuery for metrics and reporting.

---

# Relationship to Chargebacks and Representment

`CreateChargebackDocument` is closely related to chargeback representment.

A typical chargeback workflow may look like this:

```text
CreateChargeback
  ↓
Chargeback record is created in RevCent
  ↓
Business decides to fight the chargeback
  ↓
CreateChargebackDocument generates evidence package
  ↓
Evidence is submitted by merchant or mitigation company
  ↓
EditChargeback updates representment status
  ↓
Representment outcome is updated as pending, won, or lost
```

The chargeback document helps with the evidence side.

`EditChargeback` helps keep the chargeback record and reporting status accurate.

---

# Important: Update Representment Status When Fighting a Chargeback

When a chargeback is being fought, it is important to update the chargeback’s `representment` fields using `EditChargeback`.

The chargeback document generates the evidence package, but the representment fields track what happened in the chargeback fight.

Without representment updates, RevCent may know that the chargeback exists, but reporting may not accurately show:

- Whether the chargeback was fought
- Whether the fight is pending
- Whether the merchant won
- Whether the merchant lost
- Which chargebacks were not fought
- Win/loss rate
- Fight rate
- Pending representment cases

---

## Representment Status Flow

Recommended status flow when fighting a chargeback:

```text
Chargeback created
  ↓
Evidence document generated with CreateChargebackDocument
  ↓
Representment is submitted
  ↓
EditChargeback sets representment.initiated = true
  ↓
Outcome is pending
  ↓
Final result received
  ↓
EditChargeback sets representment.completed = true
  ↓
EditChargeback sets outcome = won or lost
```

---

## EditChargeback Representment Fields

The `representment` object can include:

| Field | Purpose |
|---|---|
| `initiated` | Whether representment has been initiated. |
| `initiated_date` | Date representment was initiated. |
| `completed` | Whether representment has completed with an outcome. |
| `completed_date` | Date representment was completed. |
| `outcome` | Final outcome: `pending`, `won`, or `lost`. |

Allowed outcomes:

```text
pending
won
lost
```

Important:

Several representment fields are read-only once set. MCP should not guess or casually set them.

---

## Example: Mark Representment Initiated After Creating Evidence

After using `CreateChargebackDocument` and submitting evidence, update the chargeback:

```json
{
  "chargeback_id": "XXXXXXXXXXXXXXXXXXXX",
  "representment": {
    "initiated": true,
    "initiated_date": "2026-05-30T10:00:00Z",
    "outcome": "pending"
  }
}
```

This tells RevCent:

```text
This chargeback is being fought, but the outcome is not known yet.
```

---

## Example: Mark Representment Won

When the final outcome is known:

```json
{
  "chargeback_id": "XXXXXXXXXXXXXXXXXXXX",
  "representment": {
    "completed": true,
    "completed_date": "2026-06-15T12:00:00Z",
    "outcome": "won"
  }
}
```

If initiated was not previously set, include accurate initiated fields:

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

---

## Example: Mark Representment Lost

```json
{
  "chargeback_id": "XXXXXXXXXXXXXXXXXXXX",
  "representment": {
    "completed": true,
    "completed_date": "2026-06-15T12:00:00Z",
    "outcome": "lost"
  }
}
```

If initiated was not previously set, include accurate initiated fields:

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

---

# Input Schema

`CreateChargebackDocument` requires:

| Field | Type | Required | Description |
|---|---:|---:|---|
| `item_type` | string enum | Yes | The item type to search. Used with `item_value` to find the specific item and create a document on its originating sale. |
| `item_value` | string | Yes | The item value to use when searching for the item type. |

Allowed `item_type` values:

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

---

## `item_type`

`item_type` tells RevCent what kind of item the MCP is using to find the originating sale.

Allowed values:

| `item_type` | Use When |
|---|---|
| `sale` | The sale ID or sale search value is known. |
| `transaction` | The transaction ID or transaction search value is known. |
| `shipping` | The shipping ID or shipping search value is known. |
| `fraud_detection` | The fraud detection ID or fraud detection search value is known. |
| `chargeback` | The chargeback ID or chargeback search value is known. |

Best option when fighting a known chargeback:

```text
item_type = chargeback
```

because the chargeback itself should already be tied to the originating transaction/sale.

---

## `item_value`

`item_value` is the value used to search for the selected `item_type`.

Examples:

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

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

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

MCP should use the most direct known item value.

If the user just created a chargeback and received a `chargeback_id`, use:

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

---

# Choosing the Right `item_type`

## Use `chargeback`

Use when the chargeback record exists and the chargeback ID is known.

Recommended for:

- Fighting a specific chargeback
- Chargeback mitigation company requests
- Evidence generation after `CreateChargeback`
- Dispute workflow based on an existing chargeback record

Example:

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

---

## Use `sale`

Use when the original sale is known and the chargeback ID may not be available.

Recommended for:

- Pre-dispute evidence review
- Internal sale evidence review
- Purchase proof by sale
- Generating evidence before a chargeback has been formally created

Example:

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

---

## Use `transaction`

Use when the payment transaction is known.

Recommended for:

- Chargeback notice provides transaction reference
- Gateway/processor data is mapped to a RevCent transaction
- Evidence package should be built from the transaction side

Example:

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

---

## Use `shipping`

Use when the shipping record is the available starting point.

Recommended for:

- Product-not-received disputes
- Delivery evidence workflows
- Tracking evidence review
- Shipment-driven chargeback evidence

Example:

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

---

## Use `fraud_detection`

Use when the fraud detection record is the available starting point.

Recommended for:

- Fraud-related chargeback review
- Risk-team investigation
- Evidence involving fraud score/context
- Third-party fraud detection reconciliation

Example:

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

---

# Output Schema

A successful `CreateChargebackDocument` response can include:

| Field | Type | Description |
|---|---:|---|
| `api_call_id` | string | 20-character API call ID. |
| `api_call_unix` | integer | Unix timestamp when the API call was initiated. |
| `code` | integer | API response code. `1` indicates success. |
| `id` | string | 20-character document ID. |
| `expires_on` | string/date-time | Date the document URL expires. |
| `zip_url` | string | URL to a ZIP containing `.docx` and raw `.json`. |
| `document_json` | object | Raw JSON containing details of the originating sale. |
| `result` | string | Human-readable result message. |

Example response shape:

```json
{
  "api_call_id": "XXXXXXXXXXXXXXXXXXXX",
  "api_call_unix": 1740000000,
  "code": 1,
  "id": "YYYYYYYYYYYYYYYYYYYY",
  "expires_on": "2026-05-29T12:00:00Z",
  "zip_url": "https://...",
  "document_json": {},
  "result": "..."
}
```

---

# Critical Expiration Rule

The generated document URL expires after 24 hours.

MCP must treat this as important.

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

If the document is needed by a merchant, risk team, or chargeback mitigation company, the ZIP should be downloaded and stored promptly according to the business’s document retention process.

The MCP should not assume the URL will be available later.

---

# What the ZIP Contains

The `zip_url` points to a ZIP file.

When unpacked, it contains:

```text
A friendly formatted .docx file
A raw document_json .json file
```

The `.docx` file is useful for human review and chargeback representment packages.

The raw `.json` file is useful for:

- Third-party chargeback mitigation companies
- Automated evidence review
- AI Assistant analysis
- Internal risk systems
- External AI Agents
- Audit trails
- Structured dispute workflow systems

---

# What `document_json` Can Contain

The raw `document_json` can contain detailed evidence from the originating sale.

The exact content depends on the originating sale and related records, but can include the following categories.

---

## API Call / Original Request Evidence

This can show how the original sale request was made.

Possible fields include:

- API account
- API call ID
- API method
- Original request body
- Billing information
- Shipping information
- Customer ID
- IP address
- Metadata
- Payment profile
- Product IDs and quantities
- Shipping amounts/provider/method
- Unique request ID

Why it matters:

```text
The original request can help prove what was submitted at the time of purchase.
```

---

## Campaign Evidence

Possible fields include:

- Campaign ID
- Campaign name

Why it matters:

```text
Campaign data can help identify which offer or acquisition source generated the purchase.
```

---

## Customer Evidence

Possible fields include:

- Customer ID
- First name
- Last name
- Email
- Phone
- Company
- Address
- City/state/ZIP/country
- Enabled status
- Blocked status
- Internal ID
- Metadata
- Device details
- IP details
- Email intelligence details
- Phone intelligence details

Why it matters:

```text
Customer evidence helps connect the sale to a real customer profile and purchase context.
```

---

## Sale Evidence

Possible fields include:

- Sale ID
- Sale amount
- Sale created date
- Unique request ID
- Currency
- Campaign

Why it matters:

```text
Sale evidence proves the purchase occurred and ties the transaction to an order-like record.
```

---

## Product Evidence

Possible fields include:

- Product ID
- Internal product ID
- Product name
- SKU
- Price
- Quantity
- Total amount

Why it matters:

```text
Product evidence shows what the customer purchased and how much was charged.
```

---

## Transaction Evidence

Possible fields include:

- Transaction ID
- Amount
- Approved/declined/error status
- Gateway ID
- Gateway name
- Gateway transaction ID
- Gateway result phrase
- Gateway authorization code
- AVS result code
- CVV result code
- CAVV result code
- Merchant account ID
- Customer card reference data
- BIN details

Why it matters:

```text
Transaction evidence helps show payment processing details and gateway response information.
```

---

## Customer Card Reference / BIN Evidence

Possible fields include generic customer card reference information such as:

- Customer card ID
- Card type
- First 6 digits / BIN
- Last 4 digits
- Expiration date
- Expiration month
- Expiration year
- BIN bank
- BIN card
- BIN type
- BIN level
- BIN country
- BIN validity
- Card issuer

Why it matters:

```text
Customer card reference and BIN evidence can help identify the payment method context without exposing raw card data.
```

---

## Shipping Evidence

Possible fields include:

- Shipping ID
- Shipping amount
- Shipping created date
- Fulfillment account
- Fulfillment center
- Whether fulfillment account was notified
- Fulfillment notification date
- Whether shipment was shipped
- Whether shipment was delivered
- Provider
- Provider method
- Tracking number
- Tracking URL
- Ship date
- Delivered date
- Ship-to details
- Shipping status

Why it matters:

```text
Shipping evidence is especially important for product-not-received and delivery-related chargebacks.
```

---

## Tracking Visitor Evidence

Possible fields include:

- Tracking visitor ID
- Visitor fingerprint
- IP address
- User agent
- IP geolocation
- Network/company details
- Language/currency/timezone details
- Threat/proxy/TOR/datacenter indicators
- Tracking entries
- Tracking domain
- Host/path visited

Why it matters:

```text
Tracking visitor evidence helps show visitor behavior and technical purchase context.
```

---

## Tracking Entries

Possible fields include:

- Tracking entry created date
- Host
- Pathname
- Tracking domain ID
- Tracking domain name
- Tracking domain URL

Why it matters:

```text
Tracking entries can help show the pages or tracked events associated with the customer journey.
```

---

## Fraud Detection Evidence

Possible fields include:

- Fraud detection request ID
- Fraud score
- Fraud threshold
- Whether fraud was detected
- Whether it was an error
- Third-party fraud detection ID
- Third-party fraud detection integration
- Raw fraud response

Why it matters:

```text
Fraud detection evidence may support or contextualize a fraud-related dispute.
```

---

## Chargeback Evidence

Possible fields include:

- Related chargeback records
- Chargeback metadata
- Chargeback history connected to the originating sale

Why it matters:

```text
Chargeback history can help show whether the sale or customer has related dispute records.
```

---

# Why This Evidence Is Important When Fighting a Chargeback

Chargeback disputes often depend on evidence.

A formatted `.docx` and raw JSON package can help a merchant or mitigation company support claims such as:

```text
The customer placed the order.
The order was processed.
The transaction was approved.
The product was purchased.
The item shipped.
The tracking number exists.
The package was delivered.
The customer’s IP/device/visitor details were recorded.
The gateway response supports the transaction.
The fraud/risk context was captured.
```

This can be especially important for disputes such as:

- Product not received
- Product not as described
- Fraudulent transaction claim
- Subscription/billing dispute
- Duplicate charge dispute
- Credit not processed dispute
- Authorization-related dispute
- Customer claims they did not purchase

The document does not guarantee that a chargeback will be won. It provides supporting evidence that may help the merchant or chargeback mitigation company fight the chargeback.

---

# Recommended Workflow: Fighting a Chargeback

When the user wants to fight a chargeback, MCP should follow a workflow similar to:

```text
1. Confirm the chargeback exists in RevCent.
2. Confirm the chargeback_id or related sale/transaction/shipping/fraud_detection ID.
3. Call CreateChargebackDocument.
4. Save document ID, ZIP URL, expiration date, and raw document_json if needed.
5. Download or provide ZIP promptly because URL expires after 24 hours.
6. Submit evidence through the proper chargeback mitigation process.
7. Call EditChargeback to mark representment as initiated.
8. Later call EditChargeback again when outcome is known.
9. Use BigQuery/reporting to track fought, pending, won, lost, and not-fought chargebacks.
```

---

# Recommended Workflow With Third-Party Chargeback Mitigation Company

A third-party chargeback mitigation company may use this operation as part of an evidence workflow.

```text
Chargeback received by mitigation company
  ↓
Chargeback exists or is created in RevCent
  ↓
Mitigation company requests evidence
  ↓
CreateChargebackDocument is called with item_type = chargeback
  ↓
ZIP evidence package is generated
  ↓
Provider downloads .docx and raw JSON
  ↓
Provider submits representment
  ↓
EditChargeback updates representment.initiated and outcome
```

This keeps RevCent aligned with the external provider’s chargeback lifecycle.

---

# Relationship to `CreateChargeback`

`CreateChargeback` records the chargeback.

`CreateChargebackDocument` creates evidence for the chargeback.

Use them together when a chargeback is created and then fought.

Typical sequence:

```text
CreateChargeback
  ↓
chargeback_id returned
  ↓
CreateChargebackDocument with item_type = chargeback
  ↓
Evidence package generated
  ↓
EditChargeback marks representment status
```

---

# Relationship to `EditChargeback`

`EditChargeback` should be used to update representment status as mitigation occurs.

`CreateChargebackDocument` does not mark the chargeback as fought by itself.

Important:

```text
Creating a chargeback document does not automatically mean representment was initiated.
```

A document may be created for:

- Internal review
- Deciding whether to fight
- Preparing evidence
- Sending to a mitigation company
- Risk analysis

Only update representment as initiated when the chargeback is actually being fought/submitted for representment.

---

## Important Representment Reporting Categories

Accurate `EditChargeback` updates help distinguish:

| Category | Meaning |
|---|---|
| Not fought | No representment initiated. |
| Fought pending | Representment initiated but no final result. |
| Won | Representment completed and outcome is `won`. |
| Lost | Representment completed and outcome is `lost`. |
| Total fought | All chargebacks with representment initiated. |
| Win rate | Won divided by completed representments. |
| Fight rate | Fought chargebacks divided by total chargebacks. |

This is why the MCP should consider `EditChargeback` after `CreateChargebackDocument` when mitigation is actually happening.

---

# Example Requests

## Create Document From Chargeback

Use when the chargeback ID is known.

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

---

## Create Document From Sale

Use when the sale ID is known.

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

---

## Create Document From Transaction

Use when the transaction ID is known.

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

---

## Create Document From Shipping

Use when shipping evidence is the starting point.

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

---

## Create Document From Fraud Detection

Use when fraud detection context is the starting point.

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

---

# Example: Full Fight Workflow

## Step 1: Create Evidence Document

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

Expected result:

```text
Document ID
ZIP URL
Expiration date
Raw document_json
```

## Step 2: Use Evidence

```text
Download ZIP within 24 hours.
Use .docx and/or raw JSON in chargeback mitigation workflow.
```

## Step 3: Mark Representment Initiated

```json
{
  "chargeback_id": "XXXXXXXXXXXXXXXXXXXX",
  "representment": {
    "initiated": true,
    "initiated_date": "2026-05-30T10:00:00Z",
    "outcome": "pending"
  }
}
```

## Step 4: Mark Final Outcome Later

Won:

```json
{
  "chargeback_id": "XXXXXXXXXXXXXXXXXXXX",
  "representment": {
    "completed": true,
    "completed_date": "2026-06-15T12:00:00Z",
    "outcome": "won"
  }
}
```

Lost:

```json
{
  "chargeback_id": "XXXXXXXXXXXXXXXXXXXX",
  "representment": {
    "completed": true,
    "completed_date": "2026-06-15T12:00:00Z",
    "outcome": "lost"
  }
}
```

---

# MCP Decision Process

Before calling `CreateChargebackDocument`, MCP should determine:

1. Is the user trying to fight a chargeback, review evidence, or simply inspect a sale?
2. Does a chargeback record already exist?
3. What identifier is available?
4. Should `item_type` be `chargeback`, `sale`, `transaction`, `shipping`, or `fraud_detection`?
5. What exact `item_value` should be used?
6. Is the chargeback document needed by a third-party mitigation company?
7. Does the user need the `.docx`, raw JSON, or both?
8. Does the user understand the ZIP URL expires after 24 hours?
9. Should the evidence package be downloaded/stored promptly?
10. After evidence is submitted, should `EditChargeback` mark representment as initiated?
11. Later, should `EditChargeback` mark the outcome as `won` or `lost`?
12. Should this feed reporting for fought/won/lost/not-fought chargebacks?

---

# Validation Checklist

Before submitting `CreateChargebackDocument`:

1. `item_type` is present.
2. `item_type` is one of `sale`, `transaction`, `shipping`, `fraud_detection`, or `chargeback`.
3. `item_value` is present.
4. `item_value` corresponds to the selected `item_type`.
5. Use `item_type = chargeback` when fighting a known chargeback and `chargeback_id` is available.
6. Use `item_type = sale` when the originating sale is the best known identifier.
7. Use `item_type = transaction` when transaction data is the best known identifier.
8. Use `item_type = shipping` when shipping evidence is the starting point.
9. Use `item_type = fraud_detection` when fraud context is the starting point.
10. The MCP understands this creates an evidence package, not a general documentation file.
11. The MCP plans for the ZIP URL expiring after 24 hours.
12. If the chargeback is being fought, the MCP considers updating representment with `EditChargeback`.
13. If representment has not actually been submitted, MCP does not mark representment as initiated.
14. If the final outcome is not known, MCP does not mark outcome as won/lost.
15. If a third-party mitigation company is involved, the MCP preserves document ID, ZIP URL, expiration date, and raw JSON as needed.

---

# Common Mistakes

## Mistake: Treating the Document as General Documentation

Wrong:

```text
Use CreateChargebackDocument to get general system docs.
```

Correct:

```text
CreateChargebackDocument creates a chargeback mitigation evidence document for an originating sale.
```

---

## Mistake: Forgetting the URL Expires

The ZIP URL expires after 24 hours.

MCP should not assume the document will be downloadable later.

---

## Mistake: Creating Evidence But Not Updating Representment

If the evidence was actually submitted and the chargeback is being fought, do not stop at creating the document.

Follow up with `EditChargeback`:

```text
representment.initiated = true
outcome = pending
```

Later update:

```text
completed = true
outcome = won or lost
```

---

## Mistake: Marking Representment Initiated Too Early

Creating a document does not automatically mean representment was initiated.

Only mark representment initiated when the chargeback is actually being fought or submitted.

---

## Mistake: Using the Wrong `item_type`

If the user gives a chargeback ID, use:

```json
"item_type": "chargeback"
```

not:

```json
"item_type": "sale"
```

unless the value is actually a sale identifier.

---

## Mistake: Ignoring Raw JSON

The `.docx` is useful for humans, but raw JSON can be useful for:

- AI Assistant analysis
- Third-party AI Agents
- Chargeback mitigation platforms
- Internal risk systems
- Audit workflows
- Structured evidence review

MCP should preserve or pass along raw JSON when the workflow needs structured evidence.

---

# Output Handling Best Practices

After successful creation, MCP should capture:

```text
document ID
expires_on
zip_url
document_json
```

If interacting with a human user, MCP should clearly state:

```text
The ZIP URL expires after 24 hours.
```

If sending to a third-party mitigation provider, MCP should ensure the provider receives or downloads the evidence package within the expiration window.

If the business needs long-term retention, the ZIP or extracted files should be saved according to the business’s retention process.

---

# Reporting and Analytics Impact

`CreateChargebackDocument` itself creates evidence, but the fight outcome must be tracked through `EditChargeback`.

For chargeback reporting, the important pattern is:

```text
CreateChargebackDocument = evidence generated
EditChargeback.representment = fight status and outcome
BigQuery = reporting and analytics
```

Accurate updates allow reporting on:

- Chargebacks fought
- Chargebacks not fought
- Chargebacks pending
- Chargebacks won
- Chargebacks lost
- Win rate
- Fight rate
- Loss rate
- Chargebacks by reason code
- Chargebacks by customer
- Chargebacks by campaign
- Chargebacks by gateway
- Chargebacks by mitigation provider
- Chargebacks with evidence generated

---

# Quick Reference

Required request:

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

Allowed `item_type` values:

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

Output includes:

```text
id
expires_on
zip_url
document_json
```

ZIP contains:

```text
friendly formatted .docx
raw document_json .json
```

Most important rules:

```text
CreateChargebackDocument creates a chargeback mitigation evidence package.
It is primarily used to help fight chargebacks.
Use item_type = chargeback when creating evidence for a known chargeback.
The ZIP URL expires after 24 hours.
Creating a document does not automatically mark representment as initiated.
If the chargeback is actually being fought, update EditChargeback representment fields.
Use pending while the fight is ongoing.
Use won or lost only when final outcome is known.
```


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