How to implement the API in the best possible way for this purpose
Klarna payment methods should be offered in your checkout process, at a step where the customer selects the payment method to use for their purchase. Since checkout flows are designed differently in many cases, there are many ways to accommodate for this. However, the focus should be on how you can make the purchase experience as smooth as possible for your customers. We have some recommendations in our Klarna Payments integration best practices guide. That guide can help you leverage our Klarna Payments product to offer your consumers any collection of available Klarna Payment method in your checkout.
Below you can see a diagram of the relationship between user interaction on your checkout and what you should map this to in your integration towards Klarna Payments.
See table for standalone payment methods here.
The following description will tell you how to implement the feature into your checkout’s flow. Detailed descriptions of every single API-call used in this implementation will be on separate, call-specific pages.
The Klarna Payments API will be used to connect to Klarna’s services to display and offer the payment method in your checkout. Offering these payment methods should be done at the payment method selection stage in your checkout.
You are still responsible for the other steps of the purchase journey for your customers, including handling of basket and order lines, shipping method selection, customer data collection and handling gift cards etc.
It is important that any data that is sent to Klarna is aligned with the data format of Klarna’s systems. Please validate that you are handling the following correctly:
Note: If you are sending in Extra Merchant Data, this should be added as an attachment before doing an authorize. This can be done already in the create session request.
When the user enters the page where Klarna’s payment methods are offered you must create a session towards Klarna. This session should be used throughout the whole purchase flow, until an order is placed.
The session defines what payment methods that will be available for a certain session, depending on the country of the purchase and the amount of the basket.
You can find all the details of how to correctly create a session towards Klarna in create_session.
After creating the session, the Klarna widget should be initialized and loaded on your checkout. It is advised to do this right after creating the session, so that the customer won’t notice any delay in loading. The widget can be hidden as long as the address details are not yet collected and the consumer has not yet triggered the display of it.
Since all checkouts are designed differently, there are many ways to do this and you should think about how you can make the purchase experience as smooth as possible for your customers. We have some recommendations in our Klarna Payments integration best practices guide.
Best Practice: As we do a pre-assessment of the purchase already at load, you should listen to the response of the load-call and act accordingly to offer your customers a great purchase experience!
In-depth descriptions of how to use the JS library to display the Klarna widget is presented in Initalize and Load call pages seen here .
For placing an order for session, there are two actions that must be taken. Initially, a risk and fraud assessment must be done on the purchase and user. This is achieved by using the authorize call in the client, which is described in-depth here .
Please be aware that any customer info that has not been shared before this point in time, must be done here to enable risk and fraud assessment.
Best practice: Please ensure you handle the possible responses from Klarna, so the purchase experience becomes great! Some recommendations are described in the order not approved-section here.
If the authorization is successful, you will receive an
authorization_token in the response from the authorization towards Klarna. This
authorization_token should be used to place the order towards Klarna. This is done via a server-side call to Klarna Payments API. This is explained in detail in the page on Place order.
Note: To ensure that session handling is aligned between you as a merchant and Klarna, we are validating that data shared at Place Order is aligned with any data shared in any previous calls (from
create_session, to load or authorize).
In case the cart has been updated, or the consumer has updated their details, you will need to propagate this information to Klarna. This needs to be done so that we can update our risk or fraud decisions based on the correct information, or simply display the widget in a correct way to the consumer.
Please note that some payment methods are only offered within certain amount thresholds. Updating the amount can therefore change the available payment methods in a session.
In case the cart or consumer updates are done before an authorization call has been made, there are two ways of propagating changes to Klarna. The first alternative is to update session server-side and the second is to do a client-side load with new details.
There is no difference between the two alternatives in how the updates are treated. However the effects of the update is only shown to the consumer in the Klarna widget if a load is done, so if you do a server side update you should also do a client-side load.
Note:If you try to place an order with changed details or the order without doing a new
In case the cart or consumer updates are done after an authorization call has been made, there are also two ways of propagating changes to Klarna. If the Klarna widget is still displayed to the consumer on the page, you can do a new authorization call with updated details, which will trigger a new risk and fraud assessment.
Making a new authorization will result in a new authorization_token being shared with you as a merchant. Make sure that the new token is being used when placing an order.
If you have a multi-step checkout and your checkout offers the customer to change any details of the order after the payment step (e.g. an order review page) you will need to reauthorize if the customer changes anything.
On such an order review page there is typically no Klarna widget and hence the standard way of authorizing (init + load+ authorize) is not possible. A reauthorize is possible to handle this situation and any necessary customer communication will be handled in fullscreen modals.
Best Practice: It is recommended that you will display triggered modals as these might include items that require user input to complete the purchase.
In case the customer drops out of the checkout or you become aware of that the consumer won’t complete a purchase, you can release the authorization. This will make sure that any reservations for the consumer is released, e.g. in the case of a card purchase. Be aware that releasing an authorization and then attempting to do a new one might impact our credit assessment of that consumer.
authorization_token is valid for 60 minutes. We can only guarantee that a token will work for placing orders within this timeframe.
You can find detailed descriptions of this call in the release authorization page.
You will now need to handle orders that have been created. Look into Order Management or use the Merchant Portal for this.
In respect of Klarna’s checkout solutions (Shopping Solutions) for which Klarna has partnered with third party operators of payment networks (Third Party Payment Option Providers), a customer using the Shopping Solutions may choose to use its regular debit or credit card to (i) pay directly in the checkout, or (ii) settle the debt to Klarna at a later stage. You, who operate the webstore, agree to and authorizes such Third Party Payment Option Providers to store, use, share and release cardholder data, provided or generated pursuant to this your cooperation agreement with Klarna to any person (i) for the purpose of processing the transaction; (ii) as required by applicable rules of Third Party Payment Option Providers or by applicable law; (iii) in aggregated (anonymous and generalised) format to facilitate analysis and comparisons; (iv) to investigate, prevent and/or detect fraud or crime; or (v) to mitigate information security risk, sector risk or credit risk. Klarna undertakes at all times to be Payment Card Industry Data Security Standard (PCI DSS) validated. You, who operate the webstore, undertake at all times to be compliant with the rules of PCI DSS applicable from time to time. As long as you use the Shopping Solutions in a compliant way, Klarna will be responsible for the security of cardholder data that Klarna possesses or otherwise stores, processes, or transmits when providing the Shopping Solutions.