API & SDKsSupport

Klarna Partner Product API - Payment (v3)

Download OpenAPI specification:Download

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.

Klarna merchants consuming Disputes API are authenticated via the OAuth 2.0 protocol.

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 v3/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.

It's also important to note that the following fields are referred to by different names in the Order Management API:

  • payment_transaction_id is referred as order_id
  • purchase_reference is referred as merchant_reference
  • payment_capture_reference is referred as capture_id

Payment Dispute API

Self onboarding for merchants

Self onboarding for merchants. Partners cannot self onboard through this API

Request
path Parameters
merchant_id
required
string

Merchant ID

Responses
204

Merchant successfully onboarded or was onboarded already

409

Merchant has a partner relation. Enroll is not permitted

post/disputes/v3/disputes/merchants/{merchant_id}/enroll
Request samples 
Self onboarding for partners
Self onboarding for Partners. Onboard a Partner to this API given their oAuth client ID. Merchants cannot self onboard through this API


Request 
path Parameters
partner_id
required
string
Partner ID


 
Request Body schema: application/json
required
Request body for self onboarding


client_id
required
string  [ 1 .. 64 ] characters ^[a-zA-Z0-9]+$
The unique OAuth2 client Id of the merchant


 
Responses 
204
Partner successfully onboarded or was onboarded already


post/disputes/v3/disputes/partners/{partner_id}/enroll
Request samples 
application/json
Self onboard to the API


{
  • "client_id": "abcdefghijklmnop1234567890"
}
List Disputes
Retrieve a list of Disputes, segregated by a variety of filter parameters


Request 
query Parameters
payment_product_instance_id
Array of strings
Product Instance IDs to filter by


 
 Example:  payment_product_instance_id=krn:partner:product:payment:ad71bc48-8a07-4919-a2c1-103dba3fc918
payment_transaction_id
Array of strings (PaymentTransactionId) 
Payment Transaction IDs to filter by


 
 Example:  payment_transaction_id=922c722-bd7a-449b-ad54-d9c2cc52dff9
Array of strings (PaymentDisputeState) 
States of disputes to filter by


 
reason
Array of strings (PaymentDisputeReason) 
Dispute reason to filter by


Items Enum: "RETURN_NOT_REFUNDED" "PRODUCTS_NOT_RECEIVED" "PRODUCTS_FAULTY" "CAPTURE_AMOUNT_INCORRECT" "PURCHASE_CANCELED" "PURCHASE_UNAUTHORIZED" "PURCHASE_HIGH_RISK"  
 Example:  reason=PRODUCTS_NOT_RECEIVED
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"  
purchase_references
Array of strings (PurchaseReference) 
Merchant References to filter by


 
 Example:  purchase_references=f420e0e1-971b-417a-8ece-2626387eff36
opened_at_start
Array of strings <date-time>  (Timestamp) 
Used to filter by dispute open dates. Only disputes created after (including) the supplied value will be returned.


 
 Example:  opened_at_start=2024-01-01T12:00:00Z
opened_at_end
Array of strings <date-time>  (Timestamp) 
Used to filter by dispute open dates. Only disputes created before (excluding) the supplied value will be returned.


 
 Example:  opened_at_end=2024-01-01T12:00:00Z
closed_at_start
Array of strings <date-time>  (Timestamp) 
Used to filter by dispute close dates. Only disputes closed after (including) the supplied value will be returned.


 
 Example:  closed_at_start=2024-01-01T12:00:00Z
closed_at_end
Array of strings <date-time>  (Timestamp) 
Used to filter by dispute close dates. Only disputes closed before (excluding) the supplied value will be returned.


 
 Example:  closed_at_end=2024-01-01T12:00:00Z
size
integer <int32> 
Limits the number of items to be returned. If omitted, the default page size will be used.


 
 Example:  size=20
starting_after
string
A cursor used in pagination, referring to a specific item. The last_item returned from a previous call can be used here. The next page will list items after this item. Cannot be used together with ending_before. If both starting_after and ending_before are omitted, the first page will be returned.


 
 Example:  starting_after=Zpq6F3mDYtwK8
Responses 
200
A paginated list of authorized disputes


400
Bad Request, there was an error in the input of the request.
The request can not be retried without modifications.


401
Unauthorized, the request was not authorized.


403
Forbidden, insufficient privileges to perform the requested operation on the resource.


404
Not Found, the requested resource was not found.


429
Too Many Requests, the request was rate limited.


500
Internal Server Error, there was an unexpected error in the API.


get/disputes/v3/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.


Request 
path Parameters
payment_dispute_id
required
string
ID of dispute to fetch


 
Responses 
200
Complete dispute with all requests and responses


400
Bad Request, there was an error in the input of the request.
The request can not be retried without modifications.


401
Unauthorized, the request was not authorized.


404
Not Found, the requested resource was not found.


429
Too Many Requests, the request was rate limited.


500
Internal Server Error, there was an unexpected error in the API.


Callbacks 
postDispute state changed webhook callback
postDispute updated webhook callback
get/disputes/v3/disputes/{payment_dispute_id}
Request samples 
Response samples 
application/json
{
  • "payment_dispute_id": "krn:payment:eu1:dispute:faulty-products:266091",
  • "dispute_reason": "PRODUCTS_FAULTY",
  • "state": "ARBITRATION_PENDING",
  • "previous_state": "MERCHANT_EVIDENCE_PENDING",
  • "payment_transaction_id": "krn:payment:eu1:authorization:6debe89e-98c0-486e-b7a5-08a4f6df94b0",
  • "payment_capture_reference": "partner-capture-reference-1234",
  • "purchase_reference": "f420e0e1-971b-417a-8ece-2626387eff36",
  • "payment_product_instance_id": "krn:partner:product:payment:ad71bc48-8a07-4919-a2c1-103dba3fc918",
  • "dispute_details": {
    },
  • "merchant_evidence": [
    ],
  • "config": {
    },
  • "created_at": "2020-04-15T08:31:00Z",
  • "updated_at": "2020-05-09T08:31:00Z",
  • "arbitration_started_at": "2020-05-08T00:00:00Z"
}
Callback payload samples 
application/json
A payment dispute has just been submitted to Klarna.


{
  • "metadata": {
    },
  • "payload": {
    }
}
Accept dispute loss
Accept the loss of a dispute, which will be closed with the chargeback activation


Request 
path Parameters
payment_dispute_id
required
string
ID of dispute to accept loss for


 
Responses 
202
Loss was accepted successfully


400
Bad Request, there was an error in the input of the request.
The request can not be retried without modifications.


401
Unauthorized, the request was not authorized.


404
Not Found, the requested resource was not found.


409
The dispute is not in a state where the loss can be accepted. Read the error details for further information.


429
Too Many Requests, the request was rate limited.


500
Internal Server Error, there was an unexpected error in the API.


post/disputes/v3/disputes/{payment_dispute_id}/accept-loss
Request samples 
Response samples 
application/json
{
  • "error_id": "5a3f6b9c-9b3b-4b7e-8f9d-9b9a4b9a4b9a",
  • "error_type": "INPUT_ERROR",
  • "error_code": "INVALID_CONTENT_TYPE",
  • "error_message": "The received input is not valid JSON.\nUnterminated string at 19 [character 20 line 1].\n"
}
Upload merchant evidence attachment
Uploads merchant attachment to be linked to a dispute response. File size limit is 7MB.


Request 
path Parameters
payment_dispute_id
required
string
ID 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> 
File contents


 
Responses 
201
Attachment uploaded successfully


400
Bad Request, there was an error in the input of the request.
The request can not be retried without modifications.


401
Unauthorized, the request was not authorized.


403
Forbidden, insufficient privileges to perform the requested operation on the resource.


404
Not Found, the requested resource was not found.


429
Too Many Requests, the request was rate limited.


500
Internal Server Error, there was an unexpected error in the API.


post/disputes/v3/disputes/{payment_dispute_id}/attachments
Request samples 
Response samples 
application/json
{
  • "payment_dispute_attachment_id": "krn:payment:eu1:dispute:256947:attachment:3"
}
Respond to merchant evidence request
Respond to merchant evidence request.


Request 
path Parameters
payment_dispute_id
required
string
ID of dispute for which the request to add response to belongs


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


One of:
Merchant response to a dispute where the customer claims that the products were faulty


additional_information
string
Free-text string with additional information about the dispute response


 
Array of objects (PaymentDisputeRespondToEvidenceRequestPayloadAttachment) 
List of evidence provided by the merchant to support the dispute response.


 
required
object
 
Responses 
201
Dispute's evidence request response was submitted successfully


400
Bad Request, there was an error in the input of the request.
The request can not be retried without modifications.


401
Unauthorized, the request was not authorized.


403
Forbidden, insufficient privileges to perform the requested operation on the resource.


404
Not Found, the requested resource was not found.


409
The dispute is not in a state where a response can be submitted.


429
Too Many Requests, the request was rate limited.


500
Internal Server Error, there was an unexpected error in the API.


post/disputes/v3/disputes/{payment_dispute_id}/respond
Request samples 
application/json
Responding to an evidence request with request type 'RETURN_NOT_REFUNDED'


{
  • "additional_information": "Additional free text information",
  • "created_at": "2020-05-08T08:32:14Z",
  • "attachments": [
    ],
  • "details": {
    }
}
Response samples 
application/json
{
  • "response_id": "krn:payment:eu1:dispute:266092:request:1:response:1",
  • "created_at": "2020-05-09T09:32:18Z",
  • "additional_information": "Additional free text information",
  • "attachments": [
    ],
  • "details": {
    }
}
Download dispute attachment
 Downloads either a merchant attachment linked to a response or the customer evidence attachment linked to a request.


Request 
path Parameters
payment_dispute_id
required
string
ID of dispute for which the request to add response to belongs


 
payment_dispute_attachment_id
required
string
ID of the attachment to download


 
Responses 
200
 Attachment was downloaded successfully


400
Bad Request, there was an error in the input of the request.
The request can not be retried without modifications.


401
Unauthorized, the request was not authorized.


403
Forbidden, insufficient privileges to perform the requested operation on the resource.


404
Not Found, the requested resource was not found.


500
Internal Server Error, there was an unexpected error in the API.


post/disputes/v3/disputes/{payment_dispute_id}/attachments/{payment_dispute_attachment_id}/download
Request samples 
Response samples 
application/json
{
  • "error_id": "5a3f6b9c-9b3b-4b7e-8f9d-9b9a4b9a4b9a",
  • "error_type": "INPUT_ERROR",
  • "error_code": "INVALID_CONTENT_TYPE",
  • "error_message": "The received input is not valid JSON.\nUnterminated string at 19 [character 20 line 1].\n"
}
Cookies
Terms of Service
© Klarna 2025