General Notes
Payment Type | Countries | Currency |
|---|---|---|
Invoice |
|
|
Installments | ||
Direct Debit |
B2B transactions are currently only supported in Finland, Germany, Norway and Sweden.
API-Requests - Special Notes / Deviations
Overview of Deviations
- Klarna requires more specific customer data - depending on country of customer
- Status "PENDING" has to be processed
- for API-response "PENDING" implementation of API-version 3.11 or higher is required
- for TransactionStatus "pending" implementation of notify-version 7.6 or higher is required
- Request "capture" has to use parameter "capturemode"
- Request "debit" has to use parameter "settleaccount"
- add_paydata and workorderid have to be used for update of shopping cart
Clearingtype / Clearingsubtype
clearingtype | financingtype | |
|---|---|---|
| fnc | KIS | Klarna "Slice It" (Installments) |
| fnc | KIV | Klarna "Pay Later" (Invoice) |
| fnc | KDD | Klarna "direct_debit" (Direct Debit) |
| fnc | KBT | Klarna "Pay Now" (Direct Bank Transfer) |
Summary
Enabling your customers to pay via Klarna requires you to integrate the Klarna payment method into your checkout process. In order to get an overview of the relationship and interaction on your checkout please see the following diagram. (This diagram is adopted from the official Klarna documentation: Klarna Docs - Offering Klarna payment methods to your customers)
Establishing Klarna Checkout is a 3 step process.
Create a New Session
The first step is to setup a new checkout session by sending a genericpayment-request to our server API as listed below. This step is a pre-condition for loading the Klarna widget.
Please make sure to send the customer data within this request as it is needed to initiate a new session. A session will remain valid for 48 hours after the last update.
→ Genericpayment start_session
Optional - Update the Session
If the customer leaves the checkout page and returns at a later point in time, you can update the created session and change for example the address data.
Handle Token
Part of the response is a client token. This token needs to be passed to the Klarna Widget. This Widget sends the client token together with the selected payment method (e.g. "Klarna Pay Later") to Klarna to get a authorization token.
Finalize the Checkout ((Pre-)Authorization)
In the last step, you need to send the authorization token received by Klarna widget as part of the (pre-)authorization request to our server api.
→ Preauthorization/Authorization
The response contains a redirect-URL. You need to redirect the customer to this url, so that Klarna is able to securely handle data and optimize purchase flow. The customer doesn't need to take any action and will not notice this step in the background.
Klarna Checkout Processing Sequence
General Integration Information
There are a few things you need to take care of, when integrating Klarna checkout in your shop.
- You need to ensure, that the customer only triggers the session start by deliberately choosing Klarna as a payment method. As personal data will be sent to Klarna, the customer has to actively confirm this (for example: "By selecting this payment method we will send personal data to Klarna. Please confirm.").
- After confirmation of the payment method, you want to start with the first calls to server API as described above and then display the Klarna Widget. This Klarna Widget needs defined parameters to only display the chosen payment method, even if the widget is capable of displaying more than one Klarna payment method. For example after selecting "Klarna Pay Later", the widget should look something like this:
Overview Client-Side Implementation
Display Klarna Widget
The following integration steps are taken from Klarna documentation ( https://developers.klarna.com/documentation/klarna-payments/integration-guide/present-klarna-widget )
After creating a new session, you want to present the Klarna widget to your customer. This widget allows you to present all 3 payment methods offered by Klarna to the customer or define what payment method should be presented to the customer. The Klarna widget is rendered using JavaScript SDK.
Add SDK to your page (insert in body)
<script>
window.klarnaAsyncCallback = function () {
// This is where you start calling Klarna's JS SDK functions
//
// Klarna.Payments.init({....})
};
</script>
<script src="https://x.klarnacdn.net/kp/lib/v1/api.js" async></script>
Initialize SDK and place a container on your page. Please note that the Klarna widget requires a minimum width of 280px.
Klarna.Payments.init({
client_token: 'eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJmb28iOiJiYXIifQ.dtxWM6MIcgoeMgH87tGvsNDY6cH'
})
<div id="klarna_container"></div>
Load Klarna Widget
When loading the Klarna widget, one needs to peovide the container ID established in the previous step and specify the payment_method_category. The payment_method_category specifies which of Klarna´s customer offerings (e.g. Pay now, Pay later, or Slice it) will be shown in the widget.
Klarna.Payments.load({
container: '#klarna-payments-container',
payment_method_category: 'pay_later'
}, function (res) {
console.debug(res);
})
Receive Response from load call
Klarna’s widget uses the show_form:true/false field as a response flag to load and to authorize calls in the Javascript SDK. In addition the object "error" can be retrieved to receive further information about potential problems. The response information enables you to display to your customer Klarna as a payment method only when it can actually be utilised by your customer. In summary, there are three situations deriving from the "Receive Response" call.
Positive Response
If show_form: true, and there are no errors in the object returned, Klarna renders the payment options available to the customer in the widget.
{
show_form: true
}
Adjust and Try Again
If show_form: true, but an error is returned as well, then something is wrong and the consumer needs to take action before moving forward. Klarna will inform the consumer about the details of the error in the widget. Optionally, you can interpret the invalid fields in the error message and take appropriate actions on your checkout page. See the JavaScript SDK reference page for further information.
{
show_form: true,
error: {
invalid_fields: [
billing_address.street_address
billing_address.city
billing_address.given_name
billing_address.postal_code
billing_address.family_name
billing_address.email ]
}
}
Negative Response
If show_form: false, the payment method chosen by the customer will not be offered for this order based on Klarna’s evaluation. A message is displayed to the consumer in the Widget.
When Klarna returns a show_form: false, your store cannot offer the selected payment method to this customer. You need to present other payment methods to the customer and hide the option of Klarna payment.
{
show_form: false
}
Klarna Authorize
Authorise the Purchase
Once the customer has successfully selected Klarna as payment method in the checkout, the purchase can be authorised by using the Klarna JavaScript SDK. In this step all necessary customer details are transmitted to Klarna for taking a decision about whether or not to offer credit for the purchase. As a result of the authorisation you will receive a token enabling you to place an order towards Klarna. A successful authoirsation guarantees that the order can be generated within 60 minutes.
Sending the Request
The Authorisation is initiated by a client-side call which will provide you with a token for the order once successfully completed.
Here is an example request for an authorisation call. In the call one must provide the billing and optionally the shipping address.
KKlarna.Payments.authorize({
payment_method_category: "pay_later"
}, {
purchase_country: "GB",
purchase_currency: "GBP",
locale: "en-GB",
billing_address: {
given_name: "John",
family_name: "Doe",
email: "john@doe.com",
title: "Mr",
street_address: "13 New Burlington St",
street_address2: "Apt 214",
postal_code: "W13 3BG",
city: "London",
region: "",
phone: "01895808221",
country: "GB"
},
shipping_address: {
given_name: "John",
family_name: "Doe",
email: "john@doe.com",
title: "Mr",
street_address: "13 New Burlington St",
street_address2: "Apt 214",
postal_code: "W13 3BG",
city: "London",
phone: "01895808221",
country: "GB"
},
order_amount: 10,
order_tax_amount: 0,
order_lines: [{
type: "physical",
reference: "19-402",
name: "Battery Power Pack",
quantity: 1,
unit_price: 10,
tax_rate: 0,
total_amount: 10,
total_discount_amount: 0,
total_tax_amount: 0,
product_url: "https://www.estore.com/products/f2a8d7e34",
image_url: "https://www.exampleobjects.com/logo.png"
}],
customer: {
date_of_birth: "1970-01-01",
},
}, function(res) {
console.debug(res);
})
According to Klarna documentation (Klarna Docs - Authorize the purchase):
User interaction during the authorize call
When authorizing the order, Klarna conducts a full risk assessment. Therefore, from the point where you call authorize until you receive the callback you must:
- Avoid sending another authorize call (e.g. disable the buy button from being clicked again)
- Show to the consumer that the order is being processed (e.g. by showing a loading spinner)
- Prevent consumer from changing order or billing details (e.g. lock the input fields on your page)
The callback is typically received within seconds, but may take up to a minute or so in case a consumer sign-up is required when the user interacts with the widget.
Process callback from authorise call
Once the wigdet has processes the autorisation a callback is performed providing an object with one of the following parameter:
- approved (true/false) - the authorization result, approved or denied
- show_form (true/false) - whether the Klarna Widget should be displayed or hidden
- authorization_token - a token which allows you to place the order via a server side call, only returned if the authorization was approved
- error - contains details of potential error messages
Order approved
If approved carries the value "true", Klarna has approved the authorisation of credit for this order. With the authorisation_token the order can be completed using a server side pace order call. The token is valid for 60 minutes during which the authorisation is guaranteed.
{
authorization_token: "b4bd3423-24e3",
approved: true,
show_form: true
}
Order not approved
If approved: false, Klarna cannot approve the purchase. There are now two options:
Option 1 - Fixable error
In the case of an adjustable error, you will receive show_form: true and a specification about what fields that are invalid, e.g. error: { invalid_fields: ["billing_address.email"] } }. The widget will also display an error message to the consumer, asking them to correct it before you re-authorize the order. This error message will also clarify which specific field that is incorrect.
{
approved: false,
show_form: true,
error: {
invalid_fields: [
billing_address.street_address
billing_address.city
billing_address.given_name
billing_address.postal_code
billing_address.family_name
billing_address.email ]
}
}
Option 2 - Order declined
If show_form: false, the order is declined and the Klanra widget should be hidden requesting the customer to select a different method of payment.
{
approved: false,
show_form: false
}
Finalize the authorisaton
According to Klarna documentation (Klarna Docs - Authorize the purchase) the following steps on client side are optional.
Finalising an authorisation only applies to your integration if you offer payment methods where funds are drawn from the consumers directly, such as bank transfer or Sofort, in a multi-step checkout. If you integrate a multi-step checkout, you may call authorize() with the auto_finalize: false property set in order to indicate that there is a finalization step. In this case the response may differ.
In a multi-step checkout scenario the authorize() call can be triggered when the consumer selects the payment method and then presses the “continue” button to go to the next step of the checkout. With Pay Now as payment method category however transferring the funds should only happen once the consumer has pressed the “buy” button to finalize the purchase.
To cater for such a scenario authorize() can still be called when the consumer has selected the payment method, but with the auto_finalize property set to false. authorize() example:
Klarna.Payments.authorize(
{ payment_method_category: ‘pay_now’, auto_finalize: false},
{},
function(res) {
// proceed to next checkout page. The finalize_required property in the response indicates
// if finalize is needed or not.
//
// res = {
// show_form: true,
// approved: false,
// finalize_required: true
// }
})
Now when the consumer reached the last page in the checkout and can finalize the purchase finalize() is called. This will then trigger the transfer of funds and return the authorization token in the finalize callback. The flow is transparent to all payment method categories. That means if finalization was not needed in the authorize() call (e.g. for pay later) finalize()can be still be called and will return the authorization_token so that the implementation remains the same for all payment method categories. finalize() example:
Klarna.Payments.finalize(
{payment_method_category: ‘pay_now’},
{},
function(res) {
// res = {
// show_form: true,
// approved: true,
// authorization_token: ...
// }
})
Overview Server-Side API Calls
Genericpayment start_session
The first step is to setup a new checkout session by sending a genericpayment-request to our server API as listed below. This step is a pre-condition for loading the Klarna widget.
Please make sure to send the customer data within this request as it is needed to initiate a new session. A session will remain valid for 48 hours after the last update.
Only submit a buyer's personal information within this request if you ensure the buyer has actively chosen Klarna as a payment method - due to GDPR.
Genericpayment update_session
In order to update the session, e.g. the customer has added a new item tothe cart, you need to send a genericpayment-request with action=update. The call needs to provide the new list of items representing the complete shopping cart.
- An update is only possible as long as the preauthorization is not captured completely.
- Do not send the difference/changes, instead you need to send the complete new item list
- The amount cannot be higher than the amount of the preauthorization. A lower amount is allowed.
Genericpayment cancel_authorization
To update an order, you need to send a genericpayment-request with action=update. The call needs to provide the new list of items representing the complete shopping cart.
- An update is only possible as long as the preauthorization is not captured compeletly.
- Don’t send the difference/changes, instead you need to send the complete new item list
- The amount can’t be higher as the amount of the preauthorization. A lower amount is allowed.
Preauthorization / Authorization
Capture
In the capturing step either the full amount or a partial amount can be captured. It is also possible to split the capturing in two steps, capturing an initial amount and subsequently capturing the remaining outstanding amount. Please note that the amount in the capture request must be equal or less than the remaining authorised amount.
In the capture call one can provide the order lines thar are part of the shipment. By using the exact same order line name and reference as in the order, you will improve the customer's experience in the Klarna App.
Debit
Refund
For refunding / crediting the amount to the customer a Refund request can be triggered.
The refunded amount must not be higher than the captured amount. The refunded amount can be accompanied by a descriptive text and order lines. By using the exact same order line name and reference as in the capture, one will improve the customer's experience in the Klarna App as well the payment instructions sent to the customer.
Voucher Handling
If you're using vouchers in your checkout, and want to partial refund items, you do have 2 options to do this:
- send a debit-request with the items using the original amount without any discounts and send a additional item as voucher, with an amount that sums up all discounts
- example cart with auth
- item 1; red car; 20 €
- item 2; green truck; 30 €
- item 3; voucher -10€ (-5€ discount on both items)
- example cart with debit/refund
- item 1; red car; 20 €
- item 2; voucher -5€ (15€ for one item will be returned)
- example cart with auth
- send a debit-request with the items using an reduced amount, so that the whole discount is broken down on every item.
- example cart with auth
- item 1; red car; 20 €
- item 2; green truck; 30 €
- item 3; voucher -10€ (-5€ discount on both items)
- example cart with debit/refund
- item 1; red car; 15 € (15€ for one item will be returned)
- example cart with auth