CheckoutPayment Security & Risk ManagementFraud Protection

Responding to Disputes

A step-by-step guide for merchants on how to respond to chargebacks opened against their transactions.

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. You can ignore the dispute and 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:

StatusMeaning
CHARGEBACKDispute opened - a response is required before respondByDate
CHARGEBACK_WONNetwork ruled in your favor - funds returned to you
CHARGEBACK_LOSTNetwork ruled against you - funds debited from your wallet

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:

1{
2  "event": "CardPaymentChargebackOpened",
3  "data": {
4    "id": "payment_abc123",
5    "chargebackId": "cb_xyz789",
6    "reasonCode": "10.4",
7    "reasonDescription": "Other Fraud- Card Absent Environment",
8    "respondByDate": "2025-06-10T23:59:59Z",
9    "subtotal": { "cents": 5000, "currency": "USD" },
10    "total": { "cents": 5000, "currency": "USD" }
11  }
12}

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:

CategoryExample codesWhat the cardholder is claiming
Fraud / UnauthorizedVisa 10.1–10.5, MC 4837/4870, Amex F10/F24/F29They didn’t make or authorize the transaction
Not as DescribedVisa 13.x, MC 4853Goods/service weren’t delivered or weren’t as described
Processing ErrorsVisa 12.x, MC 4834Incorrect amount, duplicate charge, late presentment
AuthorizationMC 4808, Visa 11.xTransaction wasn’t properly authorized

See Chargeback Reason Codes for the full list.

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

DecisionWhat it meansYour action
ApprovedProtection provider accepted liabilityContact Coinflow - you may not need to respond
RejectedYou are liableSubmit a response
NotEnabled / NotReviewedNo protection on this transactionSubmit a response

Step 3: Build Your Response

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:

  • 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)
  • 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
  • Proof of correct amount charged (transaction receipt)
  • Evidence that no duplicate charge occurred
  • Proof of timely presentment (within 30 days of transaction)
  • 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 wallet for the disputed amount.

CardPaymentChargebackLost - The network ruled against you. Coinflow automatically debits the disputed amount from your wallet.

Step 6: Post-Dispute Actions

1

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.

2

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

ActionDashboardAPI Endpoint
View all disputesChargebacks pageGET /merchant/chargebacks
View dispute detailsClick dispute rowGET /merchant/chargebacks/{paymentId}
Generate AI draftDraft → GeneratePOST /merchant/chargebacks/ai/{paymentId}
Save draft & notesDraft → SavePUT /merchant/chargebacks/{paymentId}/draft
Submit responseSubmit buttonPOST /merchant/chargebacks/{paymentId}/respond
Ignore (protected txn)Ignore buttonPUT /merchant/chargebacks/{paymentId}/ignore
Export for reportingExport CSVGET /merchant/chargebacks/csv
Get chargeback rateDashboard statsGET /merchant/chargebacks/rate