> For clean Markdown of any page, append .md to the page URL.
> For a complete documentation index, see https://docs.coinflow.cash/llms.txt.
> For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://docs.coinflow.cash/_mcp/server.

# Responding to Disputes

## Overview

When a cardholder disputes a transaction with their bank, the card network opens a chargeback and Coinflow notifies you. You have a fixed deadline to respond. Missing it results in an automatic loss with no appeal path.

This guide walks through the full dispute lifecycle: getting notified, assessing the dispute, building and submitting a response, and what happens after the network decides.

> **Info**
>
> If you have **chargeback indemnification** enabled and the transaction was approved by the protection provider, Coinflow covers the financial liability. No response is required from you - Coinflow handles the dispute process on your behalf. See [About Chargeback Protection](/guides/checkout/payment-security-risk-management/fraud-protection/about-chargeback-protection) for details about how chargeback indemnification works.

---

## Dispute Statuses

A payment moves through the following statuses during a dispute:

| Status            | Meaning                                                                |
| ----------------- | ---------------------------------------------------------------------- |
| `CHARGEBACK`      | Dispute opened - a response is required before `respondByDate`         |
| `CHARGEBACK_WON`  | Network ruled in your favor - funds returned to you                    |
| `CHARGEBACK_LOST` | Network ruled against you - funds debited from your settlement account |

---

## Step 1: Get Notified

Configure the `CardPaymentChargebackOpened` webhook to receive an alert the moment a dispute is opened. The payload includes everything you need to triage:

```json
{
  "event": "CardPaymentChargebackOpened",
  "data": {
    "id": "payment_abc123",
    "chargebackId": "cb_xyz789",
    "reasonCode": "10.4",
    "reasonDescription": "Other Fraud- Card Absent Environment",
    "respondByDate": "2025-06-10T23:59:59Z",
    "subtotal": { "cents": 5000, "currency": "USD" },
    "total": { "cents": 5000, "currency": "USD" }
  }
}
```

> **Warning**
>
> `respondByDate` is the card network's hard deadline - not Coinflow's. Card networks do not grant extensions. Build alerting around this field so your team has sufficient time to gather evidence and respond.

If you don't have webhooks set up yet, see [Configuring Webhooks](/guides/developer-resources/webhooks/configuring-webhooks). If you don't want to set up webhook alerts, Coinflow will also send chargeback and fraud report notifications to all emails added under chargeback emails or fraud emails. [To configure these email settings, navigate to settings.](https://merchant.coinflow.cash/settings)

---

## Step 2: Assess the Dispute

Open the **Chargebacks** section of the merchant dashboard, or call `GET /merchant/chargebacks/{paymentId}` to retrieve dispute details.

Review the following before deciding how to respond:

**Reason code** - Determines the dispute category and what evidence wins. Common categories:

| Category             | Example codes                                  | What the cardholder is claiming                         |
| -------------------- | ---------------------------------------------- | ------------------------------------------------------- |
| Fraud / Unauthorized | Visa 10.1–10.5, MC 4837/4870, Amex F10/F24/F29 | They didn't make or authorize the transaction           |
| Not as Described     | Visa 13.x, MC 4853                             | Goods/service weren't delivered or weren't as described |
| Processing Errors    | Visa 12.x, MC 4834                             | Incorrect amount, duplicate charge, late presentment    |
| Authorization        | MC 4808, Visa 11.x                             | Transaction wasn't properly authorized                  |

See [Chargeback Reason Codes](/guides/checkout/payment-security-risk-management/fraud-protection/chargeback-reason-codes) for the full list.

**Chargeback protection decision** - Check whether the transaction was reviewed by your protection provider:

| Decision                     | What it means                          | Your action                                    |
| ---------------------------- | -------------------------------------- | ---------------------------------------------- |
| `Approved`                   | Protection provider accepted liability | Contact Coinflow - you may not need to respond |
| `Rejected`                   | You are liable                         | Submit a response, or accept the dispute       |
| `NotEnabled` / `NotReviewed` | No protection on this transaction      | Submit a response, or accept the dispute       |

---

## Optional: Accept the Dispute

If you have assessed the dispute and do not intend to contest it, accept it to resolve it immediately rather than leaving it open until `respondByDate`. In the dashboard, open the dispute and click **Accept chargeback**, or call:

```bash
POST /merchant/chargebacks/{paymentId}/accept
```

Accepting a dispute:

* Moves the payment to `CHARGEBACK_LOST`
* Fires the `CardPaymentChargebackLost` webhook
* Skips Steps 3 through 5 - there is nothing left to draft, submit, or await

The payment must currently be in `CHARGEBACK` status; the endpoint returns `400` otherwise. The **Accept chargeback** button appears only on disputes you are liable for - when Coinflow or your protection provider holds the liability, no action is needed from you.

> **Info**
>
> Accepting a dispute moves no additional funds. The disputed amount and the chargeback fee were already debited from your settlement account when the dispute opened, and the chargeback fee is non-refundable regardless of the outcome.

> **Warning**
>
> Accepting a dispute is final. The dispute is recorded as lost and cannot be contested afterwards, even if the card network would later have ruled in your favor. Only accept when you are certain you do not want to respond.

---

## Step 3: Build Your Response

### Option A: AI-Generated Draft (Recommended)

Coinflow can generate a tailored response draft using your merchant profile, transaction data, cardholder details, and reason code:

```bash
POST /merchant/chargebacks/ai/{paymentId}
```

The draft is pre-populated with:

* Merchant name and description
* Transaction date, amount, and payment ID
* Cardholder name, address, card type, and last 4 digits
* Reason code and acquirer information
* 3DS authentication result (if applicable)

Review the draft, edit to add any business-specific context, and save it.

### Option B: Write Your Own

Use `PUT /merchant/chargebacks/{paymentId}/draft` to save a draft response and internal notes at any point before submitting.

### What Evidence to Include

Tailor your evidence to the dispute category:

#### Fraud / Unauthorized (Visa 10.x, MC 4837/4870, Amex F-codes)

* 3DS authentication result and timestamp
* IP address and device fingerprint at time of purchase
* Prior successful transactions from the same customer
* KYC or identity verification records
* Delivery confirmation or access logs (for digital goods)

#### Not as Described / Service (Visa 13.x, MC 4853)

* Terms of service accepted at checkout
* Description of goods or service delivered
* Delivery confirmation or download/access logs
* Customer communication history showing the issue was addressed

#### Processing Errors (Visa 12.x, MC 4834)

* Proof of correct amount charged (transaction receipt)
* Evidence that no duplicate charge occurred
* Proof of timely presentment (within 30 days of transaction)

#### Authorization Issues (MC 4808, Visa 11.x)

* Authorization approval code from the processor
* Transaction receipt showing authorization was obtained

> **Warning**
>
> Responses must be **20 pages or fewer** - this is a card network requirement enforced by Coinflow's API.

---

## Step 4: Submit Before the Deadline

Once your response is ready, submit it from the dashboard or via API:

```bash
POST /merchant/chargebacks/{paymentId}/respond
```

After submission:

* `merchantRespondedAt` is recorded on the dispute record
* The response is forwarded to the card network for review
* The dispute status remains `CHARGEBACK` until the network decides

> **Info**
>
> Card networks typically allow 20–45 days from dispute opening. The `respondByDate` field reflects the actual network deadline. Submit as early as possible - do not wait until the deadline.

---

## Step 5: Await the Decision

You'll receive a webhook (or email) when the outcome is final:

**`CardPaymentChargebackWon`** - The network ruled in your favor. Coinflow automatically credits your settlement account for the disputed amount.

**`CardPaymentChargebackLost`** - The network ruled against you. Coinflow automatically debits the disputed amount from your settlement account.

---

## Step 6: Post-Dispute Actions

#### If you won

No action required. If you suspect the dispute was abusive, consider flagging the customer in your platform and reviewing their transaction history.

#### If you lost

Review what evidence was missing or insufficient. Common reasons for losing:

* No 3DS authentication on a fraud dispute
* Missing delivery confirmation on a service dispute
* Responding after the deadline

If you're seeing a pattern of losses, contact the Coinflow integrations team about enabling or improving chargeback protection coverage.

---

## Quick Reference

| Action                   | Dashboard                | API Endpoint                                     |
| ------------------------ | ------------------------ | ------------------------------------------------ |
| View all disputes        | Chargebacks page         | `GET /merchant/chargebacks`                      |
| View dispute details     | Click dispute row        | `GET /merchant/chargebacks/{paymentId}`          |
| Generate AI draft        | Draft → Generate         | `POST /merchant/chargebacks/ai/{paymentId}`      |
| Save draft & notes       | Draft → Save             | `PUT /merchant/chargebacks/{paymentId}/draft`    |
| Submit response          | Submit button            | `POST /merchant/chargebacks/{paymentId}/respond` |
| Accept (concede) dispute | Accept chargeback button | `POST /merchant/chargebacks/{paymentId}/accept`  |
| Export for reporting     | Export CSV               | `GET /merchant/chargebacks/csv`                  |

---

## Related Pages

* [About Chargeback Protection](/guides/checkout/payment-security-risk-management/fraud-protection/about-chargeback-protection)
* [Chargeback Reason Codes](/guides/checkout/payment-security-risk-management/fraud-protection/chargeback-reason-codes)
* [How Chargeback Protection Works](/guides/checkout/payment-security-risk-management/fraud-protection/how-chargeback-protection-works)
* [Improving Chargeback Protection Acceptance Rates](/guides/checkout/payment-security-risk-management/fraud-protection/improving-chargeback-protection-acceptance-rates)