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.

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

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

Integration flow

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

Enablement of webhooks allows for:

Immediate awareness of dispute events.
Reduced response times.
Proactive management of disputes before deadline expires.
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)

Contact your Klarna technical point of contact to enable webhook subscriptions for your integration.

State change webhooks

State change webhooks notify Merchants of transitions between dispute states as part of the dispute lifecycle. payment.dispute.state-change, tracks transitions between dispute states below:

Dispute created and evidence requested

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

JSON

1 2 3 4 5 6 7 8 9 10

  {
    "metadata": {
      "event_type": "payment.dispute.state-change.initiated",
      "event_id": "d9f9b1a0-5b1a-4b0e-9b0a-9e9b1a0d5b1a",
      "event_version": "v1",
      "occurred_at": "2025-09-11T08:31:00Z",
      "webhook_id": "120e5b7e-abcd-4def-8a90-dca726e639b5",
      "merchant_id": "K000000",
      "live": true
    },

Dispute under review

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

JSON

1 2 3 4 5 6 7 8 9 10

{
    "metadata": {
      "event_type": "payment.dispute.state-change.representment",
      "event_id": "d9f9b1a0-5b1a-4b0e-9b0a-9e9b1a0d5b1a",
      "event_version": "v1",
      "occurred_at": "2025-09-15T08:31:00Z",
      "webhook_id": "120e5b7e-abcd-4def-8a90-dca726e639b5",
      "merchant_id": "K000000",
      "live": true
    },

Klarna makes preliminary decision on dispute

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

JSON

1 2 3 4 5 6 7 8 9 10

{
    "metadata": {
      "event_type": "payment.dispute.state-change.pre-arbitration",
      "event_id": "d9f9b1a0-5b1a-4b0e-9b0a-9e9b1a0d5b1a",
      "event_version": "v1",
      "occurred_at": "2025-09-15T08:31:00Z",
      "webhook_id": "120e5b7e-abcd-4def-8a90-dca726e639b5",
      "merchant_id": "K000000",
      "live": true
    },

Appeal under review

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

JSON

1 2 3 4 5 6 7 8 9 10

{
    "metadata": {
      "event_type": "payment.dispute.state-change.arbitration",
      "event_id": "d9f9b1a0-5b1a-4b0e-9b0a-9e9b1a0d5b1a",
      "event_version": "v1",
      "occurred_at": "2025-09-15T08:31:00Z",
      "webhook_id": "120e5b7e-abcd-4def-8a90-dca726e639b5",
      "merchant_id": "K000000",
      "live": true
    },

Dispute Closed

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

JSON

1 2 3 4 5 6 7 8 9 10

 {
    "metadata": {
      "event_type": "payment.dispute.state-change.closed",
      "event_id": "d9f9b1a0-5b1a-4b0e-9b0a-9e9b1a0d5b1a",
      "event_version": "v1",
      "occurred_at": "2025-09-15T08:31:00Z",
      "webhook_id": "120e5b7e-abcd-4def-8a90-dca726e639b5",
      "merchant_id": "K000000",
      "live": true
    },

API Endpoints Reference

Retrieve Disputes

Retrieve a paginated list of disputes with filtering options and any response or evidence that’s already been provided.

CONSOLE

1 2 3 4 5

curl -X GET \
  "https://api.klarna.com/v4/payment/disputes?state=INITIATED&sort_by=-created_at&size=25" \
  -H "Authorization: Basic {klarna_live_api_****}" \
  -H "Content-Type: application/json"

Note

Replace {klarna_live_api_****} with your actual Klarna API credentials (base64 encoded).

Response

JSON

1 2 3 4 5 6 7 8 9 10

{
  "disputes": [
    {
      "payment_dispute_id": "krn:network:eu1:live:payment:dispute:123456789342",
      "dispute_reason": "PRODUCTS_OR_SERVICES_NOT_RECEIVED",
      "state": "INITIATED",
      "payment_transaction_id": "krn:payment:eu1:authorization:6debe89e-98c0-486e-b7a5-08a4f6df94b0",
      "payment_transaction_reference": "f420e0e1-971b-417a-8ece-2626387eff36",
      "payment_capture_reference": "partner-capture-reference-1234",
      "purchase_reference": "f420e0e1-971b-417a-8ece-2626387eff36",

Retrieve Dispute details

Retrieve complete details of disputes and any response or evidence that’s already been provided.

CONSOLE

1 2 3 4 5

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

Note

Replace {payment_dispute_id} with the specific dispute ID you wish to query.
Replace {klarna_live_api_****} with your actual Klarna API credentials (base64 encoded).

Response

JSON

1 2 3 4 5 6 7 8 9 10

{
  "payment_dispute_id": "krn:payment:eu1:dispute:products-or-services-not-received:567891234",
  "dispute_reason": "PRODUCTS_OR_SERVICES_NOT_RECEIVED",
  "state": "CLOSED",
  "previous_state": "ARBITRATION",
  "payment_transaction_id": "krn:payment:eu1:authorization:6debe89e-98c0-486e-b7a5-08a4f6df94b0",
  "payment_transaction_reference": "f420e0e1-971b-417a-8ece-2626387eff36",
  "payment_capture_reference": "partner-capture-reference-1234",
  "purchase_reference": "f420e0e1-971b-417a-8ece-2626387eff36",
  "product_id": "krn:partner:product:payment:ad71bc48-8a07-4919-a2c1-103dba3fc918",

Accept Dispute loss

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

CONSOLE

1 2 3 4 5

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

Note

Replace {payment_dispute_id} with the ID of the dispute you wish to accept the loss on
Replace {klarna_live_api_****} with your actual (base64 encoded) Klarna API credentials
This is a POST request
No request body is required for this endpoint

Response

JSON

1 2 3 4

{
  "state": "CLOSED"
}

Upload Merchant evidence attachment

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

Request Body

file : The file to upload as binary data. This field is required and must contain the actual file content. Supported file type is: PDF (.pdf). Maximum file size is 7MB.
filename : Optional filename for the uploaded attachment. If not provided, the original filename from the uploaded file will be used. If provided, the file extension must match the extension of the uploaded file. Maximum length is 1000 characters (excluding the file extension)

CONSOLE

1 2 3 4 5 6

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

Note

Replace {payment_dispute_id} with the dispute ID.
Replace {klarna_live_api_****} with your actual Klarna API credentials (base64 encoded).
Replace /path/to/your/file.pdf with the path to the file you want to upload.
Replace your_file.pdf with your desired filename (optional; omit this parameter to use original filename).
Supported file type: .pdf.
The filename field is optional.
The file field must contain the actual binary file you want to upload.
File size must be less than or equal to 7MB.

Response

JSON

1 2 3 4

{
  "payment_dispute_attachment_id": "krn:payment:eu1:dispute:1234567890:attachment:3"
}

Respond to Representment Request

Use this endpoint to submit Merchant information by providing a document containing all relevant information when the dispute is in INITIATED state.

Optionally, include partner_proposed_refund_amount to propose a partial refund while providing evidence for why the remaining amount should not be refunded. The dispute will transition to state REPRESENTMENT for Klarna review after submission.

Request Body

Attachments - List of evidence files provided by the Merchant to support the dispute response. Merchant can upload one or more files.
additional_information - Any free text you wish to provide alongside your attachments when responding to a representment request. Klarna will review this information alongside your attachments when evaluating your representment case.
partner_proposed_refund_amount - The amount, in minor currency units, that the Merchant proposes to refund instead of the whole dispute amount. This is in the settlement currency. Must be less than the full disputed amount.

Example 1 - Defend entire dispute amount

CONSOLE

1 2 3 4 5 6 7 8 9 10

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

Note

Replace {payment_dispute_id} with the ID of the payment dispute.
Insert your actual Klarna API basic authorization string.
Replace "payment_dispute_attachment_id" with the actual attachment/file ID from Klarna’s file upload API.
Edit "description", "additional_information", and "partner_proposed_refund_amount" (amount in minor currency units) as appropriate.
Ensure "attachments" is a non-empty array with at least one attachment object
Omit optional keys (description, additional_information, partner_proposed_refund_amount) if not used.

Response

JSON

1 2 3 4 5 6 7 8 9 10

{
  "state": "REPRESENTMENT",
  "created_at": "2024-03-16T09:45:00Z",
  "additional_information": "The order was successfully delivered on March 15, 2024. Please see attached proof of delivery documentation with customer signature.",
  "attachments": [
    {
      "payment_dispute_attachment_id": "krn:payment:eu1:dispute:123456789:attachment:1",
      "description": "Proof of delivery documentation"
    }
  ]

Example 2 - Defend partial dispute amount

CONSOLE

1 2 3 4 5 6 7 8 9 10

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

Note

Replace {payment_dispute_id} with the ID of the payment dispute.
Insert your actual Klarna API basic authorization string.
Replace "payment_dispute_attachment_id" with the actual attachment/file ID from Klarna’s file upload API.
Edit "description", "additional_information", and "partner_proposed_refund_amount" (amount in minor currency units) as appropriate.
Ensure "attachments" is a non-empty array with at least one attachment object
Omit optional keys (description, additional_information, partner_proposed_refund_amount) if not used.

Response

JSON

1 2 3 4 5 6 7 8 9 10

{
  "state": "REPRESENTMENT",
  "created_at": "2024-03-16T09:45:00Z",
  "additional_information": "We accept 97 EUR out of the 100 EUR disputed amount. The 3 EUR difference represents the return shipping fee charged to the customer as per our return policy.",
  "attachments": [
    {
      "payment_dispute_attachment_id": "krn:payment:eu1:dispute:123456789:attachment:1",
      "description": "Return policy document showing 3 EUR return shipping fee"
    }
  ]

Appeal pre-arbitration decision

Use this endpoint to submit an appeal for a preliminary dispute decision by providing a summary of the reasons why the decision is considered incorrect when the dispute is in PRE_ARBITRATION state. The dispute will transition to state ARBITRATION while Klarna will review the appeal information.

Request Body

additional_information : Detailed explanation of why the preliminary decision is considered incorrect. Klarna will review this information when reconsidering the preliminary decision during the arbitration phase.

CONSOLE

1 2 3 4 5 6 7 8

curl -X POST \
  "https://api.klarna.com/v4/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."
  }'

Note

Replace {payment_dispute_id} with the dispute ID.
Replace {klarna_live_api_****} with your actual Klarna API credentials (base64 encoded).
Replace the text for additional_information with your detailed explanation for the appeal.

Response

JSON

1 2 3 4 5 6

{
  "state": "ARBITRATION",
  "created_at": "2020-05-09T09:32:18Z",
  "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 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 will be returned.

CONSOLE

1 2 3 4 5

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

Note

Replace {payment_dispute_id} with the dispute ID.
Replace {payment_dispute_attachment_id} with the attachment ID you wish to download.
Replace {klarna_live_api_****} with your Klarna API credentials (base64 encoded).
Replace output_filename.ext with the name you want to save the downloaded file as (e.g., evidence.pdf). Consult listDisputes endpoint for a complete description of the request body parameters.

How Merchants Can Respond to Disputes Using Their Existing Disputes Infrastructure

Merchants who handle disputes through their own dashboard or platform are required to integrate with Klarna’s dispute webhooks and API. This integration ensures a seamless dispute management experience with Klarna, consistent with other payment methods. By adopting these best practices, Merchants can safeguard their finances, resolve cases efficiently, and maintain strong, trust-based customer relationships. Effective dispute management also reduces chargebacks and enhances customer loyalty.

Alternate dispute solution

For Merchants who do not have a built-in dispute management flow or Merchant-facing dashboard, access to Klarna’s Merchant Portal may be provided. This enables direct handling of disputes through Klarna’s interface.

Even in these cases, integrating Klarna’s dispute webhooks is recommended. This gives Merchants real-time visibility into potential risks and outstanding dispute cases.

Best Practices for Integrating Your Disputes Infrastructure with Klarna

Integrate response capabilities: Ensure your dispute management system is integrated with Klarna’s Dispute API and webhooks, allowing direct submission of responses from your platform.
Submit evidence and responses: Merchants should upload all relevant documentation—such as shipping receipts, tracking numbers, and customer communications—directly through their 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. By enabling Merchants to manage disputes within their own existing systems, the overall process is streamlined, increasing the likelihood of timely, well-supported dispute resolution.