Klarna
Beta
Last updated: July 24, 2024
Klarna's Buy Now, Pay Later (BNPL) payment method enables customers to pay for their online purchase using any the following options:
- 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
- Pay now: customers pay the whole amount at the moment of purchase
- Financing: customers pay monthly over time with interest-bearing or interest-free payments, depending on the customer's country
- Pay Now Standalone enables merchants under the Klarna restricted categories to operate with direct bank transfers
Klarna performs risk checks on a customer before approving a payment. If the checks are successful, Klarna pays you in advance and takes on the full fraud risk for the payment.
Information
The availability of these payment options varies depending on the consumer country.
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 directly via Klarna |
Chargeback | All chargeback are handled directly via Klarna |
The Klarna payment flow is a three-step process, with one optional step:
Request a payment context.
Configure Klarna's JavaScript SDK, Display Klarna widget, Authorize the session
Optionally, verify if Klarna approved the payment context.
Request a payment.
If you used a manual capture flow, capture the payment.
To display the Klarna widget on the checkout page, you must request a payment context.
The payment context will return a session_id
and client_token
, which you'll need to provide when you configure subsequent requests.
post
https://api.checkout.com/payment-contexts
1{2"currency": "EUR",3"amount": 1000,4"payment_type" : "regular",5"source": {6"type": "klarna",7"account_holder" : {8"billing_address": {9"country": "DE"10}11}12},13"items": [14{15"name": "Battery Power Pack",16"quantity": 1,17"unit_price": 1000,18"total_amount": 1000,19"reference": "BA67A"20}21],22"processing":{23"locale": "en-GB"24},25"processing_channel_id": "{{apm_processing_channel_id}}"26}
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_id
client_token
1{2"id": "pct_jwvjl5tin54ubn7x2stvmunske",3"partner_metadata": {4"session_id": "kcs_55xomnyd3ftujckeoyuvtkx2ue",5"client_token": "eyJhbGciOiJub25lIn0.ewogICJzZXNzaW9uX2lkIiA6ICI1MGEzYTNiOS02NGE5LTYwNjMtODNmNC1hMzRlM2Q4MjRiNGIiLAogICJiYXNlX3VybCIgOiAiaHR0cHM6Ly9rbGFybmEtcGF5bWVudHMtZXUucGxheWdyb3VuZC5rbGFybmEuY29tIiwKICAiZGVzaWduIiA6ICJrbGFybmEiLAogICJsYW5ndWFnZSIgOiAiZW4iLAogICJwdXJjaGFzZV9jb3VudHJ5IiA6ICJHQiIsCiAgImFuYWx5dGljc19wcm9wZXJ0eV9pZCIgOiAiVUEtMzYwNTMxMzctMTEiLAogICJ0cmFjZV9mbG93IiA6IGZhbHNlLAogICJlbnZpcm9ubWVudCIgOiAicGxheWdyb3VuZCIsCiAgIm1lcmNoYW50X25hbWUiIDogIlBsYXlncm91bmQgRGVtbyBNZXJjaGFudCIsCiAgInNlc3Npb25fdHlwZSIgOiAiUEFZTUVOVFMiLAogICJjbGllbnRfZXZlbnRfYmFzZV91cmwiIDogImh0dHBzOi8vZXZ0LnBsYXlncm91bmQua2xhcm5hLmNvbSIKfQ."6},7"_links": {8"self": {9"href": "https://api.checkout.com/payments/pay_jwvjl5tin54ubn7x2stvmunske"10}11}12}
Note
This section should be implemented using the JS SDK first, otherwise the widget will not load. For more information on configuring Klarna, please see the Klarna documentation.
For further details, refer to the Klarna payments integration documentation.
- Include the Klarna script in your Web application.
1// Klarna SDK2<script src="https://x.klarnacdn.net/kp/lib/v1/api.js" async></script>
- Initialize the Klarna SDK with the
client_token
received in thepayment_context
response.
1window.klarnaAsyncCallback = function () {2Klarna.Payments.init({3client_token:"eyJhbGciOiJub...",4});5};
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.
1<div id="klarna-payments-container"></div>
- Load the Klarna widget in the placeholder.
1Klarna.Payments.load(2{3container: '#klarna-payments-container'4},5{},6function (res) {7console.debug(res);8}9)
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.
- When the user select Klarna as an option, open the Klarna Popup and authorize the session
Note
Klarna suggests sending the billing and shipping parameters to ensure a seamless experience for the user.
1Klarna.Payments.authorize(2{},3{4billing_address: {5given_name: "Alice",6family_name: "Test",7email: "[email protected]",8street_address: "Södra Blasieholmshamnen 2",9postal_code: "11 148",10city: "Stockholm",11phone: "+46701740615",12country: "SE",13},14shipping_address: {15given_name: "Alice",16family_name: "Test",17email: "[email protected]",18street_address: "Södra Blasieholmshamnen 2",19postal_code: "11 148",20city: "Stockholm",21phone: "+46701740615",22country: "SE",23},24customer: {25date_of_birth: "1941-03-21",26},27},28function (res) {29console.log("Authorize outcome:", res);30}31)
There are two potential cases that you need to handle based on the response:
Success response - The purchase is approved. If the response is approved,
show_form: true
, Klarna has approved the authorization for this purchase and you will receive apaymentContextApproved
webhook. Once the payment context has been approved, the approval is valid for 60 minutes.Error response - The purchase is not approved and you can't display Klarna as a payment option. If the response is
show_form: false
, your store is not able to offer Klarna as a payment option. You should hide Klarna for the customer at checkout, and your customer must select another payment method. This negative response results from the pre-assessment that Klarna executes for the purchase.
Once the customer confirms payment in the Klarna pop-up, you will receive a paymentContextApproved
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}
1{2"payment_request": {3"currency": "EUR",4"amount": 1000,5"payment_type": "regular",6"source": {7"type": "klarna",8"account_holder": {9"first_name": "Bose",10"last_name": "Gold",11"date_of_birth": "1990-10-12",12"email": "[email protected]",13"billing_address": {14"address_line1": "address_line1",15"address_line2": "address_line2",16"city": "city",17"zip": "zip",18"country": "US",19"state": "OH"20},21"phone": {22"country_code": "",23"number": ""24},25"identification": {26"number": ""27},28"company_name": "Checkout.com"29}30},31"shipping": {32"company_name": "Checkout.com",33"first_name": "Test",34"last_name": "Account",35"address": {36"address_line1": "Von-Reiche-Straße 9",37"address_line2": "6th floor",38"zip": "63930",39"city": "Furth",40"country": "DE"41},42"phone": {43"country_code": "+353",44"number": "6789010"45}46},47"items": [48{49"name": "Battery Power Pack",50"quantity": 1,51"unit_price": 1000,52"tax_rate": 0,53"total_amount": 1000,54"tax_amount": 0,55"reference": "BA67A",56"url": "https://product.url.com",57"image_url": "https://image.url.com"58}59],60"processing": {61"locale": "en-IE",62"tax_amount": 0,63"custom_payment_method_ids": [64"6m_149APR",65"6m_0APR",66"12m_149APR",67"12m_0APR",68"24m_149APR",69"24m_0APR"70]71},72"partner_metadata": {73"session_id": "kcs_55xomnyd3ftujckeoyuvtkx2ue",74"client_token": "eyJhbGciOiJub...."75},76"status": "Approved"77}78}
Information
The payment_type
field in the response will return regular
for Pay Now payments, or installment
for Pay Later payments.
"payment_type": "regular"
for Pay Now payments"payment_type": "installment"
for Pay Later payments
If the "status"
is returned as "Approved"
, it means that Klarna has approved the authorization for this purchase and you can proceed with requesting the payment.
post
https://api.checkout.com/payments
1{2"payment_context_id": "pct_xxx",3"processing_channel_id": "pc_xxx"4}
Your request was successful if you receive a 202 Success
response code with a status
field set to Pending
.
1{2"id": "pay_px7sfvkauu3ebmtdwbsm6xtleu",3"status": "Pending",4"processing": {5"partner_order_id": "13e5480e-ab56-4d94-afac-eb258d0a1f4c",6"partner_fraud_status": "ACCEPTED"7},8"_links": {9"self": {10"href": "https://api.sandbox.checkout.com/payments/pay_px7sfvkauu3ebmtdwbsm6xtleu"11}12}13}
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.
If the capture amount is equal to the authorized amount, we will consider the capture final.
When the capture amount is less than the authorized amount:
If you send a capture request with
"capture_type": Non-Final
, we won’t release the remaining authorized amount.If you send a capture request without
"capture_type"
, or with"capture_type": "Final"
, we'll release the remaining authorized amount.
For more information on capturing a payment, see the Capture a Payment page.
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.
1{2"action_id": "act_y3oqhf46pyzuxjbcn2giaqnb44",3"_links": {4"payment": {5"href": "https://api.sandbox.checkout.com/payments/pay_y3oqhf46pyzuxjbcn2giaqnb44"6}7}8}
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
1{2"amount": 1000,3"capture_type": "NonFinal"4}
Response example
If you receive a 202 Success response containing an Action ID
, your request was successful.
1{2"action_id": "act_y3oqhf46pyzuxjbcn2giaqnb44",3"_links": {4"payment": {5"href": "https://api.sandbox.checkout.com/payments/pay_y3oqhf46pyzuxjbcn2giaqnb44"6}7}8}
Use the payment_id
from the payment response to retrieve details about the payment.
get
https://api.checkout.com/payments/{id}
1{2"id": "pay_y3oqhf46pyzuxjbcn2giaqnb44",3"action_id": "act_y3oqhf46pyzuxjbcn2giaqnb44",4"amount": 1000,5"currency": "GBP",6"approved": true,7"status": "Authorized",8"response_code": "10000",9"response_summary": "Approved",10"processed_on": "2019-01-15T10:59:51Z",11"reference": "ORD-5023-4E89",12"source": {13"account_holder": {14"first_name": "Bose",15"last_name": "Gold",16"date_of_birth": "1990-10-12",17"email": "[email protected]",18"billing_address": {19"address_line1": "",20"address_line2": "",21"city": "",22"zip": "",23"country": "US",24"state": "OH"25},26"phone": {27"country_code": "",28"number": ""29},30"identification": {31"number": ""32},33"company_name": "Checkout.com"34}35},36"shipping": {37"first_name": "",38"last_name": "",39"email": "",40"address": {41"address_line1": "",42"address_line2": "",43"city": "",44"zip": "",45"country": "US",46"state": "OH"47},48"phone": {49"country_code": "",50"number": ""51}52},53"processing": {54"partner_session_id": "f813fe91-078a-4e73-8ebd-d5df35750950",55"partner_order_id": "13e5480e-ab56-4d94-afac-eb258d0a1f4c",56"partner_fraud_status": "ACCEPTED",57"locale": "en-DE",58"tax_amount": 0,59"custom_payment_method_ids": [60"6m_0APR"61]62},63"items": [64{65"name": "Battery Power Pack",66"quantity": 1,67"unit_price": 1000,68"total_amount": 1000,69"tax_rate": 0,70"tax_amount": 0,71"discount_amount": 0,72"reference": "BA67A",73"image_url": "",74"url": ""75}76]77}
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
1{2"amount": 1003}
1{2"actionId": "act_cxpffngdvouvabegyy3asiuou",3"_links": {4"payment": {5"href": "https://api.checkout.com/payments/pay_ok7yhvutuylevnatk3x3dxviq4"6}7}8}
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.
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 customer data provided by Klarna
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.
The discount information should be submitted in "items[].discount_amount":
.
The discount information should be submitted as item object "items[].type:"discount"
.
1 x jumper 50 EUR discounted 15%, tax 25%
1 x jumper = 5000
items[].tax_amount
: 25% of 4000 = 1000items[].discount_amount
: 15% of 5000 = 750items[].total_amount
: (5000 x 1) - 750 = 4250items[].total_amount
= (quantity xunit_price
) -discount_amount
3 x white t-shirt 15 EUR discounted 10%, tax 25%
3 x white t-shirt = 4500
items[].tax_amount
: 25% of 1200 = 300 x 3 = 900items[].discount_amount
: 10% of 1500 = 150 x 3 = 450items[].total_amount
: (1500 x 3) - 450 = 4050items[].total_amount
= (quantity xunit_price
) -discount_amount
10% discount on an 83 EUR order
1 x order = 8300
items[].type
: discountitems[].total_amount
: (4250 + 4050) * 0.1 = 830
Total discount
1 x jumper
items[].discount_amount
+3 x white t-shirt
items[].discount_amount
+items[].type
: discountitems[].total_amount
=processing.discount_amount
: 2030
1{2"amount": 7470,3"items":[4{5"type": "Physical",6"name": "jumper",7"quantity": 1,8"reference": "98-765-XYZ",9"total_amount": 4250,10"discount_amount": 750,11"tax_amount": 1000,12"tax_rate": 2500,13"unit_price": 500014},15{16"type": "Physical",17"name": "white t-shirt ",18"quantity": 3,19"reference": "12-345-ABC",20"total_amount": 4050,21"discount_amount": 450,22"tax_amount": 900,23"tax_rate": 2500,24"unit_price": 150025},26{27"type": "Discount",28"name": "10% discount",29"quantity": 1,30"reference": "PROMO10",31"total_amount": 83032}33],34"processing": {35"tax_amount": 190036}37}
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:
UPAPI 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. |