Disputes lifecycle

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

Lifecycle diagram

stateDiagram-v2 [*] --> INITIATED : Customer raises dispute INITIATED --> REPRESENTMENT : Partner submits evidence INITIATED --> CLOSED : Partner accepts loss / Deadline expires / Auto-close REPRESENTMENT --> PRE_ARBITRATION : Preliminary decision LOST REPRESENTMENT --> CLOSED : Preliminary decision WON PRE_ARBITRATION --> ARBITRATION : Partner appeals PRE_ARBITRATION --> CLOSED : Partner accepts 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 the Partner of the dispute. During this stage, the disputed amount is placed on hold, and a non-refundable dispute fee is charged.

Available actions for Partner:

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 expires_at field. Varies by dispute reason.

Transitions to:

REPRESENTMENT - After submitting evidence
CLOSED - If accept loss, miss deadline, or auto-closed

REPRESENTMENT

If the Partner provides evidence, Klarna reviews the case and makes a preliminary decision. If the Partner wins at this stage, the dispute is closed and the withheld amount is refunded (excluding the dispute fee).

Available actions:

getDisputeDetails - Monitor status

Representment state: EVIDENCE_RECEIVED

Note: 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 the Partner’s favor, the Partner has 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, preliminary decision becomes final.

Transitions to:

ARBITRATION - If appeal submitted
CLOSED - If 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: Cannot submit new evidence during arbitration.

Transitions to:

CLOSED - After final arbitration decision

CLOSED

All dispute paths eventually conclude in the “Closed” state. If the Partner wins, the previously withheld amount is refunded. If the dispute is lost or the deadline has expired, no refund is issued and the dispute fee remains non-refundable.

Outcome details:

dispute_outcome - WON (Partner 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 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 dispute transitions to 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 updated without state change (deadline extended, amount adjusted).

Timelines

Evidence submission: Upto 21 days (check expires_at for specific deadline)

Evidence review: Upto 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:

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

API & SDK references

Get dispute

Upload partner evidence attachment

Respond to representment request

Accept dispute loss

Appeal pre-arbitration decision