API & SDKsSupport

Disputes API v2 (2.0.0)

Download OpenAPI specification:Download

IMPORTANT NOTICE

Please be advised that new integrations to API v2 has been halted. A new API v2 r5 is now available for new integrations](https://docs.klarna.com/api/disputes-api/disputes-api-2.r5/). We appreciate your understanding and encourage you to check our documentation of the new version.

The Disputes API offers Klarna partners and merchants an easy way to handle customer disputes.

Use the available endpoints to:

  • Get a list of disputes, filtered by various parameters.
  • Get a full, detailed version of a dispute, including all the associated requests and responses.
  • Respond to a dispute request.
  • Download/upload a file attachment linked to a specific request response.
  • Accept loss for a dispute.

Please note that there are two ways to authenticate:

  • Klarna partners should authenticate via OAuth2 with client credentials. This allows access to multiple merchants in a single API call.
  • Klarna merchants (not partnered) should authenticate with basic auth credentials. Additionally, please set the x-klarna-basic-mid header to the merchant ID.

Before you get started, please make sure you understand the disputes process.

FAQ

  • Why is the API returning 403?
    • Please make sure your credentials and the endpoint you're calling are correct. Klarna APIs may also respond with a 403 for invalid paths.
  • Why doesn't the /enroll endpoint work?
    • Self-enrollment is currently only supported for basic merchants. If the merchant is a partner or related to a partner, it will fail.
  • GET v2/disputes returns an empty list, why?
    • Are you sure there are disputes to list?
    • Since you got through to the endpoint your client credentials are valid. Some partners or merchants may have been onboarded to the api incorrectly.
  • Why am I getting an invalid date format when responding to a dispute?
    • Only the following ISO 8601 format is currently supported: YYYY-MM-DDTHH:mm:ss.sssZ. Please note it includes ms.

Enroll to Disputes API

Self onboarding for merchants. Partner related merchants cannot self onboard through this API

SecurityOAuth2 or BasicAuth
Responses
204

Merchant successfully onboarded or was onboarded already

409

Merchant has a partner relation. Enroll is not permitted

post/disputes/v2/enroll
Request samples 
List disputes
Get a list of disputes, filtered by a variety of parameters parameters


SecurityOAuth2 or BasicAuth 
Request 
query Parameters
merchant_id
Array of strings
Merchant ID to filter by


 
order_id
Array of strings
Order ID to filter by


 
investigation_status
Array of strings
Investigation status of disputes to filter by


Items Enum: "opened" "started" "unresolved" "replied" "closed" "deadline_expired" "loss_accepted"  
reason
Array of strings
Dispute reason to filter by


Items Enum: "goods_not_received" "return" "incorrect_invoice" "already_paid" "faulty_goods" "pandemic_impact" "unauthorized_purchase" "high_risk_order"  
sort_by
Array of strings
 Default:  ["opened_at"]
Specifies in which order to sort the results. Then results are ordered in ascending order if not prefixed by a - which orders by descending order.


Items Enum: "deadline_expires_at" "-deadline_expires_at" "opened_at" "-opened_at"  
limit
integer <int32>   [ 1 .. 250 ] 
How many elements to include in the result


 
next_page
Array of strings
The IDs of the next result


 
merchant_references1
Array of strings
Merchant References 1 to filter by


 
merchant_references2
Array of strings
Merchant References 2 to filter by


 
Responses 
200
A paginated list of authorized disputes


400
Invalid request, check query parameters.


403
User not authorized to access the resource.


404
Dispute not found


get/disputes/v2/disputes
Request samples 
Response samples 
application/json
{
  • "disputes": [
    ],
  • "pagination": {
    }
}
Get dispute details
Fetch a fully detailed version of a Dispute, including all the associated requests and responses.


SecurityOAuth2 or BasicAuth 
Request 
path Parameters
dispute_krn
required
string
Klarna Resource Name of dispute to fetch


 
Responses 
200
Complete dispute with all requests and responses


404
Dispute not found


get/disputes/v2/disputes/{dispute_krn}
Request samples 
Response samples 
application/json
{
  • "capture_id": "6f343add-9c3d-4253-b449-fefe89d7b803",
  • "deadline_expires_at": "2020-05-22T00:00:00.000Z",
  • "dispute_krn": "krn:klarna:eu1:dispute:return:266091",
  • "investigation_status": "unresolved",
  • "merchant": {
    },
  • "opened_at": "2020-05-08T08:31:00.000Z",
  • "order": {
    },
  • "reason": "goods_not_received",
  • "region": "EU",
  • "requests": [
    ]
}
Download request attachment
Download a file attachment linked to a specific request.


SecurityOAuth2 or BasicAuth 
Request 
path Parameters
dispute_krn
required
string
Klarna Resource Name of dispute for which the attachment to fetch belongs to


 
request_id
required
integer
ID of request for which the attachment to fetch belongs to


 
attachment_id
required
integer
ID of the attachment to fetch


 
Responses 
200
File download of attachment


404
Attachment not found


get/disputes/v2/disputes/{dispute_krn}/requests/{request_id}/attachments/{attachment_id}
Request samples 
Response samples 
application/json
{
  • "error_code": "DISPUTE_NOT_FOUND",
  • "error_message": "A dispute krn 'krn:klarna:eu1:dispute:return:266091' could not be found"
}
Upload evidence attachment
Uploads an attachment to be linked to a dispute reponse. Accepts JPG, JPEG, PNG, PDF and DOCX with a maximum size of 7.3MB.


SecurityOAuth2 or BasicAuth 
Request 
path Parameters
dispute_krn
required
string
Klarna Resource Name of dispute for which the request to add response to belongs


 
Request Body schema: multipart/form-data
file
required
string <binary> 
 
filename
string
Name of a file to upload


 
Responses 
201
Attachment uploaded successfully


400
Incomplete request, missing required parameters.


404
Dispute not found


post/disputes/v2/disputes/{dispute_krn}/attachments
Request samples 
Response samples 
application/json
{
  • "attachment_id": 3,
  • "filename": "receipt.pdf"
}
Respond to a dispute
Respond to a dispute.


SecurityOAuth2 or BasicAuth 
Request 
path Parameters
dispute_krn
required
string
Klarna Resource Name of dispute for which the request to add response to belongs


 
request_id
required
integer
ID of request to add response to


 
Request Body schema: application/json
required
Response to add to request


attachments
required
Array of numbers
Attachment IDs of already uploaded attachments to link to the response


 
comment
string  <= 5000 characters 
Merchant comment regarding the associated response


 
required
object (RequestedFields) 
Data associated with the current dispute required by customer service that merchant should respond with


 
Responses 
201
Created response


400
Incomplete request, missing required parameters.


404
Dispute request not found


409
Dispute state incompatible


post/disputes/v2/disputes/{dispute_krn}/requests/{request_id}/responses
Request samples 
application/json
{
  • "attachments": [
    ],
  • "comment": "Comment from Merchant",
  • "requested_fields": {
    }
}
Response samples 
application/json
{
  • "attachments": [
    ],
  • "comment": "Comment from Merchant",
  • "created_at": "2020-05-08T12:32:55.697Z",
  • "requested_fields": {
    },
  • "response_id": 2
}
Download response attachments
Download a file attachment linked to a specific request response.


SecurityOAuth2 or BasicAuth 
Request 
path Parameters
dispute_krn
required
string
Klarna Resource Name of dispute for which the attachment to fetch belongs to


 
request_id
required
integer
ID of request for which the attachment to fetch belongs to


 
response_id
required
integer
ID of response for which the attachment to fetch belongs to


 
attachment_id
required
integer
ID of the attachment to fetch


 
Responses 
200
File download of attachment


404
Attachment not found


get/disputes/v2/disputes/{dispute_krn}/requests/{request_id}/responses/{response_id}/attachments/{attachment_id}
Request samples 
Response samples 
application/json
{
  • "error_code": "DISPUTE_NOT_FOUND",
  • "error_message": "A dispute krn 'krn:klarna:eu1:dispute:return:266091' could not be found"
}
Accept loss
Accept the loss of a dispute, which will be closed with the chargeback activation


SecurityOAuth2 or BasicAuth 
Request 
path Parameters
dispute_krn
required
string
Klarna Resource Name of dispute to accept loss for


 
Responses 
204
204 no content response


404
Dispute not found


409
Dispute state incompatible


post/disputes/v2/disputes/{dispute_krn}/accept-loss
Request samples 
Response samples 
application/json
{
  • "error_code": "DISPUTE_NOT_FOUND",
  • "error_message": "A dispute krn 'krn:klarna:eu1:dispute:return:266091' could not be found"
}
Cookies
Terms of Service
© Klarna 2024