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, filtered by a variety of 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 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.
Find out more about the Klarna REST APIs

Authentication

BasicAuth

Merchants (not partnered) should authenticate with basic auth credentials. Additionally, please set the x-klarna-basic-mid header to the merchant id.

Security Scheme Type HTTP
HTTP Authorization Scheme basic

OAuth2

Partners should authenticate via OAuth2 with client credentials. This allows access to multiple merchants in a single api call.

Security Scheme Type OAuth2
clientCredentials OAuth Flow
Token URL: /oauth2/v1/token
Scopes:
  • read -

    read:dispute

  • write -

    write:dispute

Disputes

List Disputes

Retrieve a list of Disputes, filtered by a variety of parameters parameters

Request
Security:
OAuth2 or BasicAuth
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
curl -i -X GET \
  'https://api.klarna.com/disputes/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: Bearer <YOUR_TOKEN_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:
OAuth2 or BasicAuth
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
curl -i -X GET \
  'https://api.klarna.com/disputes/v2/disputes/{dispute_krn}' \
  -H 'Authorization: Bearer <YOUR_TOKEN_HERE>'
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": [
    ]
}

Accept dispute loss

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

Request
Security:
OAuth2 or BasicAuth
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
curl -i -X POST \
  'https://api.klarna.com/disputes/v2/disputes/{dispute_krn}/accept-loss' \
  -H 'Authorization: Bearer <YOUR_TOKEN_HERE>'
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 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.

Request
Security:
OAuth2 or BasicAuth
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
curl -i -X POST \
  'https://api.klarna.com/disputes/v2/disputes/{dispute_krn}/attachments' \
  -H 'Authorization: Bearer <YOUR_TOKEN_HERE>' \
  -H 'Content-Type: multipart/form-data' \
  -F file=string \
  -F filename=receipt.pdf
Response samples
application/json
{
  • "attachment_id": 3,
  • "filename": "receipt.pdf"
}

Download request attachment

Download a file attachment linked to a specific request.

Request
Security:
OAuth2 or BasicAuth
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
curl -i -X GET \
  'https://api.klarna.com/disputes/v2/disputes/{dispute_krn}/requests/{request_id}/attachments/{attachment_id}' \
  -H 'Authorization: Bearer <YOUR_TOKEN_HERE>'
Response samples
application/json
{
  • "error_code": "DISPUTE_NOT_FOUND",
  • "error_message": "A dispute krn 'krn:klarna:eu1:dispute:return:266091' could not be found"
}

Respond to Dispute Request

Respond to a Dispute request.

Request
Security:
OAuth2 or BasicAuth
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/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 attachment

Download a file attachment linked to a specific request response.

Request
Security:
OAuth2 or BasicAuth
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
curl -i -X GET \
  'https://api.klarna.com/disputes/v2/disputes/{dispute_krn}/requests/{request_id}/responses/{response_id}/attachments/{attachment_id}' \
  -H 'Authorization: Bearer <YOUR_TOKEN_HERE>'
Response samples
application/json
{
  • "error_code": "DISPUTE_NOT_FOUND",
  • "error_message": "A dispute krn 'krn:klarna:eu1:dispute:return:266091' could not be found"
}

Enroll merchant to disputes API

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

Request
Security:
OAuth2 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
curl -i -X POST \
  https://api.klarna.com/disputes/v2/enroll \
  -H 'Authorization: Bearer <YOUR_TOKEN_HERE>'