Disputes in the settlement report
Learn how disputes and chargebacks appear in your Klarna settlement report, both with hold policy `NONE` and with `ON_DISPUTE_INITIATED`.
10 min read
When a customer disputes a payment, the dispute appears in your settlement report as one or more transactions. This page maps each step of a dispute to the
type and detailed_type it produces, and shows worked examples for every outcome.What you see depends on the dispute's hold policy (
hold_policy on the dispute's configuration). With NONE, nothing is charged back while a dispute is open, so a dispute only reaches your report when it closes against you. Once the account is opted in to ON_DISPUTE_INITIATED, disputes initiated under that policy are charged back as soon as they are initiated, and the chargeback is reversed if you win. The report format does not change — there are no new type or detailed_type values — only which rows a dispute produces.For the full field catalogue and report formats, see Settlement reports. For how disputes work end to end, see the Dispute management documentation.
Two conventions in this report differ from Klarna's other settlement formats. Getting them wrong is the most common cause of a failed reconciliation.
- Amounts are unsigned magnitudes. A row never carries a minus sign. Whether it is money in or money out is carried by the
type, and the settlement formula adds or subtracts accordingly. - The file is semicolon-delimited with decimal amounts. Data rows are quoted; header rows are not.
Disputes are linked to their transactions by
reversal_reference, the dispute's Klarna reference. Every row belonging to one dispute carries the same value, in every settlement it appears in.A dispute's shape is fixed when it is initiated, and never changes afterwards.
| Hold policy | What happens |
|---|---|
NONE | Nothing posts while the dispute is open. If you lose, the full amount is debited at close |
ON_DISPUTE_INITIATED | The amount is charged back as soon as the dispute is initiated, and reversed at close if you win |
Because the rule keys off the policy at initiation, you will receive both shapes at once while some accounts (or older disputes) are still on
NONE and newer ones are already charged back up front.The dispute fee follows the same initiation-time policy for eligibility, but it is posted when the dispute closes, not when the dispute starts. It is charged once per dispute.
A dispute is raised against either a whole order or a single capture.
- Order-level —
capture_idis empty on the dispute rows. The chargeback covers the outstanding order amount. - Capture-level —
capture_ididentifies the disputed capture. Other captures on the same order are unaffected and can be disputed independently, each with its ownreversal_referenceand its own dispute fee.
Match a dispute's rows across settlements on
reversal_reference. Do not key on order_id or capture_id — two captures of one order can be disputed separately and would collide.This is how disputes appear with hold policy
NONE, and how any dispute initiated under that policy behaves for its whole life.| Dispute step | Settlement transaction | Effect | Summary total |
|---|---|---|---|
| Dispute initiated | nothing posts | — | — |
| Resolved in the customer's favour | REVERSAL / REVERSAL | Debit | total_reversal_amount |
| Resolved in your favour | nothing posts | — | — |
| Dispute closed — dispute fee | FEE / DISPUTE_FEE | Debit | total_fee_amount |
If a dispute in this shape is first decided against you and only later overturned, the earlier
REVERSAL and DISPUTE_FEE are put right by a correction. See Corrections.Info
The report gains no new
type or detailed_type values — every row below reuses a value that exists today. Opting the account into ON_DISPUTE_INITIATED only changes which of those rows a dispute produces.Once the account has
ON_DISPUTE_INITIATED, 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 reversal if you win.| Dispute step | Settlement transaction | Effect | Summary total |
|---|---|---|---|
| Dispute initiated — amount charged back | REVERSAL / REVERSAL | Debit | total_reversal_amount |
| Resolved in your favour — chargeback reversed | CREDIT / CORRECTION_DISPUTE | Credit | total_credit_amount |
| Resolved in the customer's favour | nothing posts | — | — |
| Appeal unsuccessful — appeal fee | FEE / DISPUTE_FEE | Debit | total_fee_amount |
| Appeal fee corrected | FEE_REFUND / DISPUTE_FEE_REFUND | Credit | total_fee_refund_amount |
| Dispute closed — dispute fee | FEE / DISPUTE_FEE | Debit | total_fee_amount |
The appeal fee has no type of its own in this report: it posts as another
FEE / DISPUTE_FEE row, so a dispute lost on appeal carries two DISPUTE_FEE rows. Its correction reuses FEE_REFUND / DISPUTE_FEE_REFUND in the same way.Warning
There is no dedicated reversal total in this report, and no
detailed_type unique to a won dispute. CORRECTION_DISPUTE folds into total_credit_amount alongside unrelated credits, and the same detailed_type also carries Klarna-issued corrections — so neither the total nor the detailed_type isolates dispute wins on its own. See Corrections.The money left your settlement 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.
This holds on a partial loss too. The chargeback raised at initiation covers the full disputed amount and the reversal returns only the won portion. The amount you lose appears in no row — it is the chargeback minus the reversal.
The dispute fee is charged once per dispute, never once per part.
Winning a dispute returns the charged-back amount, but it does not reverse the fees on the original capture.
PURCHASE_FEE_FIXED and PURCHASE_FEE_PERCENTAGE, and any tax on them, stay charged.Separately from the dispute outcome, Klarna may issue a correction when it acknowledges an error on its side.
| Correction | Settlement transaction | Effect |
|---|---|---|
| Correction of an incorrect chargeback | CREDIT / CORRECTION_DISPUTE | Credit |
| Correction of an incorrect dispute fee | FEE_REFUND / DISPUTE_FEE_REFUND | Credit |
| Correction of an incorrect appeal fee | FEE_REFUND / DISPUTE_FEE_REFUND | Credit |
Warning
CORRECTION_DISPUTE carries two different events. It reports both a dispute you won and a chargeback Klarna raised in error and later put right. The settlement report does not separate them: same type, same detailed_type, same total.To tell them apart, match the row's
reversal_reference to the dispute and read dispute_outcome on the Disputes API. If the dispute was won, the credit is the outcome. If it was lost and a credit still arrived, the credit is a correction.An appeal is a third case. It is decided before the dispute closes, so it resolves through the ordinary close rather than through a correction.
Each example shows the transaction rows a single dispute produces. Amounts use a EUR 250.00 capture for illustration; your own fees come from your price list.
The full amount is debited at close, with the dispute fee.
TEXT
1
2
3
type;detailed_type;amount;reversal_reference
"REVERSAL";"REVERSAL";"250.00";"krn:klarna:eu1:dispute:return:000000000000001"
"FEE";"DISPUTE_FEE";"15.00";"krn:klarna:eu1:dispute:return:000000000000001"No money line — nothing was ever charged back, so there is nothing to give back.
If the dispute was first decided against you and only later overturned, the earlier
REVERSAL and DISPUTE_FEE are put right by a correction rather than by a reversal. See Corrections.The chargeback appears when the dispute is initiated; the reversal when it closes. They are usually in different settlement reports, often weeks apart.
TEXT
1
2
3
4
5
6
7
8
# settlement of the day the dispute was initiated
type;detailed_type;amount;reversal_reference
"REVERSAL";"REVERSAL";"250.00";"krn:klarna:eu1:dispute:return:000000000000002"
# settlement of the day the dispute closed
type;detailed_type;amount;reversal_reference
"CREDIT";"CORRECTION_DISPUTE";"250.00";"krn:klarna:eu1:dispute:return:000000000000002"
"FEE";"DISPUTE_FEE";"15.00";"krn:klarna:eu1:dispute:return:000000000000002"Net effect over the dispute's life: the 250.00 comes back in full, and you pay the fee. The money was out of reach between the two settlements.
The close posts only the dispute fee. No second debit arrives — the money already left when the chargeback was raised.
TEXT
1
2
3
4
5
6
7
# settlement of the day the dispute was initiated
type;detailed_type;amount;reversal_reference
"REVERSAL";"REVERSAL";"250.00";"krn:klarna:eu1:dispute:return:000000000000003"
# settlement of the day the dispute closed
type;detailed_type;amount;reversal_reference
"FEE";"DISPUTE_FEE";"15.00";"krn:klarna:eu1:dispute:return:000000000000003"300.00 was charged back at initiation. 180.00 is decided against you, 120.00 in your favour.
TEXT
1
2
3
4
# settlement of the day the dispute closed
type;detailed_type;amount;reversal_reference
"CREDIT";"CORRECTION_DISPUTE";"120.00";"krn:klarna:eu1:dispute:return:000000000000004"
"FEE";"DISPUTE_FEE";"15.00";"krn:klarna:eu1:dispute:return:000000000000004"The 180.00 you lose 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 of the day the dispute finally closed
type;detailed_type;amount;reversal_reference
"FEE";"DISPUTE_FEE";"15.00";"krn:klarna:eu1:dispute:return:000000000000005"
"FEE";"DISPUTE_FEE";"600.00";"krn:klarna:eu1:dispute:return:000000000000005"The second row is the appeal fee. It reuses
DISPUTE_FEE, so the two rows are told apart by their amount and by the dispute's appeal outcome, not by the detailed_type.Had the appeal succeeded, the same close would post
CREDIT / CORRECTION_DISPUTE for the charged-back amount and no appeal fee.A chargeback is taken from that day's settlement. If it is larger than the day's sales, the settlement amount is floored at zero and the shortfall becomes a debt balance, recovered from your next positive settlement through
total_repay_amount.This is more likely under the hold policy than it was before, because a dispute now affects your payout as soon as it is initiated rather than only when you lose it.
| How your import behaves today | What happens once the hold policy is on |
|---|---|
Rejects an unrecognised detailed_type | Nothing breaks — no new type or detailed_type is introduced. The chargeback, the reversal, the dispute fee, and the appeal fee all reuse values you handle today |
Assumes one DISPUTE_FEE row per dispute | An unsuccessful appeal adds a second FEE / DISPUTE_FEE row for the appeal fee |
| Waits for a debit when a dispute is lost | That debit never arrives at close — it happened when the dispute was initiated |
Treats a REVERSAL row as a settled loss | A chargeback is now raised on every dispute, including ones you go on to win |
Books total_reversal_amount straight to a loss account | That total now mixes real losses with chargebacks on undecided disputes |
Treats CORRECTION_DISPUTE as a Klarna error to look into | It now reports every won dispute too, so the volume rises sharply and most of it needs no investigation |
Expects DISPUTE_FEE_REFUND alongside every CORRECTION_DISPUTE | A won dispute credits you without refunding the dispute fee, so that pairing no longer holds |
Jump to section...