Disputes lifecycle

Understand dispute states, transitions, and available actions at each stage.

5 min read

Lifecycle diagram

stateDiagram-v2 [*] --> INITIATED : Customer raises dispute INITIATED --> REPRESENTMENT : You submit evidence INITIATED --> CLOSED : You accept loss / Deadline expires / Auto-close REPRESENTMENT --> PRE_ARBITRATION : Preliminary decision LOST REPRESENTMENT --> CLOSED : Preliminary decision WON PRE_ARBITRATION --> ARBITRATION : You appeal PRE_ARBITRATION --> CLOSED : You accept loss / Appeal deadline expires ARBITRATION --> CLOSED : Final decision note right of INITIATED Evidence collection Respond before deadline end note note right of PRE_ARBITRATION Preliminary decision Accept or appeal end note note right of CLOSED Final outcome WON or LOST end note

Lifecycle states

INITIATED

When a customer raises a concern — such as non-delivery, damaged goods, or unauthorized transactions — Klarna immediately notifies you of the dispute. During this stage, the disputed amount is placed on hold. The dispute fee is charged when the dispute is decided against you.

Available actions:

getDisputeDetails — Retrieve dispute details and customer evidence
uploadAttachment — Upload supporting documents (PDF up to 7MB)
respondToDisputeRequest — Submit evidence with optional partial refund proposal
acceptLoss — Accept the dispute

Representment substates:

EVIDENCE_REQUESTED — Can submit evidence before deadline
EVIDENCE_REQUEST_EXPIRED — Deadline passed, dispute results in LOST
EVIDENCE_WAIVED — Accepted loss via accept-loss endpoint
REPRESENTMENT_AUTOMATICALLY_REJECTED — Amount below threshold, auto-accepted as LOST

Response deadline: Check the expires_at field. Varies by dispute reason.

Transitions to:

REPRESENTMENT — After submitting evidence
CLOSED — If you accept loss, miss deadline, or the dispute is auto-closed

REPRESENTMENT

If you provide evidence, Klarna reviews the case and makes a preliminary decision. If you win at this stage, the dispute is closed and the withheld amount is released back to you.

Available actions:

getDisputeDetails — Monitor status

Representment state: EVIDENCE_RECEIVED

Note: You cannot submit additional evidence during review.

Transitions to:

PRE_ARBITRATION — Preliminary decision is LOST
CLOSED — Preliminary decision is WON

PRE_ARBITRATION

If Klarna's preliminary decision is not in your favor, you have the option to appeal within a set period. The dispute then moves to the arbitration phase, where Klarna undertakes a final review.

Available actions:

getDisputeDetails — Review preliminary decision and reason
acceptLoss — Accept the preliminary decision
appealDispute — Challenge the decision

Decision details:

preliminary_outcome — WON or LOST
preliminary_outcome_detailed — Specific reason code
arbitration_expires_at — Appeal deadline

Note: If no action before deadline, the preliminary decision becomes final.

Transitions to:

ARBITRATION — If appeal submitted
CLOSED — If you accept loss or appeal deadline expires

ARBITRATION

Final binding review after appeal. Klarna's arbitration team reconsiders all previously submitted evidence.

Available actions:

getDisputeDetails — Monitor arbitration status

Note: You cannot submit new evidence during arbitration.

Transitions to:

CLOSED — After final arbitration decision

CLOSED

All dispute paths eventually conclude in the CLOSED state. If you win, the previously withheld amount is released back to you. If the dispute is lost or the deadline has expired, no refund is issued and the dispute fee is charged.

Outcome details:

dispute_outcome — WON (you won) or LOST (customer won)
dispute_outcome_detailed — Specific closing reason code
closed_at — When dispute was closed

Financial impact:

If WON — Disputed amount released to you
If LOST — Disputed amount goes to customer

Process exceptions

Dispute window extension

Dispute window extended beyond the standard timeframe.

Type: DISPUTE_WINDOW_EXTENSION

Reasons:

DISPUTE_MIS_HANDLED — Previous process had errors
REGULATORY_REQUIREMENT — Required for legal compliance

Immediate dispute resolution

Dispute resolved immediately without standard defense period.

Type: IMMEDIATE_DISPUTE_RESOLUTION

Reasons:

FRAUDULENT_PARTNER — Partner identified as engaging in fraud
DISPUTE_MIS_HANDLED — Defense period skipped due to errors

Webhooks

State change webhooks

Event	When
`payment.dispute.state-change`	Delivered when a dispute transitions to a new state: `INITIATED`: Dispute created `REPRESENTMENT`: Evidence under review `PRE_ARBITRATION`: Preliminary decision made `ARBITRATION`: Appeal in progress `CLOSED`: Final decision

Update webhooks

Event	When
`payment.dispute.updated`	Delivered when details are updated without state change (deadline extended, amount adjusted).

Timelines

Evidence submission: Up to 21 days (check expires_at for the specific deadline)

Evidence review: Up to 30 days (varies by complexity)

Pre-arbitration window: 10 days to decide whether to appeal (check arbitration_expires_at)

Arbitration review: 14 days (varies by complexity)

Best practices

Best practices:

Set up webhook listeners for real-time notifications
Check dispute details immediately upon notification
Gather evidence promptly to meet deadlines
Submit evidence well before the deadline

Jump to section...