> ## Documentation Index > Fetch the complete documentation index at: https://waffo.com/docs/llms.txt > Use this file to discover all available pages before exploring further. # Chargeback & Dispute FAQ > Answers to the most common merchant questions about chargebacks: how notifications arrive, what to do when a chargeback opens, how to submit representment evidence, deadlines and status flow, and why disputed orders cannot be refunded. This page answers the questions merchants ask most often about chargebacks and disputes. Field-level contracts live in the [Chargeback API Specification](/docs/api-reference/introduction). ## How am I notified when a chargeback opens? Waffo pushes a webhook (`eventType: CHARGEBACK_NOTIFICATION`) to the `notifyURL` you provided. The payload carries the full chargeback object — the same structure returned by `/api/v1/chargeback/inquiry`. * A notification is sent whenever the chargeback **status changes**; no notification is sent for `UNDER_REVIEW`. * Respond with `message: "success"` after processing. If Waffo receives `failed` or `unknown`, Waffo retries the notification on a fixed back-off schedule; see [Webhook retry](/docs/en/developer-docs/webhook/retry) for the attempts and intervals. You can also poll `/api/v1/chargeback/list` (filter by status or `lifeCycle`; the time window filters on creation time and must be within 3 months) and fetch full detail — including `message` and `evidence` — with `/api/v1/chargeback/inquiry`. ## What happens to my funds when a chargeback is created? The chargeback `amount` and the chargeback fee (`feeAmount`) are debited when the chargeback is **created**, not when it closes. If the case later closes in your favour (`CASE_WON`, `CANCELED`, `SETTLED`), the amount is refunded and the fee is retained. When a case escalates to Second Cycle, a further fee is debited as the Second Cycle case opens; and because a Second Cycle normally follows a First Cycle you **won** (the amount was already returned to you), the disputed amount is debited **again** for the Second Cycle. Only if the First Cycle was not closed in your favour is the Second Cycle debit limited to the fee. ## I fully refunded the order. Why was it still charged back? A refund does not exempt an order from the chargeback process. The issuing bank does not see that you already refunded the user through Waffo, so the case proceeds as a normal chargeback. If the defense ultimately fails, you end up bearing the refunded amount, the chargeback amount and the chargeback fee. Such cases are usually strong candidates for representment: submit your refund confirmation as evidence instead of accepting the case. ## What happens when a case escalates to Second Cycle (Pre-Arbitration)? Pre-Arbitration is the issuer's follow-up after you won the First Cycle: the issuer rejects your representment result and asks for the funds again. When the Second Cycle case opens, a further chargeback processing fee is debited — it follows the same contractual fee rule as the First Cycle — and the disputed amount, which was returned to you when you won the First Cycle, is debited again. If the issuer accepts your defense (`CASE_WON`), the disputed amount is credited back. You have two options: * **Accept** — concede the case; the funds go to the cardholder. This is the most common choice, taken to avoid arbitration costs. * **Defend** — if the issuer still does not concede, the case escalates to **Arbitration**, the card scheme's final and binding ruling. At that stage you cannot submit any new material, and the losing party bears a substantial arbitration fee. Most card schemes also do not allow evidence in Pre-Arbitration that was not presented in the First Cycle. ## When does a chargeback debit appear in my settlement? Chargeback settlement is always triggered **after the original payment order has settled**, because it reuses the original order's settlement exchange rate: * If the original order is already settled, the chargeback is settled on the next settlement day after the case event is confirmed. * If the original order has not settled yet, the chargeback is settled together with the original order on its settlement day. In your settlement report these entries appear with transaction type `CHARGEBACK`; the settled amount can be negative (a debit when a case opens) or positive (a repayment when a case is won). ## How is the chargeback fee determined? The chargeback fee comes from your merchant contract and is configured per merchant account (MID). It is applied automatically when a case is created and cannot be adjusted case by case; Pre-Arbitration (Second Cycle) cases use the same fee rule as First Cycle chargebacks. The fee is a contract term, not a per-case setting — contact your Waffo account manager to discuss it. ## What should I do when I receive a chargeback? 1. Read `chargebackStatus`, `reasonCode`, `reason` and `expiryDateTime` from the notification (or from `/api/v1/chargeback/inquiry`). 2. Decide: **defend** the case with evidence, or **accept** it via `/api/v1/chargeback/accept`. 3. If you defend, submit evidence before `expiryDateTime` (see below). If no evidence is submitted before the deadline, the case becomes `EXPIRED` and the funds are not refunded. Accepting is **irreversible**: the case closes, you are not refunded, and no further evidence can be submitted. Accept is callable while the case is waiting on you — `EVIDENCE_REQUIRED`, `ACTION_REQUIRED` or `SECOND_CYCLE_RESPONSE_REQUIRED` — and rejected once the case is in a final status; there is no additional debit, because the amount was already booked when the case was created. A note on timing: chargeback amounts and fees are booked against you when the case is created, but the money moves with your next settlement cycle rather than instantly. Your settlement statement is the place to reconcile them. ## How do I submit representment evidence? For a First Cycle case in `ACTION_REQUIRED`: 1. Upload each evidence file with `/api/v1/chargeback/file/upload` (`multipart/form-data`, part name `file`; JPG, JPEG, PNG or PDF; max 10 MB). The response returns a `fileId` — it contains a slash, so URL-encode it when used as a query parameter. 2. Call `/api/v1/chargeback/update` with the file IDs (comma-separated) in `message.documents` or `evidence.othersFile`. At least one evidence file is required. Re-submitting a field replaces its previous value; omitted fields are unchanged. 3. On success the status becomes `UNDER_REVIEW` — this means Waffo accepted the submission and forwards it to the payment channel; it is **not** a channel decision. For a Second Cycle case in `SECOND_CYCLE_RESPONSE_REQUIRED` (Pre-Arbitration), evidence files are **not** accepted: call `/api/v1/chargeback/update` with `merchantId` and `chargebackId` (optionally `message.notes` as a defense note) to defend, or accept the case. Update calls after `expiryDateTime` are rejected. The file upload and download APIs are authenticated by `X-API-KEY` only and do not participate in RSA signing. ## What evidence should I prepare for different dispute reasons? Whatever the reason code, effective representment evidence answers three questions: | Dimension | Question | Typical evidence | | - | - | - | | Transaction authenticity | Did the transaction genuinely happen? | Authorization result, device / IP information, account activity | | Fulfillment | Was the product or service delivered? | Delivery confirmation, usage or access logs, invoices / receipts | | Policy compliance | Were refunds and cancellations handled per your published policy? | The policy as shown at checkout, the user's acknowledgment, communication records | Each case carries an **Evidence Requirements** list generated from its dispute reason, marking items as mandatory or recommended. A submission missing mandatory items is blocked, so review the list before uploading. ## What are the chargeback statuses? | Status | Meaning | Funds | | - | - | - | | `ACTION_REQUIRED` | Submit evidence before `expiryDateTime` | Amount and fee are booked against you | | `UNDER_REVIEW` | Evidence submitted, under channel review | — | | `EVIDENCE_REQUIRED` | The channel asked for additional evidence after review | — | | `SECOND_CYCLE_RESPONSE_REQUIRED` | Pre-Arbitration: defend or accept; no evidence files | Fee debited; the amount is debited again if the First Cycle had been won | | `ESCALATE_TO_2ND_CYCLE` | Escalated to Second Cycle | No further debit | | `CASE_WON` | Channel ruled for you | Amount refunded, fee retained | | `CANCELED` | Withdrawn by the channel or cardholder | Amount refunded, fee retained | | `SETTLED` | Settled offline | Amount refunded, fee retained | | `CASE_LOST` | Channel ruled against you | Not refunded | | `ACCEPTED` | You accepted the chargeback | Not refunded | | `EXPIRED` | No evidence before `expiryDateTime` | Not refunded | A dispute has two rounds, tracked by `lifeCycle`: `FIRST_CYCLE` and `SECOND_CYCLE` (Pre-Arbitration); the two cases are linked through `relevantChargebackId`. `CASE_LOST`, `ACCEPTED` and `EXPIRED` are not absolutely final: the only way they change is by the issuer escalating the case to Second Cycle. `CASE_WON`, `CANCELED`, `SETTLED` and `ESCALATE_TO_2ND_CYCLE` never change. Always treat the latest notification as authoritative. ## What is the deadline for submitting evidence? Each case carries its own `expiryDateTime` (ISO 8601, UTC). There is no single fixed window — read it per case. Submissions after `expiryDateTime` are rejected, and a case with no evidence by then becomes `EXPIRED`. ## Can I refund an order that has a chargeback dispute? No. A refund request against an order with a chargeback dispute is rejected with error `A0019` ("Refund not allowed due to a chargeback dispute") — see [Error codes](/docs/en/developer-docs/tools-and-references/developer-tools/error-codes). The chargeback flow itself decides whether the disputed amount is returned. ## Does Waffo send chargeback summary emails? Yes — two daily emails, and no monthly report: * **Previous-day disputes report** — sent only when new cases were recorded the day before; no email on a given day simply means nothing new was recorded. The attachments are split into two lists: **Customer Disputes** and **Chargebacks**. If you are enrolled in the Chargeback Alert service, the report also includes an alert list with each alert's refund status and expiry time. * **Daily volume report** — the day's counts of chargeback alerts, chargebacks and customer disputes, with a link into the Portal. Both go to the same recipients — see *Which email address do dispute notifications go to?* below. ## How am I notified when Chargeback Alert auto-refunds an order? If the alert service has already refunded an order, a refund you submit for the same order is rejected with `A0039` — that is the signal to check the order rather than retry. Whether your account receives alert notifications, and in what form, depends on how Chargeback Alert is set up for you; confirm the details with integration support before building against them. What is consistent is the downstream effect: when an alert relates to a subscription, Waffo can cancel that subscription automatically — see the next question. If the automatic refund fails, Waffo processes the case manually and contacts you if it still cannot be completed; an unresolved alert may develop into a formal chargeback. ## Can a chargeback or fraud signal automatically cancel the user's subscription? Yes, as an opt-in capability — contact Waffo to enable it. It is configured per merchant account and per signal type (chargeback alert, chargeback, reported fraud, customer dispute), and is **off by default**. When enabled, Waffo cancels the affected subscription automatically as soon as the signal is recorded, without waiting for you to call the cancel API: * Only the disputed subscription is cancelled — the user's other subscriptions are untouched. * Payments already collected are not refunded automatically; the capability only stops future deductions. * The cancellation is final and cannot be reversed. * Your own merchant-initiated refunds never trigger it. Notifications arrive in order: for alert and chargeback signals you first receive the usual chargeback notification, then a `SUBSCRIPTION_STATUS_NOTIFICATION` whose status indicates the subscription was cancelled by the platform (`PLATFORM_CANCELLED`), with a `cancelReason` naming the triggering signal. ## My settlement bill has a Chargeback Alert line. What is it? Chargeback Alert service fees are cleared as their own transaction type, **Chargeback Alert**. Any alert fee not yet settled in the period enters clearing alongside your `PAYMENT`, `REFUND` and `CHARGEBACK` rows, appears in both the settlement detail report and the summary report, and is deducted from the settlement amount. If the fee is billed in a currency other than your settlement currency, it is converted to the settlement currency before being deducted. Alert fees also count towards the net-amount test that decides whether a settlement happens at all: a period whose alert fees and chargebacks outweigh its incoming payments settles nothing and carries forward to the next period — see [Settlement Cycle & Calendar](/docs/en/support/settlement-cycle-faq). ## Why was I billed for an alert on an order I had already refunded? Because every chargeable alert is billed once it is delivered and matched to an order. Billing reflects delivery, not whether the alert actually prevented a chargeback — so an alert can be billed even where no chargeback was ever possible: | Situation | Alert fee | Chargeback fee | | - | - | - | | The alert arrived and the order was refunded in response | Charged | — | | You had already refunded the order before the alert arrived | Charged | — | | The original transaction had failed, so no chargeback was possible | Charged | — | | The alert arrived after the order had already gone to chargeback | Charged | Also charged | | No action was taken and the case became a chargeback | Charged | Also charged | | The alert could not be matched to any order in Waffo | Not charged | — | The last row is the only case that is free of charge by rule. Where an alert case ends up in chargeback as well, the alert fee and the chargeback fee are both due — they are separate charges for separate events. ## Where do I see the refund that an alert triggered? On your side it is an ordinary refund. It clears through the normal refund flow and appears in your transaction records and settlement reports as a regular `REFUND` row, with nothing marking it as alert-initiated — you cannot (and do not need to) tell it apart from a refund you submitted yourself. Once an order has been refunded through the alert flow, Waffo makes sure the same order does not also produce a chargeback. That is why your own refund request for such an order comes back with `A0039`: the money has already gone back to the cardholder. ## Which email address do dispute notifications go to? Customer dispute, chargeback and chargeback alert emails — the new-dispute notification and both daily reports — are sent to the Portal users of your merchant account who hold the **Super Admin**, **Admin** or **Dispute Manager** role. There is no separate recipient list: to add, replace or remove a recipient (for example when your dispute handler changes), add the person as a Portal user with one of those roles, or change their role, in the Portal's user management. If nobody holds one of those roles, the emails are not sent. ## What is the difference between a Customer Dispute and a Chargeback? They are two different case types, not two names for the same thing. Every dispute record carries a `disputeType` of either `CUSTOMER_DISPUTE` or `CHARGEBACK`, and the two types have their own status sets, their own effect on your money, and their own menu in the Portal — **Customer Disputes** and **Chargebacks** are separate lists that open a shared detail page. | | Customer Dispute | Chargeback | | - | - | - | | What it is | The customer raised a complaint about the payment and is waiting for your response | The issuing side formally reversed the payment | | Status set | `EVIDENCE_REQUIRED` / `UNDER_REVIEW` / `ESCALATED` / `CLOSED` | `ACTION_REQUIRED` … `CASE_WON` / `CASE_LOST` etc. (see the status table above) | | Effect on funds | None by itself — the case does not book an amount or a fee against you | Amount and fee are booked when the case is created | | Can you still refund the order? | **Yes** — a customer dispute does not lock refunds, and refunding is often how the case is resolved | No — refunds are rejected with `A0019` | | Webhook | No — `CHARGEBACK_NOTIFICATION` is sent for chargebacks only | Yes, on every status change | | API visibility | Not returned by `/api/v1/chargeback/list` or `/inquiry` — those are filtered to chargebacks | Yes | | Where you see it | Portal **Customer Disputes**, and the Customer Disputes attachment of the dispute reports | Portal **Chargebacks**, webhook, chargeback API, settlement reports | The practical consequence: a customer dispute is a conversation you can still settle commercially, and it produces no webhook — so if you rely only on webhooks you will never learn about it. Watch the Portal list (the tab carries a count badge) or the daily dispute report. ## How does a Customer Dispute progress, and what can I do at each step? | Status | Meaning | What you can do | | - | - | - | | `EVIDENCE_REQUIRED` | The case was opened, or the channel asked for more material. `ACTION_REQUIRED` carries the same meaning — both mean your response is needed | Submit evidence, reply, or close the dispute | | `UNDER_REVIEW` | You submitted evidence and it is being reviewed | Reply; you may still be moved back to `EVIDENCE_REQUIRED` if more material is wanted | | `ESCALATED` | A chargeback was raised on the same payment — the case continues as that chargeback | No further status change on this record; work the chargeback instead | | `CLOSED` | The case is finished, closed by you or by the channel | Nothing, unless the customer complains again | Notes that follow from the state machine: * **Submitting evidence requires at least one file.** The submission moves the case to `UNDER_REVIEW`; evidence can only be edited while the case is in `EVIDENCE_REQUIRED` or `UNDER_REVIEW`. * **Closing is available only from `EVIDENCE_REQUIRED` or `UNDER_REVIEW`** and is recorded as closed by the merchant. An `ESCALATED` case cannot be closed. * **A `CLOSED` customer dispute can reopen.** If the customer complains again, the case returns to `UNDER_REVIEW` rather than starting over as a new dispute. * **Escalation only happens while the case is open.** If a chargeback arrives on a payment whose customer dispute is still open, that dispute flips to `ESCALATED` and the chargeback record links back to it through `relevantCustomerDisputeId`. A dispute already `CLOSED` is left alone. * **Expiry behaves differently from a chargeback.** Passing the evidence deadline on a customer dispute only flips the separate **Expire Status** column from `ACTIVE` to `EXPIRED`; the dispute status is unchanged and the case stays workable. On a chargeback, the deadline turns the case itself into `EXPIRED` and the amount is not refunded. Where the payment method supports it, the detail page also offers **Reply Message** — a free-text reply with optional attachments that goes into the dispute conversation without changing the status, and an unread counter for messages from the customer's side. ## Can I reply to repetitive customer disputes automatically? Yes, per payment method, on the **Dispute Config** tab of the Customer Disputes page. When a customer's complaint is recorded for the first round, Waffo posts your configured message as the first reply on your behalf — typically to point the customer at your support channel while you work the case. The tab appears only for accounts whose contracted payment methods support dispute replies and for users holding the auto-reply permission; **if you can see the tab, the feature is available to you.** Auto-reply covers customer disputes only, never chargebacks. How the rules match and behave: * **The only matching dimension is the payment method** of the original order. There is no matching on dispute reason, amount or customer. The currency shown next to each rule is derived from the payment method for information — it is not a second matching key. * **One rule per payment method.** Creating a second rule for the same payment method is rejected, and the payment method cannot be changed after the rule is created — edit the message or the status instead. * **The dropdown only offers payment methods you have contracted that also support dispute replies.** A payment method missing from the list cannot be configured. * **Only an Active rule fires.** There is no delete: set a rule to **Inactive** to stop it. * The reply does not change the dispute status and does not count as evidence submission — you still need to submit evidence or close the case. Fields and history: a rule holds `paymentMethodId` (shown as **Apply to**), `messageContent` (up to 256 characters) and `status` (Active / Inactive). The Dispute Config list is the configuration history — every rule for your account, newest first, with its payment method, currency, message, status and creation time, each editable in place. These rules are created, edited and switched on or off only on the Dispute Config tab of the Portal; there is no signed public API for auto-reply configuration. This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.