> ## 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 Field Reference

> A field dictionary for reading chargebacks in the Merchant Portal and in your settlement statement: the four CHARGEBACK Event Types and their signs, the Compulsory Channel Review flag, every Customer Dispute and Chargeback timeline event, which events move the unread counter, the 26 columns of the chargeback CSV export, how Dispute Amount is derived, the chargeback fee currency, and the Alert Status values in the daily dispute report.

This is the field dictionary behind
[Chargeback & Dispute FAQ](/docs/en/support/chargeback-faq) — use that page for how the process
works and what to do, and this page when you are staring at a value in the Portal, in a
CSV or in a settlement line and need to know what it means. Evidence selection is on
[Chargeback evidence guide](/docs/en/support/chargeback-evidence-guide).

## My settlement detail has a `CHARGEBACK` row. What are the Event Types and which way does the money go?

For chargeback movements `Transaction Type` is always `CHARGEBACK`. The **`Event Type`**
column is what tells you whether the line is a debit or a repayment, and whether it
carries the amount, the fee, or both:

| `Event Type` | Raised by | Order amount on the line | Fee on the line | Settlement amount |
| - | - | - | - | - |
| `FIRST_CB_PRE_DEDUCT` | A first-cycle chargeback opened against you | The disputed amount | The chargeback fee | **Negative** — `−(amount + fee)` |
| `FIRST_CB_AMOUNT_REFUND` | The first cycle closed in your favour | The disputed amount | Zero | **Positive** — `+amount` |
| `SECOND_CB_PRE_DEDUCT` | A second cycle (Pre-Arbitration) opened | **Zero** — no second debit of the amount | The chargeback fee | **Negative** — `−fee` only |
| `SECOND_CB_AMOUNT_REFUND` | The second cycle closed in your favour | The disputed amount | Zero | **Positive** — `+amount` |

Reading the pattern rather than the amounts is the reliable way round:
`*_PRE_DEDUCT` always takes money, `*_AMOUNT_REFUND` always gives it back, and the fee
only ever appears on a `PRE_DEDUCT` line. A case that opens, escalates and is finally won
therefore produces three or four separate `CHARGEBACK` rows across different settlement
dates — not one net row.

Which case statuses produce which event:

| Case status when the settlement event is raised | Event Type |
| - | - |
| `ACTION_REQUIRED`, `EVIDENCE_REQUIRED`, `UNDER_REVIEW`, `SECOND_CYCLE_RESPONSE_REQUIRED` | `PRE_DEDUCT` for the matching cycle |
| `CASE_WON`, `SETTLED`, `CANCELED` | `AMOUNT_REFUND` for the matching cycle |
| `CASE_LOST` | `PRE_DEDUCT` — the amount stays with the cardholder, nothing is returned |

Note the consequence for `CASE_LOST`: there is no separate "loss" event. You were already
debited when the case opened, so losing produces no new line — the absence of an
`AMOUNT_REFUND` row *is* the loss. Timing and the settlement-day rule are in
[Chargeback & Dispute FAQ](/docs/en/support/chargeback-faq).

Older records can carry an empty `Event Type`. Those predate this breakdown and are always
debits.

## What is `Compulsory Channel Review` on the chargeback detail page?

`compulsoryChannelReview` is a true/false flag on the case, returned to the Portal, that
records whether the payment side mandates its own review of the case. Chargebacks are
created with it set to **true**; customer disputes raised through an in-app complaint flow
are created with it set to **false**.

Read it as an expectation-setter for the outcome: where it is true, the case is decided by
the reviewing side and your submission is input to that review, not a resolution of it.
Where it is false, resolving the case with the customer directly is a real option, and
closing the dispute is how that resolution is recorded.

What actually gates the **Close** action is the case status, not this flag: closing is
available from `EVIDENCE_REQUIRED`, `ACTION_REQUIRED` and `UNDER_REVIEW`, and an
`ESCALATED` case cannot be closed. So if Close is greyed out, check the status first.

## What does each event in a Customer Dispute timeline mean?

The timeline records 11 event values. Anything not in this list is not a timeline event.

| Event | When it appears | What you do |
| - | - | - |
| `CREATE_DISPUTE` | The dispute was opened against a payment | Read the reason, decide whether to defend, reply or refund |
| `MERCHANT_SUBMIT_EVIDENCE` | Your evidence submission was accepted; the case moves to `UNDER_REVIEW` | Nothing — wait for review |
| `MORE_EVIDENCE_REQUIRED` | More material was asked for; the case returns to `EVIDENCE_REQUIRED` | Upload the additional material |
| `DISPUTE_ESCALATED` | A chargeback was raised on the same payment; this record stops progressing | Work the linked chargeback instead |
| `CLOSE_DISPUTE` | The case was closed — by you, or by the reviewing side | Nothing, unless the customer complains again |
| `NOTIFY_OVERDUE` | The case was flagged as approaching its evidence deadline | Submit before the deadline |
| `EXPIRED` | The evidence deadline passed | The case is **still workable** — see the expiry question below |
| `USER_RESPONSE` | The customer replied in the dispute conversation | Read it; reply if useful |
| `PLATFORM_RESPONSE` | A response arrived from the reviewing side | Read it; it often specifies what is missing |
| `MERCHANT_RESPONSE` | Your own reply was posted | Nothing |
| `USER_CREATE_COMPLAINT` | The customer raised a further complaint — this is what reopens a `CLOSED` case | Respond; the case returns to an open state |

## What does each event in a Chargeback timeline mean?

14 event values, a different set from customer disputes:

| Event | When it appears | What you do |
| - | - | - |
| `CREATE_DISPUTE` | The chargeback was created | Read `reasonCode`, `reason` and `expiryDateTime`; decide defend or accept |
| `MERCHANT_SUBMITS_EVIDENCE` | Your evidence submission was accepted | Wait |
| `AUTO_SUBMITS_EVIDENCE` | Evidence was submitted automatically on your behalf under your configured handling strategy | Verify what went in — you are on record as having defended |
| `MORE_EVIDENCE_REQUIRED` | Additional material was asked for after review | Upload it before the deadline |
| `NOTIFY_OVERDUE` | The case was flagged as approaching its deadline | Submit or accept |
| `MERCHANT_ACCEPTED_DISPUTE` | You accepted the case | Nothing — this is irreversible |
| `MERCHANT_WON_DISPUTE` | Ruled in your favour | Expect an `AMOUNT_REFUND` settlement line |
| `MERCHANT_LOST_DISPUTE` | Ruled against you | Nothing further on this cycle; a second cycle may follow |
| `CHARGEBACK_SETTLED` | The case was settled outside the normal flow | Amount returned, fee retained |
| `CHANNEL_CLOSE_DISPUTE` | The case was withdrawn on the raising side | Amount returned, fee retained |
| `CHARGEBACK_EXPIRED` | No response before the deadline | Nothing — the amount is not returned |
| `ESCALATED_TO_2ND_CYCLE` | The case escalated to Pre-Arbitration | A new second-cycle record now exists; work that one |
| `CREATE_SECOND_CYCLE_DISPUTE` | The second-cycle record was created | Defend or accept; **no evidence files are accepted** in the second cycle |
| `MERCHANT_DEFENDS_SECOND_CYCLE` | You chose to defend the second cycle | Understand the arbitration exposure before doing this |

`AUTO_SUBMITS_EVIDENCE` and `CREATE_SECOND_CYCLE_DISPUTE` are the two events that can
appear without any action from you. If you have set a blanket handling strategy, these are
where you find out it fired.

## Which timeline events increase the unread counter?

Exactly three, and all three are inbound messages rather than status changes:

* `USER_RESPONSE`
* `PLATFORM_RESPONSE`
* `USER_CREATE_COMPLAINT`

Your own `MERCHANT_RESPONSE` does not increment it, and neither does any status change,
any evidence submission or any deadline event. So an unread count is always *someone said
something to you*, never *something happened to the case* — a case can move all the way to
a final status without the counter ever moving. Do not use the counter as an activity
indicator; use the timeline.

## How do I export my chargeback detail, and does it go through the Reports tab?

The Chargebacks list has its own export, and unlike most Portal exports it is a **direct
synchronous download**: the file is streamed to your browser when you click, and **no task
row appears in any Reports tab**. If you are looking for it in
[Exports & report downloads](/docs/en/support/export-center-faq), it is not there — that page
covers the queued exports, this one is not queued.

The file name is:

```
chargebacks_{merchant id}_{from}_{to}.csv
```

Both dates are `YYYYMMDD` in UTC+8 and come from the created-time filter you had applied.
The export follows your current list filters, so filter first, export second.

## What are the columns in the chargeback CSV export?

26 columns, in this order:

| # | Header | What it holds |
| - | - | - |
| 1 | `Chargeback Id` | The case id |
| 2 | `Life Cycle` | `FIRST_CYCLE` or `SECOND_CYCLE` |
| 3 | `Relevant Chargeback Id` | The other cycle's case id |
| 4 | `Original Order Id` | Waffo's id for the disputed order |
| 5 | `Original Payment Request id` | Your payment request id for that order |
| 6 | `Subscription Request` | Your subscription request id, for subscription cases |
| 7 | `Related Subscription Id` | Waffo's subscription id, for subscription cases |
| 8 | `Merchant User Id` | Your id for the buyer |
| 9 | `Merchant Order Id` | Your order id |
| 10 | `Merchant Id` | Your MID |
| 11 | `Sub Merchant Id` | Sub-MID, where you use one |
| 12 | `Chargeback Amount` | The amount disputed **against you**, in the order currency — see below |
| 13 | `Chargeback Currency` | Currency of column 12 |
| 14 | `Chargeback Reason Code` | The reason code on the case |
| 15 | `Chargeback Reason` | The reason text |
| 16 | `Transaction Type` | `CHARGEBACK` |
| 17 | `Country/Region` | Country of the payment |
| 18 | `Payment Method Type` | For example `CREDITCARD` |
| 19 | `Payment Method` | The specific method used |
| 20 | `Chargeback Status` | The case status |
| 21 | `Settlement Status` | Whether the movement has cleared into a settlement — see below |
| 22 | `Created Datetime(UTC+8)` | When the case was created |
| 23 | `Updated Datetime(UTC+8)` | When the case last changed |
| 24 | `Expiry Datetime(UTC+8)` | The evidence deadline |
| 25 | `Chargeback Fee Amount` | The chargeback fee booked on the case |
| 26 | `Chargeback Fee Currency` | Currency of column 25 — your configured fee currency, see below |

Every header is unique, so a parser keyed on header text is safe. Note that the export
says **Chargeback** where the Portal detail page says **Dispute** for the same values —
columns 12 and 25 are the disputed amount and the fee respectively, not two amounts.

## Column 21 says the case is not settled yet. Has the money been taken or not?

That is exactly what `Settlement Status` is for, and it is the column to check when the
case status and your bank balance disagree.

`Chargeback Status` and `Settlement Status` answer different questions and move at different
times:

| Column | Question it answers |
| - | - |
| `Chargeback Status` | Where the case stands with the reviewing side |
| `Settlement Status` | Whether the resulting money movement has been through a settlement yet |

A chargeback is booked against you when the case opens, but it only reaches a settlement
statement once the **original payment order has settled**, because it reuses that order's
settlement exchange rate. So a case can sit at `ACTION_REQUIRED` with the amount already
booked and `Settlement Status` still showing unsettled — the debit is coming, on the
settlement day of the original order or the next settlement day after that. Pair this
column with the `Event Type` table above to reconcile a specific `CHARGEBACK` line.

## Why is `Dispute Amount` different from what the cardholder disputed?

Because they are two different figures, and the Portal shows you yours.

The amount raised on the payment side is denominated in the **payment currency** of the
original transaction. The `Dispute Amount` you see — and the amount you are actually
debited — is the **merchant share, expressed in the order currency**:

1. Any buyer-side fee on the original payment is funded by Waffo, not by you, and is
   excluded from your disputable balance.
2. Your share of the disputed amount is taken in proportion to your share of what the
   buyer paid, and any remainder is borne by Waffo.
3. That share is converted to the order currency and **rounded down (FLOOR) to 2 decimal
   places**, so the figure is never rounded up against you. A sub-cent remainder stays
   with Waffo.

Consequences worth knowing:

* On a cross-currency order, your `Dispute Amount` will not equal the figure quoted on the
  payment side, and the difference is not an error.
* Where the order was already partly or fully refunded, your remaining disputable balance
  is lower, and your share is capped by it.
* Your `Dispute Amount` can never exceed the order amount.

The proportional split itself — how much of a given dispute falls to you versus to Waffo —
is a funding rule, not a self-service setting; ask support if a specific case does not
reconcile.

## What currency is my chargeback fee in? It is not USD.

The chargeback fee currency comes from **your** merchant configuration, not from a global
default, and it is returned on the case as `feeCurrency` alongside `feeAmount`. It is not
guaranteed to match your settlement currency and it is not guaranteed to be USD.

When the fee currency differs from your settlement currency, the fee is converted to the
settlement currency at settlement time, using the settlement-side rate for that
settlement — the same rate basis as the rest of that settlement, not a rate captured on
the day the case opened. Where the two currencies are the same, no conversion happens.

So if your statement shows a chargeback fee in a currency you did not expect, that is your
configured fee currency showing through. The fee amount itself is a contract term — see
[Chargeback & Dispute FAQ](/docs/en/support/chargeback-faq).

## How do I find the cases that are about to run out of time?

Both the Chargebacks and Customer Disputes lists carry an **expiring soon** filter, which
returns the open cases whose evidence deadline falls within the next **3 days**. That is
the supported way to triage by deadline; each case still carries its own
`expiryDateTime`, and that value is authoritative for the individual case.

## What happens when the evidence deadline passes?

The two case types behave differently, and this is the most commonly misread difference
between them:

| | Customer Dispute | Chargeback |
| - | - | - |
| What changes at the deadline | Only a separate **Expire Status** column flips from `ACTIVE` to `EXPIRED` | The case **status itself** becomes `EXPIRED` |
| Case status after the deadline | Unchanged — stays `EVIDENCE_REQUIRED` / `ACTION_REQUIRED` / `UNDER_REVIEW` | `EXPIRED`, a final status |
| Can you still submit? | **Yes** — the case stays workable | No |
| Money | Unaffected by expiry itself | The disputed amount is not returned |

So an expired customer dispute is a nudge, not a closed door: submit late material and
keep working the case. An expired chargeback is a loss. When you are prioritising a queue
under time pressure, chargeback deadlines are the hard ones.

Each case's window is set on the payment side and arrives on the case as
`expiryDateTime` — there is no single Waffo-wide window, and it is not derived from the
transaction date, so always read it per case rather than computing it.

## What do the `Alert Status` values in the daily dispute report mean?

If Chargeback Alert is enabled for you, the daily dispute report carries an alerts
attachment. `Alert Status` is the overall stage of the alert case:

| `Alert Status` | Meaning | Does it need you? |
| - | - | - |
| `PROCESSING` | The case is being worked | No |
| `MANUAL PROCESSING` | The case hit an exception and is being handled by hand **at Waffo** | **No** — despite the name |
| `PROCESSED` | A refund was initiated and the alert answered; final confirmation is still pending | No |
| `FAILED` | Final: the case could not be completed | Only if Waffo contacts you |
| `EXPIRED` | Final: the case did not reach a final state within 72 hours of being received | No |

**`MANUAL PROCESSING` does not mean "manual processing by you".** It is the single most
misread value in this report: it means Waffo took the case out of the automated path. You
are contacted directly if anything is actually needed from you.

The attachment reports the alert case's stage and its refund; it does not expose the
internal handling steps behind a `MANUAL PROCESSING` case, so there is nothing further to
read into that value than "not automated, being handled".

## What is `Refund Status`, and what does an Alert ID look like?

`Refund Status` in the same attachment tracks only the refund that the alert triggered:

| `Refund Status` | Meaning |
| - | - |
| `PROCESSING` | The refund has been submitted and is not confirmed yet |
| `SUCCESS` | The refund completed |
| `FAILED` | The refund did not complete |

A `FAILED` refund does not mean the alert was ignored — it is exactly the case that gets
picked up by hand, which is why `MANUAL PROCESSING` and a `FAILED` refund often appear on
the same row.

Alert IDs are formatted like `CBA-00-20251125-00003`: a fixed `CBA` prefix, a two-digit
segment, the date, and a sequence number. Quote the whole string when you contact support
about a specific alert. Where an alert relates to a subscription, the attachment also
carries the subscription id.

Once the alert has refunded an order, your own refund request for that order is rejected
with `A0039` — see [Chargeback & Dispute FAQ](/docs/en/support/chargeback-faq) for what that
means and how alert fees are billed.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.