Disputes states

A dispute progresses through several states from initiation to resolution. Each state represents a phase in the dispute lifecycle where specific actions are available to you. Understanding these states helps you respond appropriately and resolve disputes efficiently.

What happens: When a dispute is initiated, Klarna notifies you and immediately withholds the disputed amount along with a dispute fee. The dispute fee is non-refundable regardless of outcome, but the disputed amount will be refunded if you win.

Webhook: payment.dispute.state-change.initiated

Your options: You must take action before the deadline expires:

• Accept the loss - If you agree with the dispute, accept the full disputed amount as a loss
• Defend the dispute - Submit evidence to challenge the dispute (fully or partially)

Response deadline:

When to accept a loss:

Consider accepting a loss rather than defending when:

• The customer's evidence is compelling (clear proof of non-receipt, defects, or errors)
• The cost of gathering evidence exceeds the disputed amount
• Maintaining customer relationship is more valuable than the disputed amount
• The disputed amount is small relative to defense costs

Accepting loss implications:

• The disputed amount is refunded to the customer
• Dispute fees are applied
• Payouts are adjusted accordingly
• Quick resolution can enhance customer satisfaction

What happens: You've submitted your defense evidence within the deadline. Klarna's dispute team is now reviewing your case and the evidence provided.

Webhook: payment.dispute.state-change.representment

Your action: No action required. Wait for Klarna's review to complete within 30 days. You cannot submit additional evidence during this state.

Representment substates:

The REPRESENTMENT state includes several substates that indicate progress:

What happens: Klarna has issued a preliminary decision in favor of the customer. You have the opportunity to appeal this decision if you believe there was an error in Klarna's assessment.

Webhook: payment.dispute.state-change.pre-arbitration

Your options:

• Appeal the decision - Submit a summary explaining errors in Klarna's assessment (only full appeals allowed, no partial appeals)
• Accept the preliminary decision - Take no action and the dispute closes as LOST after 10 days

How the appeal process works:

1. Preliminary outcome provided
   1. Klarna provides a preliminary outcome: LOST
   2. The preliminary_outcome_detailed field contains the specific reason code
2. Submit your appeal (if needed)
   1. Via Merchant Portal: Click "Appeal" button and complete the form with your summary
   2. Via API: Use the appealDispute endpoint
   3. Include a clear summary of the perceived error
   4. Reference only evidence already submitted
      1. No new evidence is accepted during appeal. However, if merchants have evidence that was genuinely unavailable during the initial defense, they may include it in their appeal—provided they also supply proof that demonstrates the evidence was not accessible at the time of the original defense.
   5. Only one appeal is permitted per dispute
3. Dispute moves to Arbitration
   1. Upon receiving your appeal, the dispute transitions to ARBITRATION
   2. Klarna re-investigates the case with a fresh review
4. Final decision within 14 days
   1. If appeal succeeds: Dispute closes as WON
   2. If appeal fails: Original decision stands, dispute closes as LOST, and arbitration fees apply

What happens: You've appealed Klarna's preliminary decision. Klarna's dispute team is conducting a thorough review of your appeal and the evidence to make a final decision.

Webhook: payment.dispute.state-change.arbitration

Your action: No action required. Klarna will review and resolve the case within 14 days.

What happens: The dispute has reached a final resolution - either WON (in your favor) or LOST (in customer's favor).

Webhook: payment.dispute.state-change.closed

Possible paths to closure:

Dispute WON by Merchant:

• Path 1: Successful defense during Representment
  • INITIATED → REPRESENTMENT → CLOSED (WON)
  • Reason: Klarna accepts your evidence and rules in your favor
• Path 2: Successful appeal after Pre-Arbitration
  • INITIATED → REPRESENTMENT → PRE_ARBITRATION (LOST) → ARBITRATION → CLOSED (WON)
  • Reason: Your appeal convinces Klarna to overturn the preliminary decision

Dispute LOST by Merchant:

• Path 1: Accepted loss or no response at initiation
  • INITIATED → CLOSED (LOST)
  • Reason: You accepted the dispute or didn't respond
• Path 2: Missed response deadline
  • INITIATED → CLOSED (LOST)
  • Reason: No response provided within allowed timeframe
• Path 3: Unsuccessful defense without appeal
  • INITIATED → REPRESENTMENT → PRE_ARBITRATION (LOST) → CLOSED (LOST)
  • Reason: Klarna ruled against you and you didn't appeal
• Path 4: Unsuccessful appeal
  • INITIATED → REPRESENTMENT → PRE_ARBITRATION → ARBITRATION → CLOSED (LOST)
  • Reason: Klarna upheld its decision after final review

Settlement details:

• Dispute WON: Klarna refunds the withheld dispute amount. Dispute fee remains non-refundable.
• Dispute LOST: Neither the withheld dispute amount nor the dispute fee is refunded.

Your action: No further action required.

When a dispute reaches the CLOSED state, it has one of two outcomes:

For complete information about dispute fees, see here.

The dispute_outcome_detailed field provides a specific reason code explaining why the dispute was resolved the way it was. These codes help you understand the decision and identify areas for improvement.

Outcome codes fall into several categories:

Outcomes favorable to you (WON):

• Valid shipping proof provided
• Valid return/refund documentation
• Dispute resolved directly with customer
• Customer cancelled the dispute
• Dispute filed under wrong reason code

Outcomes requiring action (may trigger fees):

• Refund issued to customer during dispute
• Refund issued after escalation
• Payment issues resolved

Outcomes unfavorable to you (LOST):

• No response or missed deadline
• Insufficient or missing shipping proof
• Didn't follow Klarna's shipping or return policies
• Service or product issues without adequate evidence
• Failed to perform promised actions (refund, cancellation, updates)

For a complete reference of all outcome codes, their descriptions, and when they apply, see the Dispute API Reference.

Use outcome codes to:

• Track which issues cause the most disputes
• Identify patterns in lost disputes
• Generate reports on dispute resolution effectiveness
• Improve processes based on common failure reasons

Handle unknown codes gracefully:

Your integration should accept any string value for dispute_outcome_detailed since new codes may be added:

function getOutcomeDescription(outcomeCode) {
  const knownOutcomes = {
    'PARTNER_PROVIDED_VALID_SHIPPING_DETAILS': 'Valid shipping proof submitted',
    'PARTNER_DID_NOT_REPLY_TO_DISPUTE_REQUEST': 'No response before deadline',
    // ... other known codes
  };

  return knownOutcomes[outcomeCode] || `Unknown outcome: ${outcomeCode}`;
}