Skip to main content
This page answers the questions merchants ask most often about chargebacks and disputes. Field-level contracts live in the Chargeback API Specification.

​
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 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: 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?

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

​
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: 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. 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?

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.