Disputes and chargebacks in the settlement report
Learn how disputes and chargebacks appear as transactions in the Klarna settlement report, both without the hold policy and with the ON_DISPUTE_INITIATED hold policy on KNR_APR2026.
13 min read
When a customer disputes a payment, the dispute surfaces in the settlement report as one or more balance transactions. This page maps each step of a dispute to the settlement transaction
type and detailed_type it produces.Two separate settings decide what an Acquiring Partner sees: the updated report, which changes what money returned on a chargeback is called, and the dispute hold policy, which changes when the chargeback is raised. Both are enabled per Acquiring Partner, and the updated report can be enabled on its own.
For the full catalog of transaction types and report formats, see Settlement report types. For how disputes work end to end — states, reasons, fees, and deadlines — see the disputes documentation.
Amounts follow the report's sign convention: positive values are credits to the Acquiring Partner, negative values are debits.
To support the hold policy, the settlement report has an updated format — the updated report, as this page calls it. It adds the chargeback reversal transaction a won dispute needs, and renames what carries money returned on a chargeback today. Klarna enables it per Acquiring Partner.
The updated report doesn't depend on the hold policy and can be enabled on its own. What it changes:
| Reported today | Once the updated report is enabled |
|---|---|
CHARGEBACK / CORRECTION_CHARGEBACK | CHARGEBACK_REVERSAL / CHARGEBACK_REVERSAL, a new top-level type |
CSV summary column correction_chargeback_amount | Renamed in place to chargeback_reversal_amount, so the column count and order don't change |
JSON total correction_chargeback_amount | Joined by chargeback_reversal_amount. The old field stays but is deprecated and always reads 0 |
Without the hold policy, the only thing
CHARGEBACK_REVERSAL reports is a chargeback Klarna raised in error and later corrected — the same transaction that arrives today as CHARGEBACK / CORRECTION_CHARGEBACK, under its new name.The hold policy (
ON_DISPUTE_INITIATED, available on KNR_APR2026) changes when the chargeback is raised: at dispute initiation rather than at close, and reversed if the Acquiring Partner wins. Handling the updated report is a prerequisite for enabling it, because a win returns the money as CHARGEBACK_REVERSAL and the earlier report has no transaction that can carry it. The order is therefore fixed: the Acquiring Partner's integration handles the updated report, Klarna enables it for them, and the hold policy is turned on last.When the hold policy is not enabled, a chargeback is created only once Klarna resolves the dispute in the customer's favor. Initiating a dispute doesn't produce a settlement transaction on its own.
| Dispute step | Settlement transaction | Effect |
|---|---|---|
| Dispute initiated | None | — |
| Resolved in the customer's favor | CHARGEBACK / CHARGEBACK | Debit |
| Resolved in the Acquiring Partner's favor | None | — |
| Resolved in the customer's favor — dispute fee | FEE / DISPUTE_FEE | Debit |
With the hold policy enabled (
ON_DISPUTE_INITIATED on KNR_APR2026), Klarna raises the chargeback as soon as the dispute is initiated instead of waiting for the outcome. Only two money transactions can follow from a dispute: the chargeback, and a chargeback reversal if the Acquiring Partner wins. This is the same model Visa, Mastercard, and other acquiring platforms use. This shape needs the updated report — the reversal has nowhere to go without it.| Dispute step | Settlement transaction | Effect |
|---|---|---|
| Dispute initiated — chargeback raised | CHARGEBACK / CHARGEBACK | Debit |
| Resolved in the Acquiring Partner's favor — chargeback reversed | CHARGEBACK_REVERSAL / CHARGEBACK_REVERSAL | Credit |
| Resolved in the customer's favor | None | — |
| Resolved in the customer's favor — dispute fee | FEE / DISPUTE_FEE | Debit |
A lost dispute posts no transaction of its own. The money left when the chargeback was raised, so losing moves nothing further: there is no marker row and no second debit. The only row a lost dispute adds at close is the dispute fee.
On a partial loss, the chargeback raised at initiation covers the full disputed amount and the reversal returns only the won portion. The lost amount appears in no row of its own — it is the chargeback minus the reversal. The dispute fee is charged once per dispute, never once per part.
In the settlement totals, chargebacks are summed in
chargeback_amount and reversals in chargeback_reversal_amount.The dispute fee is charged when a dispute is decided against you, once per dispute, and is non-refundable. A dispute resolved in your favor carries no dispute fee. For the full dispute fee rules and lifecycle, see the disputes documentation.
A dispute's shape is fixed when it is initiated and never changes afterwards. Enabling the hold policy is not retroactive: a dispute already open on the day it is enabled keeps the shape it started with.
| Dispute initiated | What happens |
|---|---|
| Before the hold policy is enabled | Nothing posts while the dispute is open. If it is lost, the full amount is debited at close |
| After the hold policy is enabled | The chargeback is raised as soon as the dispute is initiated, and reversed at close if the Acquiring Partner wins |
Because the rule keys off the initiation date, Acquiring Partners receive both shapes at once for as long as pre-cutover disputes are still closing.
A dispute is raised against either a whole order or a single capture.
- Order-level —
payment_capture_idis empty on the dispute rows. The chargeback covers the outstanding order amount. - Capture-level —
payment_capture_ididentifies the disputed capture. Other captures on the same order are unaffected and can be disputed independently, each with its ownpayment_dispute_idand its own dispute fee.
Match a dispute's rows across settlements on
payment_dispute_id. Do not key on payment_capture_id or on the order — two captures of one order can be disputed separately and would collide.When a dispute involves a currency exchange, a rate movement may add a currency-conversion delta transaction that adjusts the settled amount by the difference; when the rate doesn't move, no delta is emitted. Two independent cases can trigger it:
- Customer FX (the billing currency differs from the transaction currency) — a delta from converting the customer's billing currency. This can happen regardless of the dispute flow and already occurs today.
- Settlement FX (the settlement currency differs from the transaction currency) — only with the hold policy
ON_DISPUTE_INITIATED, and only when the dispute is lost: the chargeback is raised at initiation, so the settlement (payout) rate can drift before the dispute closes and a delta settles that movement at close. A win produces no settlement FX delta — the reversal reuses the rate the chargeback was raised at, so it returns exactly what was taken.
The delta's direction reflects which way the rate moved:
| Example | Settlement transaction | Effect |
|---|---|---|
| Rate moved so more is owed on the chargeback | CHARGEBACK / CUSTOMER_CURRENCY_CONVERSION_DELTA | Debit |
| Rate moved so less is owed on the chargeback | CHARGEBACK_REVERSAL / CUSTOMER_CURRENCY_CONVERSION_DELTA | Credit |
If a dispute decision is appealed, Klarna adds an appeal fee, reported as
FEE / APPEAL_FEE (debit). It is separate from the dispute fee and is charged only when the appeal is unsuccessful — a successful appeal carries no appeal fee. The FEE / APPEAL_FEE type is on the updated report. A row posts when an appeal is unsuccessful, on KNR_APR2026 with the hold policy ON_DISPUTE_INITIATED. Turning the hold policy on does not change the report structure.An appeal does not produce its own settlement transactions. The preliminary decision posts nothing; the dispute closes only once the appeal process finishes, and that close posts the chargeback reversal if the appeal succeeds, or nothing at all if it fails. A correction is a different path — see Corrections.
Separately from the dispute outcome, Klarna may issue a correction when it acknowledges an error on its side — for example, reversing a chargeback that should never have been raised, or correcting a fee. Corrections credit the Acquiring Partner.
With the updated report,
CHARGEBACK_REVERSAL / CHARGEBACK_REVERSAL carries both events: a dispute resolved in the Acquiring Partner's favor, and a chargeback Klarna raised in error and later corrected. There is no detailed_type unique to a won dispute, so don't read the reversal total as a dispute win rate — match the row's payment_dispute_id to the dispute and check its outcome instead.Which transaction a correction posts under follows the updated report, not the hold policy.
Before the updated report:
| Correction | Settlement transaction | Effect |
|---|---|---|
| Correction of an incorrect chargeback | CHARGEBACK / CORRECTION_CHARGEBACK | Credit |
| Correction of an incorrect dispute fee | FEE_CORRECTION / CORRECTION_DISPUTE_FEE | Credit |
With the updated report:
| Correction | Settlement transaction | Effect |
|---|---|---|
| Correction of an incorrect chargeback | CHARGEBACK_REVERSAL / CHARGEBACK_REVERSAL | Credit |
| Correction of an incorrect dispute fee | FEE_CORRECTION / CORRECTION_DISPUTE_FEE | Credit |
| Correction of an incorrect appeal fee | FEE_CORRECTION / CORRECTION_APPEAL_FEE | Credit |
Corrected chargebacks are summed in
chargeback_reversal_amount alongside won disputes.Each example shows the dispute rows one dispute produces, narrowed to the columns that matter. Amounts are in minor units and signed: negative is a debit to you. A EUR 250.00 capture and a EUR 15.00 dispute fee are used for illustration; your own fees come from your price list. Fees carry tax in the row's
tax_amount and tax_rate columns, omitted here for readability.The full amount is debited at close, with the dispute fee.
TEXT
1
2
3
type,detailed_type,amount,currency,payment_dispute_id,payment_chargeback_id
CHARGEBACK,CHARGEBACK,-25000,EUR,krn:klarna:eu1:dispute:1,krn:klarna:eu1:chargeback:1
FEE,DISPUTE_FEE,-1500,EUR,krn:klarna:eu1:dispute:1,No rows at all. Nothing was ever charged back, so there is nothing to give back, and a dispute decided in your favor carries no dispute fee. The dispute leaves no trace in the settlement report — to see it you have to read the dispute itself.
The chargeback posts when the dispute is initiated, the reversal when it closes. These are usually different settlements, often weeks apart.
TEXT
1
2
3
4
5
6
7
# settlement covering the day the dispute was initiated
type,detailed_type,amount,currency,payment_dispute_id,payment_chargeback_id
CHARGEBACK,CHARGEBACK,-25000,EUR,krn:klarna:eu1:dispute:3,krn:klarna:eu1:chargeback:3
# settlement covering the day the dispute closed
type,detailed_type,amount,currency,payment_dispute_id,payment_chargeback_id
CHARGEBACK_REVERSAL,CHARGEBACK_REVERSAL,25000,EUR,krn:klarna:eu1:dispute:3,krn:klarna:eu1:chargeback:3Over the dispute's life the 250.00 comes back in full and no fee is charged, so the dispute nets to zero. The money was out of reach between the two settlements.
The close posts only the dispute fee. No second debit arrives — the money left when the chargeback was raised.
TEXT
1
2
3
4
5
6
7
# settlement covering the day the dispute was initiated
type,detailed_type,amount,currency,payment_dispute_id,payment_chargeback_id
CHARGEBACK,CHARGEBACK,-25000,EUR,krn:klarna:eu1:dispute:4,krn:klarna:eu1:chargeback:4
# settlement covering the day the dispute closed
type,detailed_type,amount,currency,payment_dispute_id,payment_chargeback_id
FEE,DISPUTE_FEE,-1500,EUR,krn:klarna:eu1:dispute:4,300.00 was charged back at initiation. 180.00 is decided against you, 120.00 in your favor.
TEXT
1
2
3
4
# settlement covering the day the dispute closed
type,detailed_type,amount,currency,payment_dispute_id,payment_chargeback_id
CHARGEBACK_REVERSAL,CHARGEBACK_REVERSAL,12000,EUR,krn:klarna:eu1:dispute:5,krn:klarna:eu1:chargeback:5
FEE,DISPUTE_FEE,-1500,EUR,krn:klarna:eu1:dispute:5,The 180.00 lost is the 300.00 charged back minus the 120.00 reversed. It is not printed as a row.
The preliminary decision posts nothing. Only the final close, after the appeal is resolved, reaches the report — and an unsuccessful appeal adds the appeal fee.
TEXT
1
2
3
4
# settlement covering the day the dispute finally closed
type,detailed_type,amount,currency,payment_dispute_id,payment_chargeback_id
FEE,DISPUTE_FEE,-1500,EUR,krn:klarna:eu1:dispute:6,
FEE,APPEAL_FEE,-60000,EUR,krn:klarna:eu1:dispute:6,Had the appeal succeeded, the same close would post
CHARGEBACK_REVERSAL / CHARGEBACK_REVERSAL for the charged-back amount and neither fee — a dispute decided in your favor carries no dispute fee either.The two files below are complete CSV settlement reports under the hold policy, with every column the format carries rather than the handful shown above. They are a separate set of disputes from the examples on this page, with their own amounts and identifiers.
The first covers the day five disputes were opened, the second the day those five closed — one confirmed after an unsuccessful appeal, one won in full, one won in part, and two confirmed on a purchase the customer paid in another currency, where the settlement rate moved between the chargeback and the close. Each
payment_capture_reference names the outcome its dispute gets, so the same five disputes can be followed from one file to the other.A chargeback is taken from that day's settlement. If it exceeds the day's sales, the settlement amount is floored at zero and the shortfall becomes a debt balance in
deposit_amount and closing_debt_balance, recovered from the next positive settlement through repay_amount.This is more likely under the hold policy than before, because a dispute now affects the payout as soon as it is initiated rather than only when it is lost.
When the updated report is enabled:
| How your import behaves today | What happens |
|---|---|
Rejects an unrecognized type or detailed_type | The import fails on the first reversal — CHARGEBACK_REVERSAL is a new top-level type |
| Silently skips rows it doesn't recognize | The report stops balancing and reversed amounts are lost |
Reads reversed amounts from correction_chargeback_amount | In JSON that field is deprecated and reads 0; in the CSV summary the column is renamed. Read reversals from chargeback_reversal_amount |
| Matches CSV summary columns by header name | correction_chargeback_amount is renamed to chargeback_reversal_amount. The column count, order, and every other name are unchanged |
When the hold policy is enabled:
| How your import behaves today | What happens |
|---|---|
| Waits for a debit when a dispute is lost | That debit never arrives at close — it happened when the dispute was initiated |
Treats a CHARGEBACK row as a settled loss | A chargeback is now raised on every dispute, including ones you go on to win. Only its absence of a reversal makes it a loss |
Books chargeback_amount straight to a loss account | That total now mixes settled losses with chargebacks on undecided disputes |
Related articles
Jump to section...