Disputes integration with API

Integrate with 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 Partner as Acquiring 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.

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 (representment-deadline-extended) For webhook subscription setup, see Subscribing to webhook events.

State change webhooks

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

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 on dispute

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

Dispute update (no state change) webhooks

Dispute updated webhooks notify Partners of dispute updates that do not include a dispute state change

See paymentDisputeUpdatedWebhook API

to get a full description of the payload.

Representment deadline extended

Webhook event - payment.dispute.updated.representment-deadline-extended

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-global.klarna.com/v2/accounts/partner_account_id/payment/disputes?state=INITIATED&sort_by=-created_at&size=25" \
  -H "Authorization: Basic {klarna_live_api_****}" \
  -H "Content-Type: application/json"

Note

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

See listDisputes API

to get a full description of the request and response.

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-global.klarna.com/v2/accounts/{partner_account_id}/payment/disputes/{payment_dispute_id}" \
  -H "Authorization: Basic {klarna_live_api_****}" \
  -H "Content-Type: application/json"

Note

Replace partner_account_id with your actual Klarna partner account ID.
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).

See getDisputeDetails API

to get a full description of the request and response.

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-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"

Note

Replace {partner_account_id} with your actual Klarna partner account ID (e.g., krn:partner:global:account:live:LWT2XJSE)
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

See acceptLoss API

to get a full description of the request and response.

Upload partner evidence attachment

Upload a partner 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)

Note

Replace {partner_account_id} with your Klarna partner account ID.
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

See uploadAttachment API

to get a full description of the request and response.

Respond to Representment Request

Use this endpoint to submit partner 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 partner to support the dispute response. Partner 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 partner 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-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:payment:eu1:dispute:123456789:attachment:1",
        "description": "Proof of delivery documentation"
      }

Note

Replace {partner_account_id} with your actual Klarna account ID.
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.

Example 2 - Defend partial dispute amount

CONSOLE

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:payment:eu1:dispute:123456789:attachment:1",
        "description": "Return policy document showing 3 EUR return shipping fee"
      }

Note

Replace {partner_account_id} with your actual Klarna account ID.
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

See respondToDisputeRequest API

to get a full description of the request and response.

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-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."
  }'

Note

Replace {partner_account_id} with your Klarna partner account ID.
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.

See appealDispute API

to get a full description of the request and response.

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-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

Note

Replace {partner_account_id} with your Klarna partner account ID.
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 the API reference for a complete description of the request body parameters.

See getDisputeAttachment API

to get a full description of the request and response.

How Partners Can Respond to Disputes Using Their Existing Disputes Infrastructure

Partners 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, partners 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 acquiring partners who do not have a built-in dispute management flow or partner-facing dashboard, access to Klarna Partner 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 acquiring partners 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: Partners 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 partners to manage disputes within their own existing systems, the overall process is streamlined, increasing the likelihood of timely, well-supported dispute resolution.

Testing

In the test environment, you can drive a dispute through a predetermined lifecycle by tagging the customer email with a dispute flag. Once the dispute is created and escalated, Klarna's test infrastructure plays out the corresponding state transitions automatically and emits the same payment.dispute.state-change webhooks you'd receive in production.

Where to place the flag

The flag is read from the local part of the customer email in the following Payment Authorization field:

supplementary_purchase_data.customer.email

The flag is matched as a +-prefixed substring of the local part, so it can be combined with other test-routing tokens (for example customer+se+dispute_win_on_evidence@klarna.com).

JSON

1 2 3 4 5 6 7

{
  "supplementary_purchase_data": {
    "customer": {
      "email": "customer+se+dispute_win_on_evidence@klarna.com"
    }
  }
}

Dispute lifecycle flags

Flag	Effect after the dispute is created and escalated
`dispute_win_on_evidence`	Waits for the Partner to submit evidence, then resolves the dispute in the Partner's favor.
`dispute_lose_on_evidence`	Waits for the Partner to submit evidence, then resolves the dispute against the Partner.
`dispute_lose_on_expiry`	Auto-closes the dispute as a Partner loss to simulate the Partner failing to respond before the deadline.
`dispute_pre_arb_window_expired`	Waits for evidence, then simulates the pre-arbitration window expiring without further Partner action.
`dispute_pre_arb_accept_loss`	Auto-closes the dispute with the Partner accepting the loss to simulate the Partner choosing not to enter pre-arbitration.
`dispute_pre_arb_lose_after_arbitration`	Waits for evidence and, subsequently, an appeal. After arbitration, the dispute is resolved against the Partner.
`dispute_pre_arb_win_after_arbitration`	Waits for evidence and, subsequently, an appeal. After arbitration, the dispute is resolved in the Partner's favor.

For the full set of test customers and per-market sample data, see Sample customer data - Disputes.

The dispute flag mechanism is only honored in the test environment. Payment Authorizations in production ignore these flags.

Setup your webhooks

Sample customer data - Disputes

API & SDK references

Klarna Partner Product API - Payment