Klarna Docs - Disputes API V3 integration
API and SDKsSupport
Disputes API V3 integration

Integrate Klarna’s Dispute API V3 to streamline dispute management, minimize financial impact, and protect customer relationships.

​​A "dispute" occurs when a customer questions a payment due to issues like not receiving goods, unauthorized transactions, or dissatisfaction with a product. Efficiently managing disputes through Klarna’s Dispute API allows Partners/Merchants to respond in a structured manner, minimize financial impact, and resolve issues promptly.

Acquiring Partners who present disputes within a dashboard are required to integrate Klarna dispute handling, such that the friction of dispute handling for Klarna does not differ from other payment methods. By following these guidelines, Partners/Merchants can protect their finances and keep strong relationships with customers. Efficiently resolving disputes reduces chargebacks and builds customer loyalty.

Alternate dispute solution

For Acquiring Partners without a dispute handling flow or Partner-facing dashboard, direct provisioning of Klarna’s Partner Portal may be given to Partners, allowing direct management of disputes.

Integration of Disputes webhooks by the Acquiring Partner is still recommended in these cases, to ensure the Acquiring Partner has visibility on risk factors and outstanding dispute cases.

A dispute typically progresses through several states from initiation to resolution. Understanding these states is crucial for effectively managing disputes:

flowchart LR A(["PRE-ARBITRATION"]) --> |High-risk or Unauthorized order| B(["ARBITRATION PENDING"]) A --> |Unresolved After 21 Days|B A --> |Escalation by Klarna| B %% Arbitration Pending to Closed B --> |Merchant accepts loss| C(["CLOSED"]) D(["MERCHANT EVIDENCE PENDING"]) --> |Merchant submits evidence|B D --> |Submission window expired|B D --> |Merchant accepts loss| C %% Decision handling B --> |Klarna requests evidence|D B --> h[Klarna evaluates case] h --> |Additional evidence required| D h --> |Customer wins| K(["ARBITRATION APPEAL OPEN - disabled after R5"]) h --> |Merchant wins| C K --> |Challenge expired or Merchant accepts decision| C K --> |Additional evidence required by appeal| B

Arbitration Appeal will be completed in a later release.

StateTriggerWebhookExpected actionDispute state duration
Pre-arbitrationA customer initiates a dispute.payment.dispute.state-change.pre-arbitration – Provides the Partner/Merchant with essential information about the dispute.Klarna alerts the Partner/Merchant with initial dispute details through a payment.dispute.state-change.pre-arbitration webhook. Partners should review the dispute specifics and prepare any initial response or can accept loss at this stage in order to avoid dispute fees since Klarna will not charge the dispute fee at this stage.The duration a dispute remains in its initial state varies based on the type of dispute.
Immediate transition to arbitration pending: Disputes categorized as ​High Risk Purchase​ and ​Unauthorized Purchase​ will transition immediately to the next state, which is ​Arbitration Pending​.21-Day minimum duration: Disputes related to the following categories will remain in the initial state for a minimum of 21 days before transitioning to ​Arbitration Pending​:
  1. Return not possible
  2. Return not refunded
  3. Goods or services not received
  4. Not as described or defective goods
  5. Incorrect amount
  6. Purchase Cancelled
Agent discretion: Klarna has the authority to advance a dispute to the next state prior to the completion of the 21-day period, based on their discretion. These scenarios include, but are not limited to:
  1. Disputes related to Debt Collection
  2. Complaints
  3. Claims raised by an external authority (for example ARN in SWE)
Merchant Evidence PendingKlarna formally requests evidence from the Partner/Merchant.payment.dispute.state-change.merchant-evidence-pending – Prompts the Partner/Merchant to provide requested documentation.Partners/Merchants must upload and submit specific evidence via the Dispute API. Attach the attachment ID received after upload in response to the payment.dispute.state-change.merchant-evidence-pending webhook.Partners/Merchants are given 14 days to respond to an evidence request. The dispute will remain in this state until evidence is submitted or the window for evidence submission expires.
ClosedThe dispute reaches a resolution.payment.dispute.state-change.closed – Confirms that the dispute has been finalized and indicates the outcome.If the dispute closes in favor of the customer, the Partner/Merchant may incur a chargeback. If the Partner/Merchant prevails, no additional action is required.

Disputes can arise in various situations during a payment transaction. Below are some scenarios to illustrate different pathways to resolve disputes. A dispute is considered resolved once:

  • Loss accepted: If the evidence clearly supports the customer’s claim, the Partner/Merchant may choose to accept the loss and issue a refund or replacement.
  • Closed - lost: Evidence provided by the Partner/Merchant was insufficient, resulting in Klarna ruling in favor of the customer.
  • Closed - won: Evidence provided by the Partner/Merchant proved that they acted appropriately and all goods were delivered as promised, resulting in Klarna ruling in favor of the Partner/Merchant.

Example 1: Products not received

  • Scenario: A customer named Emily places an order for a laptop from ShopStore Electronics. After the expected delivery date passed, Emily contacts ShopStore to report that she hasn’t received the laptop.
  • Dispute Trigger: Emily initiates a dispute through Klarna, claiming products not received
  • Webhook: payment.dispute.state-change.pre-arbitration
  • Expected Action: The Partner/Merchant should provide tracking details, proof of shipment, and delivery confirmation if available.
  • Resolution Pathway 1: ShopStore reviews Emily’s dispute and checks their shipping records. They confirm that the laptop was shipped but delayed due to an issue with the courier. ShopStore provides tracking information and proof of shipment through Klarna’s Dispute API, along with an updated delivery timeline. Emily receives the package and confirms its delivery through Klarna.
  • Resolution Pathway 2: ShopStore reviews Emily’s dispute and finds evidence that the laptop was delivered to the correct address. They submit proof of delivery through Klarna’s Dispute API. Klarna reviews the evidence and determines that the package was delivered as promised. The dispute is closed in ShopStore’s favor.
  • Required Evidence: Shipping confirmation, tracking ID, proof of delivery and recipient name for validation.

Example 2: Products faulty

  • Scenario: James orders a set of dining chairs from HomeStyle Furniture. Upon delivery, he finds that one of the chairs is damaged.
  • Dispute Trigger: James raises a dispute, stating that the goods were delivered in poor condition.
  • Webhook: payment.dispute.state-change.pre-arbitration
  • Expected Action: Partners/Merchants should submit photos of the returned item, shipment details, and any customer correspondence.
  • Resolution Pathway 1: HomeStyle Furniture reviews James's dispute and requests photos of the damaged chair. After verifying the damage through the provided images, they acknowledge the issue. HomeStyle Furniture offers James a replacement chair at no additional cost and ships the new item promptly. HomeStyle provides the evidence of replacement chair by Klarna Disputes API
  • Resolution Pathway 2: HomeStyle Furniture reviews James's dispute and the provided photos. They find that the chair’s condition does not match the description of damage or believe the issue resulted from misuse after delivery. HomeStyle Furniture submits evidence via Klarna’s Dispute API. Klarna reviews the evidence, determines that HomeStyle Furniture is not liable, and closes the dispute in their favor.
  • Required Evidence: Confirmation that changes will be made to order or alternative resolution was arrived at. Transaction IDs and/or numerical discounts in form of attachment is required

Example 3: Capture amount incorrect

  • Scenario: Olivia purchases a smartwatch from GadgetGrove using Klarna’s payment services. However, when she checks her bank statement, she notices that she has been charged twice for the same item.
  • Dispute Trigger: Olivia contacts GadgetGrove and subsequently raises a dispute through Klarna, claiming an incorrect charge.
  • Webhook: payment.dispute.state-change.pre-arbitration
  • Resolution Pathway 1: GadgetGrove reviews their payment records and confirms that a duplicate charge occurred due to a system error. They promptly issue a refund for the extra payment through Klarna’s Dispute API and provide evidence, such as transaction logs and invoice copies, to support the resolution. Klarna reviews the submission and informs Olivia of the refund.
  • Resolution Pathway 2: GadgetGrove reviews their payment records and finds no evidence of a duplicate charge. Their investigation shows that the transactions on Olivia’s statement correspond to separate orders or activities. GadgetGrove submits evidence via Klarna’s Dispute API to demonstrate that the charges were legitimate. Klarna reviews the evidence, determines that the charges are valid, and closes the dispute in GadgetGrove’s favor.
  • Required Evidence: Relevant financial records and invoice copies in form of attachment.

Example 4: Purchase unauthorized

  • Scenario: Michael notices a transaction on his account for a high-end gaming console from GameHub, a store he has never shopped at.
  • Dispute Trigger: Michael suspects fraud and files a dispute through Klarna, stating that the purchase was unauthorized.
  • Webhook: payment.dispute.state-change.pre-arbitration
  • Expected Action: GamyHub should investigate the purchase and supply any fraud prevention measures taken (e.g., proof of customer ID verification).
  • Resolution Pathway 1: GameHub investigates the transaction and finds that it was made using stolen card information. They confirm that the purchase was unauthorized and promptly cancel the order. GameHub refunds Michael and provides the required evidence to clarify the situation. Klarna reviews the evidence, confirms the refund, and updates Michael.
  • Resolution Pathway 2: GameHub investigates the transaction and finds no evidence of fraud. Their review shows that the order was placed from a device and location consistent with previous purchases associated with Michael’s account. They submit evidence via Klarna’s Dispute API. Klarna reviews the evidence and determines that the transaction appears legitimate.
  • Required Evidence: Transaction details, customer verification steps, and any fraud reports.

Example 5: Return not refunded

  • Scenario: A customer, Sarah, returns an item purchased from FashionFusion, an online apparel store. Despite receiving confirmation from the courier that the return was delivered to FashionFusion's warehouse, Sarah hasn't received her refund after 14 days.
  • Dispute Trigger: Sarah contacts Klarna to initiate a dispute, claiming "Refund not received."
  • Webhook: payment.dispute.state-change.pre-arbitration
  • Expected Action: Confirm receipt of returned items; specify condition or reason if not accepted.
  • Resolution Pathway 1: FashionFusion reviews their return records and confirms receipt of the item. They discover that the refund was delayed due to a processing error. FashionFusion promptly issues the refund to Sarah and notifies her of the resolution through Klarna’s Dispute API. Sarah confirms receipt of the refund, and the dispute is resolved and closed.
  • Resolution Pathway 2: FashionFusion reviews their return records and finds no evidence of receiving the returned item. They submit proof via Klarna’s Dispute API, including warehouse logs and courier tracking data, showing that the return was never delivered. Klarna reviews the submitted evidence, determines that FashionFusion is not liable, and closes the dispute in their favor. Sarah is notified of the decision, and the case is resolved.
  • Required Evidence: Return policy compliance, item photos, or tracking records for returned items, acknowledgement of return.

In certain situations, it may be more practical for a partner/merchant to accept a loss rather than contest a dispute. Accepting a loss means acknowledging that the customer’s claim is valid and agreeing to resolve the dispute by issuing a refund or replacement without further investigation. This approach can save time and resources, especially when the evidence strongly supports the customer or when the cost of defending the dispute outweighs the potential loss.

Consider accepting a loss in the following scenarios:

  • Strong evidence against the partner/merchant: The evidence provided by the customer is compelling, such as clear proof of non-receipt, unauthorized transactions, or defective products.
  • High cost of defense: The cost of gathering and submitting additional evidence, such as legal fees or operational costs, exceeds the amount in dispute.
  • Customer relationship considerations: Maintaining a positive relationship with the customer may be more valuable than the disputed amount, especially in cases involving loyal customers or high-value transactions.
  • Small disputed amounts: When the amount in dispute is relatively small, it may not be worth the effort to contest the dispute.

Accepting a loss can have several implications:

  • Financial adjustments: The disputed amount will be refunded to the customer, and any associated fees, such as chargeback fees, will be applied to the partner/merchant.
  • Impact on payouts: Accepting a loss may result in adjustments to your payouts, depending on the payment method and terms of the dispute.
  • Customer trust: Resolving the dispute quickly and amicably by accepting a loss can enhance customer satisfaction and loyalty.

The process for accepting a loss typically involves the following steps:

  1. Review the dispute: Assess the evidence provided by the customer and determine if accepting the loss is the best course of action.
  2. Use Klarna’s dispute API: To accept the loss, make the appropriate API call through Klarna’s Dispute API. This action will close the dispute and trigger the refund process.
  3. Document the decision: Keep a record of the decision to accept the loss, including any evidence reviewed and the reasoning behind the decision. This documentation can be valuable for future reference or internal audits.
  4. Encourage partner/merchant to communicate with the customer: Proactively notify the customer that their dispute has been resolved in their favor. This communication should be clear, concise, and appreciative, reinforcing a positive customer experience.

Example

FashionFusion, an online store, receives a dispute from Karen, a customer claiming that the handbag she received was damaged. Karen provides clear photos showing the damage, and the cost of shipping a replacement is low compared to the potential cost of contesting the dispute. After reviewing the evidence, FashionFusion decides to accept the loss and promptly issues a refund to Karen. This resolution not only saves time and resources for FashionFusion but also leaves Karen satisfied with the quick and fair resolution.

Providing shipping or delivery evidence is crucial in resolving disputes where a customer claims non-receipt of goods or delayed delivery. By submitting clear and accurate evidence, you can substantiate that the goods were shipped or delivered as agreed. This evidence plays a vital role in defending against disputes and ensuring that the resolution process is fair and transparent.

Importance of Shipping/Delivery Evidence: In disputes involving non-receipt or delayed delivery of goods, shipping or delivery evidence is often the deciding factor. This evidence helps verify that the transaction was completed according to the terms agreed upon by both the partner/merchant and the customer. Without this evidence, the dispute is likely to be resolved in favor of the customer, potentially leading to financial loss and a negative impact on your business’s reputation.

You can submit various types of evidence to support your case, including:

  • Shipping receipts: Documentation that confirms the goods were shipped to the customer’s address.
  • Tracking numbers: Unique identifiers provided by the shipping carrier that allow tracking of the shipment’s progress.
  • Delivery confirmations: Proof from the shipping carrier that the goods were delivered to the specified address. This may include a signature or electronic confirmation.
  • Shipping labels: Images or scans of the shipping label that was attached to the package, showing the destination address and other relevant details.

To effectively upload and submit shipping or delivery evidence, follow these steps:

  1. Gather the necessary documents: Collect all relevant documents related to the shipment, such as tracking numbers, shipping receipts, and delivery confirmations.
  2. Use Klarna’s dispute API: Access Klarna’s Dispute API to upload the evidence. The API allows you to attach files and submit them as part of your response to the dispute. Ensure that the documents are clearly labeled and easy to identify.
  3. Verify the information: Before submitting, double-check the evidence to ensure it is accurate, complete, and directly related to the disputed transaction. Incorrect or incomplete evidence may weaken your case.
  4. Submit the evidence: Use the API to upload and submit the evidence. Once submitted, Klarna will review the documentation as part of the dispute resolution process.
  5. Track the dispute status: After submitting the evidence, monitor the status of the dispute through Klarna’s webhooks or API updates. This will help you stay informed about any further actions required.
  6. Maintain records: Keep copies of all submitted evidence for your records. This can be useful for future disputes or internal audits.

Example

UrbanGear, an online store, receives a dispute from Chris, a customer claiming that the hiking boots he ordered were never delivered. UrbanGear gathers the shipping receipt, which includes the tracking number and delivery confirmation from the carrier, showing that the boots were delivered to Chris’s address. They use Klarna’s Dispute API to upload these documents as evidence. After reviewing the submission, Klarna resolves the dispute in UrbanGear’s favor, as the evidence clearly supports that the goods were delivered as promised.