Disputes integration with API

Integrate the Payment Dispute API to manage disputes programmatically — receive real-time notifications, submit evidence, and track outcomes through the complete lifecycle.

159 min read

Using Klarna's Payment Dispute API, you can seamlessly upload evidence, respond to disputes, submit appeals for arbitration decisions, and retrieve detailed information on each dispute.

Webhooks keep you informed in real time by notifying you of key dispute-related events as they occur. This integration empowers you to handle disputes efficiently, ensure timely responses, and maintain full visibility throughout the dispute lifecycle.

Integration flow

sequenceDiagram participant Customer participant Klarna participant Partner participant Evidence as Evidence System Customer->>Klarna: Raises dispute Klarna->>Partner: Webhook: payment.dispute.state-change.initiated Partner->>Klarna: GET /disputes/{dispute_id} Klarna-->>Partner: Dispute details + customer evidence Partner->>Evidence: Gather supporting documents Evidence-->>Partner: Evidence files collected Partner->>Klarna: POST /disputes/{dispute_id}/attachments Klarna-->>Partner: attachment_id Partner->>Klarna: POST /disputes/{dispute_id}/represent Klarna-->>Partner: Response accepted Klarna->>Partner: Webhook: payment.dispute.state-change.representment Note over Klarna: Evidence review alt Preliminary decision: WON Klarna->>Partner: Webhook: payment.dispute.state-change.closed Note over Partner: Dispute resolved favorably else Preliminary decision: LOST Klarna->>Partner: Webhook: payment.dispute.state-change.pre-arbitration Partner->>Klarna: POST /disputes/{dispute_id}/appeal Klarna-->>Partner: Appeal accepted Klarna->>Partner: Webhook: payment.dispute.state-change.arbitration Note over Klarna: Arbitration review Klarna->>Partner: Webhook: payment.dispute.state-change.closed Note over Partner: Final outcome determined end

Dispute webhooks

Klarna webhooks allow you to receive real-time notifications about dispute activities. This proactive communication enables you to respond swiftly to any dispute-related events, minimizing the risk of delayed responses or escalations. As soon as you receive a notification, evaluate the information and prepare to take the necessary actions — whether it's gathering evidence, reviewing the dispute, or preparing a response.

Dispute webhooks are categorized into two main types: state changes and updates.

Enabling webhooks gives you:

Immediate awareness of dispute events
Reduced response times
Proactive management of disputes before deadlines expire

Subscribe to webhook events:

payment.dispute.state-change — Dispute state transitions (INITIATED, REPRESENTMENT, PRE_ARBITRATION, ARBITRATION, CLOSED)
payment.dispute.updated — Details updated without state change (deadline extended, amount adjusted)

For webhook subscription setup, see Subscribing to webhook events.

State change webhooks

State change webhooks notify you of transitions between dispute states as part of the dispute lifecycle. The payment.dispute.state-change event tracks transitions between dispute states:

See paymentDisputeStateChangeWebhook API

to get a full description of the payload.

Dispute created and evidence requested

Webhook event: payment.dispute.state-change.initiated

Dispute under review

Webhook event: payment.dispute.state-change.representment

Klarna makes preliminary decision

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

Appeal under review

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

Dispute closed

Webhook event: payment.dispute.state-change.closed

Update webhooks

The payment.dispute.updated event is delivered when dispute details are updated without a state change — for example, when a deadline is extended or the disputed amount is adjusted.

See paymentDisputeUpdatedWebhook API

to get a full description of the payload.

API endpoints reference

The Payment Dispute API exposes the following operations to manage disputes end-to-end:

Common request examples

Retrieve dispute details

Retrieve complete details of a dispute and any response or evidence already provided.

BASH

1 2 3 4

curl -X GET \
  "https://api-global.klarna.com/v2/accounts/{partner_account_id}/payment/disputes/{payment_dispute_id}" \
  -H "Authorization: Basic {klarna_live_api_****}" \
  -H "Content-Type: application/json"

Replace {partner_account_id} with your Klarna partner account ID, {payment_dispute_id} with the dispute ID, and {klarna_live_api_****} with your base64-encoded Klarna API credentials.

Upload an evidence attachment

Upload an evidence attachment using multipart/form-data. The response returns a payment_dispute_attachment_id you can reference when calling the respond endpoint. Supported file type: PDF. Maximum file size: 7 MB.

BASH

1 2 3 4 5

curl -X POST \
  "https://api-global.klarna.com/v2/accounts/{partner_account_id}/payment/disputes/{payment_dispute_id}/attachments" \
  -H "Authorization: Basic {klarna_live_api_****}" \
  -F "file=@/path/to/your/file.pdf" \
  -F "filename=your_file.pdf"

The filename field is optional. If omitted, the original filename is used. If provided, the file extension must match the uploaded file's extension.

Respond to a representment request — defend the entire amount

BASH

1 2 3 4 5 6 7 8 9 10

curl -X POST \
  "https://api-global.klarna.com/v2/accounts/{partner_account_id}/payment/disputes/{payment_dispute_id}/represent" \
  -H "Authorization: Basic {klarna_live_api_****}" \
  -H "Content-Type: application/json" \
  -d '{
    "attachments": [
      {
        "payment_dispute_attachment_id": "krn:network:eu1:test:payment:dispute:123456789:attachment:1",
        "description": "Proof of delivery documentation"
      }

Respond to a representment request — defend a partial amount

Optionally, include partner_proposed_refund_amount (in minor currency units) to propose a partial refund while providing evidence for why the remaining amount should not be refunded.

BASH

1 2 3 4 5 6 7 8 9 10

curl -X POST \
  "https://api-global.klarna.com/v2/accounts/{partner_account_id}/payment/disputes/{payment_dispute_id}/represent" \
  -H "Authorization: Basic {klarna_live_api_****}" \
  -H "Content-Type: application/json" \
  -d '{
    "attachments": [
      {
        "payment_dispute_attachment_id": "krn:network:eu1:test:payment:dispute:123456789:attachment:1",
        "description": "Return policy document showing 3 EUR return shipping fee"
      }

Accept a dispute loss

Accept the loss of the dispute when it is in INITIATED or PRE_ARBITRATION state. The dispute will transition to state CLOSED with outcome LOST. No request body is required.

BASH

1 2 3 4

curl -X POST \
  "https://api-global.klarna.com/v2/accounts/{partner_account_id}/payment/disputes/{payment_dispute_id}/accept-loss" \
  -H "Authorization: Basic {klarna_live_api_****}" \
  -H "Content-Type: application/json"

Appeal a pre-arbitration decision

Submit an appeal for a preliminary dispute decision when the dispute is in PRE_ARBITRATION state. The dispute will transition to ARBITRATION while Klarna reviews the appeal.

BASH

1 2 3 4 5 6 7

curl -X POST \
  "https://api-global.klarna.com/v2/accounts/{partner_account_id}/payment/disputes/{payment_dispute_id}/appeal" \
  -H "Authorization: Basic {klarna_live_api_****}" \
  -H "Content-Type: application/json" \
  -d '{
    "additional_information": "We believe the preliminary decision is incorrect because we have proof of delivery with customer signature. The tracking shows the package was delivered and signed for by the customer on the expected date."
  }'

Download a dispute attachment

Download an attachment file associated with the dispute. This can be either a partner-submitted evidence attachment or a customer-provided evidence attachment. If the attachment_id does not belong to the specified dispute_id, a 404 error is returned.

BASH

1 2 3 4

curl -X GET \
  "https://api-global.klarna.com/v2/accounts/{partner_account_id}/payment/disputes/{payment_dispute_id}/attachments/{payment_dispute_attachment_id}/download" \
  -H "Authorization: Basic {klarna_live_api_****}" \
  -o output_filename.ext

Integrating with your existing dispute infrastructure

If you already manage disputes through your own dashboard or platform, integrate Klarna's dispute webhooks and API so the Klarna dispute experience is consistent with the other payment methods you support. By adopting these best practices, you can safeguard your finances, resolve cases efficiently, and maintain strong customer relationships.

Alternate dispute solution

Alternate dispute solution

If you do not have a built-in dispute management flow or partner-facing dashboard, you can use the Klarna Partner Portal Disputes App to handle disputes through Klarna's interface.

Even in this case, integrating Klarna's dispute webhooks is recommended. They give you real-time visibility into potential risks and outstanding dispute cases.

Best practices:

Integrate response capabilities: Ensure your dispute management system is integrated with Klarna's Disputes API and webhooks, allowing direct submission of responses from your platform.
Submit evidence and responses: Upload all relevant documentation — such as shipping receipts, tracking numbers, and customer communications — directly through your own system. This information is then transmitted to Klarna for review.
Monitor submission status: Track the status of all submitted evidence to confirm successful delivery and receipt by Klarna, ensuring nothing is missed and timelines are met.

Alternative: using the Partner Portal

If you don't want to integrate the API immediately, you can manage disputes via the Disputes App in Klarna's Partner Portal. The Portal provides an intuitive interface where you can:

View all active and past disputes (organized by deadline)
Submit evidence or responses
Configure notification settings (per Merchant ID and market)
Set chargeback thresholds (auto-resolve low-value disputes)
Track dispute outcomes and fees
View statistics and dispute trends

Tabs in the Disputes App

Tab	Purpose
Open Disputes	Active disputes that require a response. Prioritized by earliest deadlines.
Unauthorized Purchases	Disputes flagged as suspected fraud. Typically require a quicker response.
High-Risk Orders	Orders with an elevated risk of dispute. Review recommended before shipment.
All Disputes	Historical log of all disputes from the past 180 days. Useful for audits or analysis.

Responding to a dispute via the Portal

1.
On the Open Disputes page, click Respond.
2.
Upload your evidence as one or more PDF files (for example, tracking proof, return confirmation, or product photos).
3.
Add comments to explain the situation or highlight supporting details.
4.
Click Submit.

Once submitted, the dispute moves to the REPRESENTMENT state while Klarna reviews your evidence and determines the outcome.

Integration requirement

Evidence uploaded should meet the following criteria:

File type: PDF
Maximum file size: 7 MB
Submit before the deadline shown: 21 days for most reasons, or 7 days for Purchase Unauthorized

Chargeback threshold

You can configure a chargeback threshold per currency and Merchant ID. When a dispute amount is at or below the threshold, Klarna resolves it automatically with a chargeback instead of requesting evidence from you to defend the case.

Chargeback threshold scope

The chargeback threshold applies only to the first dispute raised on a capture. If the same capture is disputed again, the threshold is not applied — the case is sent to you as a normal dispute request, and if you do not respond it can be closed against you with a dispute fee.

Benefits:

No need to allocate resources for defending low-value disputes
No dispute fee charged for these auto-resolved cases

To safeguard you from human error, Klarna enforces a maximum threshold per currency:

Currency	Max amount
EUR	50
SEK	500
NOK	500
DKK	500
GBP	50
PLN	500
USD	50
CAD	50
AUD	50
NZD	50
CZK	1000
RON	250
CHF	50
MXN	1000
HUF	20000

Customer service information

Klarna shows your customer service details to the customer when they raise a dispute, directing them to contact you first. To set or update these details, open Settings → Customer Service Information in the Disputes App, choose the Merchant ID and market (choose Global to apply to all markets without specific details), and fill in:

Customer service email, phone number, contact form URL, and chat URL
Return policy URL and the days limit for returns and refunds

Keeping this information current helps customers resolve issues with you directly before a dispute escalates.

Set up your webhooks

Jump to section...