Klarna
Beta
Last updated: November 20, 2024
Klarna is a popular online payment method that provides flexible payment options for your customers, enabling them to pay now, pay later, or pay over a period of time.
You can integrate with Klarna to accept any of the following payment solutions:
- Klarna Payment - enables your customers to select their preferred Klarna payment option at checkout:
- Pay now - customers pay the whole amount at the moment of purchase
- Pay later - customers pay 30 days after the goods have been delivered
- Pay over time - customers pay in three or four installments over a period of time
- Financing - customers pay monthly in interest-bearing or interest-free payments, depending on their country
- Klarna Debit Risk - enables merchants in Klarna's restricted categories to operate with direct bank transfers
Klarna performs risk checks on the customer before approving a payment. If the checks are successful, Klarna settles you in advance and takes on the full fraud risk for the payment.
The availability of these payment options varies depending on the customer's country. See the payments options by country for more information.
Information
To enable Klarna payments on your account, contact your Account Manager or [email protected].
Model | Gateway/collecting |
|---|---|
Payment flow | Direct |
Auto capture | |
Manual capture | Full and Partial capture |
Refund | Full and Partial refund |
Void | |
Disputes | All disputes are handled via Klarna's Merchant Portal |
Chargeback | All chargeback are handled directly via Klarna |
Information
Klarna is also available through Flow. Flow enables you to accept payments on your website using Checkout.com's global network of payment methods with a single integration.
The Klarna payment flow is as follows:
- Request a payment context.
- Configure Klarna's JavaScript SDK.
- Authorize the session.
- Optionally, you can verify if Klarna approved the payment context.
- Request a payment.
- If you used a manual capture flow, you must also capture the payment.
To display the Klarna widget on the checkout page, you must request a Checkout.com payment context. The payment context will return a session_id and client_token, which you'll need to provide in later requests.
Information
The Payment Contexts API supports idempotency. You can safely retry API requests without the risk of duplicate requests.
post
https://api.checkout.com/payment-contexts
You must provide the items[] array when you request a Klarna payment context.
If you use Klarna Debit Risk, the value of items[].reference is the reference shown to your customer in the Klarna application when confirming the payment.
For the full API specification, see the API reference.
If you receive a 201 Created response code, your request was successful.
A successful request will contain the following fields in the response's partner_metadata object:
session_idclient_token
The Klarna JavaScript SDK enables you to display the Klarna widget in your site:
- Add the Klarna script to your web application.
- Initialize the Klarna SDK with the
client_tokenreceived in thepayment_contextresponse.
Note
client_token relies on the Klarna session created with the payment context request. The payment context request expires after 48 hours, so purchases might fail after 48 hours have elapsed.
- Place a container on your page to render Klarna as a payment option.
- Load the Klarna widget in the placeholder.
Information
For a better user experience, call load() when you load your checkout page. This ensures that the container for Klarna payments loads immediately in a hidden container, and is ready to display when needed.
For more information, see Klarna Docs:
When the customer selects to pay with Klarna, open the Klarna pop-up and authorize the session. To provide a seamless checkout experience, ensure you send the billing and shipping parameters:
There are two potential cases that you need to handle based on the response:
- Success response
show_form: true- Klarna performed a pre-assessment and authorized this purchase. You will receive apayment_context_approvedwebhook. Once the payment context is approved, the approval is valid for 60 minutes. - Error response
show_form: false- Klarna performed a pre-assessment and didn't authorize this purchase. You can't offer Klarna as a payment option and should hide it for the customer at checkout. The customer must select another payment method.
Once the customer confirms payment in the Klarna pop-up, you will receive a payment_context_approved webhook.
Optionally, you can verify if Klarna approved the payment context by calling the GET payment context endpoint to verify its status:
get
https://api.checkout.com/payment-contexts/{id}
If status is returned as Approved, Klarna has authorized this purchase and you can request the payment.
post
https://api.checkout.com/payments
Your request was successful if you receive a 202 Success response code with a status field set to Pending.
The payment_type field in the response can return any of the following values, depending on the selected payment option:
"payment_type": "Regular"for Pay Now payments"payment_type": "PayLater"for Pay Later payments"payment_type": "Installment"for Pay over time and Financing payments- When
payment_typeis set toInstallment, you will also receive apayment_plan.financingfield. If this field is:true- the transaction is a Financing paymentfalse- the transaction is a Pay over time payment
- When
The manual capture flow enables you to authorize a payment and then capture the payment later.
Authorizing a payment places a hold on the customer’s funds and gives you some time before finalizing the transaction. For example, if you need to verify that the item is in stock.
Note
Manual capture should be triggered when you ship the items. Checkout.com's solution can perform full captures, or multiple partial captures for a payment.
Checkout.com can perform one full or multiple partial captures.
If the capture amount is equal to the authorized amount, we will consider the capture full and final.
If the capture amount is less than the authorized amount and your capture request:
- includes
"capture_type": "Non-Final"- we don’t release the remaining authorized amount - doesn't include
"capture_type", or includes"capture_type": "Final"- we release the remaining authorized amount
- includes
For more information on capturing payments, see Capture a Payment.
If you want to use full capture, pass the payment_id in the request.
post
https://api.checkout.com//payments/{id}/captures
Response example
If you receive a 202 Success response, your request was successful.
If you want to perform multiple partial captures, pass "capture_type": "NonFinal" in the capture request.
You can also use "capture_type" : Final.
post
https://api.checkout.com/payments/{id}/captures
Request example
Response example
If you receive a 202 Success response containing an Action ID, your request was successful.
Use the payment_id from the payment response to retrieve details about the payment.
get
https://api.checkout.com/payments/{id}
Klarna supports both partial and full refunds.
You can process a full refund using the Dashboard or by using the Refund API.
Information
For a better customer experience, submit the item information of the item being refunded in the partial refund request. This is only possible when using the Refund API.
post
https://api.checkout.com/payments/{id}/refunds
Once a payment is created using the auto-capture payment flow, it cannot be voided by the merchant. If you wish to reverse a payment in progress, please wait for the payment_captured webhook, and then process a refund. The webhooks you may receive are outlined in more detail below.
A payment can be fully voided after it is authorized but not yet captured.
For more information, see the Void a payment page.
During your onboarding process when integrating with Klarna, Checkout.com registers your email to access Klarna's Merchant Portal.
You can use Klarna's portal to manage on-site messaging and disputes.
On-site messaging is a solution that enables you to add tailored messaging to your business website or mobile app. Use messaging to let your customers know about the available payment options as they browse your online store. To learn more about the benefits, see the On-site messaging article in Klarna's documentation.
You can set up On-site messaging for your store or app using Klarna's portal:
- Log in to Klarna's Merchant Portal and go to On-Site messaging.
- Confirm your website.
- Read and approve the Terms and Conditions.
- Add the script to communicate with Klarna. This script is generic and is located at the top of the page.
- Add the script for the messaging placement. This script enables Klarna to render the message for the customer.
- You must provide the purchase amount information so that Klarna can display dynamic pricing and payment type information based on the basket size.
- If you have items with varying prices, you might need to add another line of code to update the messaging placement on demand.
- Copy the code snippet generated under Installation and add it to your site or app.
For Klarna, disputes are any case where customers challenge their liability to pay you. When a customer contacts Klarna to open a dispute, they are asked to contact you to resolve the issue before Klarna can act as an intermediary.
Klarna categorizes disputes into different dispute reasons:
- Returns – A customer returns all or part of their order.
For more information, see Klarna's return instructions documentation. - Goods not received – A customer did not receive all or parts of their order.
- Faulty goods – A customer received a broken item, or parts are missing or deviate significantly from the description.
For information about what qualifies as significant deviation, See Klarna's merchant protection program documentation. - Incorrect invoice – A customer claims to have received an invoice that is incorrect. For example, missing discounts or incorrect items on the invoice.
- Unauthorized purchases – A customer claims they did not make the purchase.
Klarna does not consider high-risk orders to be disputes. Disputes are raised by customers, whereas high-risk orders are flagged by Klarna's internal alarm systems designed to protect you from potential fraudulent activities.
For more information, see Klarna's dispute processing flow documentation.
You can manage and resolve disputes directly in Klarna's portal.
After a customer raises a dispute, you have 21 days to resolve the issue directly with them. After this period, if no solution is found, Klarna starts an investigation.
To manage your open disputes, log in to Klarna's portal and go to the Disputes app.
The Disputes app in Klarna's portal has six sections:
Open Disputes
This section displays all disputes that require your input to resolve. All open disputes are organized by deadline, where the dispute with the nearest deadline appears at the top of the list.
The Open Disputes page has two tabs:
- Response required – This tab show disputes that are waiting for your response. Select Respond to open the Dispute details page, where you submit your response to defend the dispute.
- Under review – This tab shows the disputes to which you've already responded. These cases are ready to be picked up by Klarna's Dispute Resolution Team.
Unauthorized purchases
This page shows disputes in the unauthorized purchases category, which the customer has raised or flagged as potential fraud.
Therefore, these disputes are more sensitive and have a shorter deadline (7 days / 168 hours) than other disputes, such as returns (14 days / 336 Hours).
High-risk order
You can use this section to find cases that Klarna's monitoring systems identified as high risk, but not a dispute.
Note
High-risk orders are time sensitive, and we recommend that you actively monitor this page and cancel these orders before shipping products.
All disputes
You can use this section to review all disputes raised with Klarna, such as:
- Disputes raised with Klarna but not yet classified as cases that need Klarna's Dispute Resolution Team to be resolved
- Disputes where Klarna's Dispute Resolution Team intervened and requested further information from you to resolve the case
- Disputes where you provided input that are now under review
- Disputes that have been resolved
Email & Dispute Settings
This page consists of two sections:
- Email & Notification
- Chargeback Threshold
Administrators can add or modify contact emails in this section and select the preferred language for dispute notifications. The local language refers to the language used in the market where the order was placed.
Statistics
In this section, you can review your customers' dispute behavior and your own performance, and visualize the costs incurred.
For more information, see Klarna's Disputes app in Merchant Portal documentation.
Learn how to manage webhooks using our API, or the Dashboard.
When integrating Klarna, you can configure the following webhooks:
| Webhook | Description |
|---|---|
| Sent when a payment request has been successfully initiated. |
| Sent when payment is approved by the partner. |
| Sent when payment is approved by the customer. |
| Sent when a payment request has been rejected. |
| Sent when the payment has been successfully captured. |
| Sent when a capture request has been rejected. |
| Sent when a payment reaches its expiry date. |
| Sent when the payment has been (fully or partially) refunded. |
| Sent when a refund has been unsuccessful. |
| Sent when payment is voided after authorization. Sent when payment is voided after partial capture, releasing the remaining amount. Sent when payment is expired. |
| Sent when void request is unsuccessful. |
To test your Klarna integration:
- Contact your Account Manager or [email protected] to activate Klarna payments in your Checkout.com test environment.
- Create a Klarna transaction by following the Klarna Payment flow and using:
- either an auto-capture or manual capture payment flow
- any of the sample data provided by Klarna:
- To test Klarna Payment transactions, use Klarna's sample customer data.
- To test Klarna Debit Risk, use Klarna's test environment data.
Information
Manual-capture payment flows are only available for Pay later, Pay over time, Pay now, and Financing.
- Using the Klarna JS SDK, embed the JWT token to render the UI components, and carry out the payment via the pop-up window.
- Complete the payment.
If successful, you will then be redirected to your predefined success URL.
Contact your Account Manager or [email protected] to move your integration to a live environment.
| Customer Country | Payment options |
|---|---|
Australia |
|
Austria |
|
Belgium |
|
Canada |
|
Czech Republic |
|
Denmark |
|
Finland |
|
France |
|
Germany |
|
Greece |
|
Ireland |
|
Italy |
|
Mexico |
|
Netherlands |
|
New Zealand |
|
Norway |
|
Poland |
|
Portugal |
|
Romania |
|
Spain |
|
Sweden |
|
Switzerland |
|
United Kingdom |
|
United States |
|
Optional features include:
Promo codes
Discounts
Delivery tracking
Klarna offers support for a preconfigured processing.custom\_payment\_method\_ids[] array to be passed into the payment context request. In product terms, this field is referred to as Promo Codes. The values passed enable the merchant to offer their customers more appealing financing options.
The values are included as a part of the session and order creation. Example values include "6m_0APR", "12m_0APR", "24m_0APR". To better understand the values, they can be split at the "_" to reveal what discount is being offered to the merchants.
The first segment is the installment months and the trailing is the annual percentage rate of charge as a percentage. For example, when "6m_0APR" is passed, the promotion being offered is for 6-month installments at an interest rate of 0%.
To configure the promo codes, there needs to be an agreement between you and Klarna as to the values for each payment option. Klarna will configure these within backend systems such that once you submit these within the API request the appropriate options are displayed in the purchase flow.
You can provide tax information for each item using the following fields:
items[].tax_rateitems[].tax_amount
You can provide either one of these fields and then Checkout.com calculates the other:
tax_amount= (tax_rate*total_amount) / (100 +tax_rate)tax_rate= (100 *tax amount) / (total_amount-tax amount)
You can apply a discount to an individual item or to all items in the transaction:
- For an individual item, provide the discount amount in the item's
items[].discount_amountfield. - For all items, provide:
- A new item object with type
discount("items[].type:"discount") - The discount amount in
"items[].total_amount"
- A new item object with type
You can apply both discounts to the same transaction.
The following example shows two individual items with individual discounts applied, and an additional discount to the entire transaction:
1 x jumper 50 EUR discounted 15%, tax 25%
items[0].quantity: 1items[0].unit_price: 5000items[0].discount_amount: 15% of 5000 = 750items[0].total_amount: (5000 * 1) - 750 = 4250- (
unit_pricex quantity) -discount_amount
- (
items[0].tax_rate: 2500items[0].tax_amount: (25 * 4250) / (100 + 25) = 850- (tax rate *
total_amount) / (100 + tax rate)
- (tax rate *
3 x white t-shirt 15 EUR discounted 10%, tax 25%
item.[1].quantity: 3item.[1].unit_price: 1500items[1].discount_amount: 15% of 1500 = 450items[1].total_amount: (1500 * 3) - 450 = 4050- (
unit_pricex quantity) -discount_amount
- (
items[1].tax_rate: 2500items[1].tax_amount: (25 * 4050) / (100 + 25) = 810- (tax rate *
total_amount) / (100 + tax rate)
- (tax rate *
10% discount on an 83 EUR order
- 1 x order = 8300
items[2].type: discountitems[2].total_amount: (4250 + 4050) * 0.1 = 830- (
items[0].total_amount+items[1].total_amount) x discount rate
- (
Note
This feature is available only with the manual capture flow.
When your customers want to see the delivery status of the goods they paid for with Klarna, they can use the Klarna app to track the delivery.
The Klarna app offers a smooth and intuitive way for your customers to track the entire shipping lifecycle and get notifications throughout the different stages. For example, when the goods are in transit or ready to pick up.
Some benefits of enabling delivery tracking are:
- offering a smooth post-purchase experience to your customers
- increasing customer satisfaction and loyalty
- increasing the successful delivery rate
- reducing customer service workload
The following information needs to be included in the capture request:
| API field | Description |
|---|---|
| Shipping information for this capture. Maximum 500 items. |
| Name of the shipping company (as specific as possible). Maximum 100 characters. Example: 'DHL US' and not only 'DHL'. |
| Shipping method. Allowed values matches - "PickUpStore", "Home", "BoxReg", "BoxUnreg", "PickUpPoint", "Own", "Postal", "DHLPackstation", "Digital", "Undefined", "PickUpWarehouse", "ClickCollect". |
| Tracking number for the shipment. Maximum 100 characters. |
| URI where the customer can track their shipment. Maximum 1024 characters. |
| Name of the shipping company for the return shipment (as specific as possible). Maximum 100 characters. Example: "DHL US" and not only "DHL". |
| Tracking number for the return shipment. Maximum 100 characters. |
| URL where the customer can track the return shipment. Maximum 1024 characters. |