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.

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 for details about how chargeback indemnification works.

Dispute Statuses

A payment moves through the following statuses during a dispute:

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:

{
  "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" }
  }
}

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

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:

See Chargeback Reason Codes for the full list.

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

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:

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.

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.

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:

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

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:

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

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

Related Pages

• About Chargeback Protection
• Chargeback Reason Codes
• How Chargeback Protection Works
• Improving Chargeback Protection Acceptance Rates