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.

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)

For webhook subscription setup, see Subscribing to webhook events.

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:

Dispute created and evidence requested

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

{
  "payment_dispute_id": "krn:payment:eu1:dispute:products-or-service-not-received:123456789",
  "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",
  "payment_capture_id": "krn:payment:eu1:capture:a1b2c3d4-5678-90ab-cdef-1234567890ab",
  "purchase_reference": "f420e0e1-971b-417a-8ece-2626387eff36",
  "product_id": "krn:partner:product:payment:ad71bc48-8a07-4919-a2c1-103dba3fc918",
  "state_context": {
    "representment": {

Dispute under review

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

{
  "payment_dispute_id": "krn:payment:eu1:dispute:products-or-service-not-received:123456789",
  "dispute_reason": "PRODUCTS_OR_SERVICES_NOT_RECEIVED",
  "state": "REPRESENTMENT",
  "previous_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",
  "payment_capture_id": "krn:payment:eu1:capture:a1b2c3d4-5678-90ab-cdef-1234567890ab",
  "purchase_reference": "f420e0e1-971b-417a-8ece-2626387eff36",
  "product_id": "krn:partner:product:payment:ad71bc48-8a07-4919-a2c1-103dba3fc918",
  "state_context": {

Klarna makes preliminary decision on dispute

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

{
  "payment_dispute_id": "krn:payment:eu1:dispute:products-or-service-not-received:123456789",
  "dispute_reason": "PRODUCTS_OR_SERVICES_NOT_RECEIVED",
  "state": "PRE_ARBITRATION",
  "previous_state": "REPRESENTMENT",
  "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",
  "payment_capture_id": "krn:payment:eu1:capture:a1b2c3d4-5678-90ab-cdef-1234567890ab",
  "purchase_reference": "f420e0e1-971b-417a-8ece-2626387eff36",
  "product_id": "krn:partner:product:payment:ad71bc48-8a07-4919-a2c1-103dba3fc918",
  "state_context": {

Appeal under review

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

{
  "payment_dispute_id": "krn:payment:eu1:dispute:products-or-service-not-received:123456789",
  "dispute_reason": "PRODUCTS_OR_SERVICES_NOT_RECEIVED",
  "state": "ARBITRATION",
  "previous_state": "PRE_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",
  "payment_capture_id": "krn:payment:eu1:capture:a1b2c3d4-5678-90ab-cdef-1234567890ab",
  "purchase_reference": "f420e0e1-971b-417a-8ece-2626387eff36",
  "product_id": "krn:partner:product:payment:ad71bc48-8a07-4919-a2c1-103dba3fc918",
  "arbitration": {

Dispute Closed

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

{
  "payment_dispute_id": "krn:payment:eu1:dispute:products-or-service-not-received:123456789",
  "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",
  "payment_capture_id": "krn:payment:eu1:capture:a1b2c3d4-5678-90ab-cdef-1234567890ab",
  "product_id": "krn:partner:product:payment:ad71bc48-8a07-4919-a2c1-103dba3fc918",
  "state_context": {

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

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

Response

{
  "disputes": [
    {
      "payment_dispute_id": "krn:payment:eu1:dispute:products-or-services-not-received:123456789",
      "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",
      "product_id": "krn:partner:product:payment:ad71bc48-8a07-4919-a2c1-103dba3fc918",
      "payment_account_id": "krn:partner:global:payment-account:test:3440b9b7-7ca2-44a3-8f62-776caacdaa0b",

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

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

Response

{
  "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",
  "payment_account_id": "krn:partner:global:payment-account:test:3440b9b7-7ca2-44a3-8f62-776caacdaa0b",
  "payment_account_reference": "REF995847",

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.

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

Response

{
  "state": "CLOSED"
}

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)

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"

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

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

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

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"
      }
      // You can add more attachment objects as needed
    ],

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

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

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"
      }
      // You can add more attachment objects as needed
    ],

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

{
  "partner_proposed_refund_amount": 9700,
  "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"
    }
  ]
}

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.

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.

Response

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

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.

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.

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