Disputes API v2 (2.0.0)

Download OpenAPI specification:Download

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

Utilizing the available endpoints, you are able to:

  • Retrieve a list of Disputes, segregated by a variety of filter parameters.
  • Fetch a fully 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 the dispute loss.

Klarna merchants consuming Disputes API are authenticated via the OAuth 2.0 protocol. As part of your credentials you have the possibility to specify a webhook endpoint to receive notifications when your input is needed for a dispute.

Read more on the Disputes process.

Find out more about the Klarna REST APIs

Authentication

apiUser

Security Scheme Type API Key
Header parameter name: Authorization

Disputes

List Disputes

Retrieve a list of Disputes, segregated by a variety of filter parameters

Request
Security:
apiUser
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/v2/disputes
Request samples
curl -i -X GET \
  'https://api.klarna.com/v2/disputes?merchant_id=string&order_id=string&investigation_status=opened&reason=goods_not_received&sort_by=opened_at&limit=1&next_page=string&merchant_references1=string&merchant_references2=string' \
  -H 'Authorization: YOUR_API_KEY_HERE'
Response samples
application/json
{
  • "disputes": [
    ],
  • "pagination": {
    }
}

Get Dispute Details

Fetch a fully detailed version of a Dispute, including all the associated requests and responses.

Request
Security:
apiUser
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/v2/disputes/{dispute_krn}
Request samples
curl -i -X GET \
  'https://api.klarna.com/v2/disputes/{dispute_krn}' \
  -H 'Authorization: YOUR_API_KEY_HERE'
Response samples
application/json
{
  • "capture_id": "4ba29b50-be7b-44f5-a492-113e6a865e22",
  • "charged_disputes_fee": {
    },
  • "closed_at": "2018-12-03T10:26:06Z",
  • "closing_reason": "resolved",
  • "closing_reason_detailed": "merchant_did_not_reply_to_dispute_request",
  • "deadline_expires_at": "2018-12-03T00:00:00Z",
  • "dispute_krn": "krn:klarna:eu1:dispute:faulty-goods:256947",
  • "disputed_amount": {
    },
  • "disputed_order_lines": [
    ],
  • "investigation_status": "closed",
  • "merchant": {
    },
  • "opened_at": "2018-12-03T10:26:06Z",
  • "order": {
    },
  • "reason": "goods_not_received",
  • "region": "EU",
  • "requests": [
    ],
  • "status": "open"
}

Accept dispute loss

Accept the loss of a dispute, which will be closed with the chargeback activation

Request
Security:
apiUser
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/v2/disputes/{dispute_krn}/accept-loss
Request samples
curl -i -X POST \
  'https://api.klarna.com/v2/disputes/{dispute_krn}/accept-loss' \
  -H 'Authorization: YOUR_API_KEY_HERE'
Response samples
application/json
{
  • "error_code": "MISSING_PARAMETER",
  • "error_message": "Invalid request received, missing request body"
}

Upload attachment

Uploads an attachment to be linked to a dispute reponse

Request
Security:
apiUser
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
filename
string

Name of a file to upload

file
required
string <binary>
Responses
201

Attachment uploaded successfully

400

Incomplete request, missing required parameters.

404

Dispute not found

post/v2/disputes/{dispute_krn}/attachments
Request samples
curl -i -X POST \
  'https://api.klarna.com/v2/disputes/{dispute_krn}/attachments' \
  -H 'Authorization: YOUR_API_KEY_HERE' \
  -H 'Content-Type: multipart/form-data' \
  -F filename=string \
  -F file=string
Response samples
application/json
{
  • "attachment_id": 3,
  • "filename": "receipt.pdf"
}

Download request attachment

Download a file attachment linked to a specific request.

Request
Security:
apiUser
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/v2/disputes/{dispute_krn}/requests/{request_id}/attachments/{attachment_id}
Request samples
curl -i -X GET \
  'https://api.klarna.com/v2/disputes/{dispute_krn}/requests/{request_id}/attachments/{attachment_id}' \
  -H 'Authorization: YOUR_API_KEY_HERE'
Response samples
No sample

Respond to Dispute Request

Respond to a Dispute request.

Request
Security:
apiUser
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

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/v2/disputes/{dispute_krn}/requests/{request_id}/responses
Request samples
application/json
{
  • "attachments": [
    ],
  • "comment": "All the requested fields are addressed as requested",
  • "requested_fields": {
    }
}
Response samples
application/json
{
  • "attachments": [
    ],
  • "comment": "All the requested fields are addressed as requested",
  • "created_at": "2018-12-03T10:26:06Z",
  • "requested_fields": {
    },
  • "response_id": 2
}

Download response attachment

Download a file attachment linked to a specific request response.

Request
Security:
apiUser
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/v2/disputes/{dispute_krn}/requests/{request_id}/responses/{response_id}/attachments/{attachment_id}
Request samples
curl -i -X GET \
  'https://api.klarna.com/v2/disputes/{dispute_krn}/requests/{request_id}/responses/{response_id}/attachments/{attachment_id}' \
  -H 'Authorization: YOUR_API_KEY_HERE'
Response samples
No sample