Hosted Klarna Checkout Integration

This guide will lead you through all the steps required to accept payments with Klarna Checkout using the Hosted Payment Page. At the end you will be able to accept payments with Klarna without hosting any web component on your own pages.

You will find here the usual integration flow of the Hosted Payment Page using a Klarna Checkout order. In this flow, actors are defined as follow:

• Consumer: a physical person that wants to buy something.
• Browser: the browser that the Consumer is able to control, for example on a desktop or a mobile.
• Merchant Backend: your backend that will do the API calls to HPP, KCO, and Order Management.
• HPP: the Hosted Payment Page API
• Klarna Checkout: the Klarna Checkout API

The first step is to create a KCO Order with the Klarna Checkout API in order to be able to host it using the Hosted Payment Page API. This is where you are going to define all you know already about your Consumer, what is the content of the order, and the metadata associated with the purchase.

Create a KCO Order: Request

{
  "purchase_country": "GB",
  "purchase_currency": "GBP",
  "locale": "en-GB",
  "order_amount": 50000,
  "order_tax_amount": 4545,
  "order_lines": [
      {
          "type": "physical",
          "reference": "19-402-USA",

Create a KCO Order: Response

{
  "order_id": "8cf27b55-53e8-6aba-9fb4-7c692e56ddee",
  "status": "checkout_incomplete",
  "purchase_country": "gb",
  "purchase_currency": "GBP",
  "locale": "en-GB",
  "billing_address": {
    "country": "gb"
  },
  "customer": {},

How to create the Request

Please read the order creation guide of Klarna Checkout API to get all details on fields and how you can use them. As you will use the Hosted Payment Page API to host your KCO Order, you don’t need to read the step after.

As you won’t own and host the page that displays Klarna Checkout's Client, you have to respect additional guidelines that will depend on the use case of your integration see special rules.

How to interpret the Response

The KCO Order is created on a successful response. On the fields present in it, only the order_id is useful when KCO is used with Hosted Payment Page API. You will have to use it to build HPP’s payment_session_url.

https://api.klarna.com/checkout/v3/orders/<kco_order_id>

The second step is to create the HPP Session using the KCO Order you have just created. Sessions will have a tied lifecycle meaning that the HPP Session will expire 1 hour before the KCO Order, see session lifetimes. Multiple HPP Sessions can be linked to the same KCO Order if you need to have multiple customizations at the same time, although it is considered a bad practice.

How to create the Request

Please read the session creation call reference of HPP to get all details on fields and how you can use them. As you will use the Hosted Payment Page API to host a KCO Order, you have additional options that you can use.

Outside of typical eCommerce flow, you will need to distribute the link to the Hosted Payment Page to the Consumer, for example by email or SMS, or by QR code. The Consumer will then be able to access the page and complete the payment.

Once the Consumer has completed the flow on HPP, the status of the HPP Session will change to reflect the outcome of their actions. Your system will then need to retrieve this outcome to be able to act on it, maybe by just storing the order_id for post-purchase purposes.

The outcome of the HPP Session can be retrieved either via the redirection of the Consumer to your own website or by making an API Call to get the status of the session.

4. a. From the Consumer redirection

You can get the outcome of the KCO Order from the link that the Consumer will be redirected to as stated in our redirection guide. It is still advised to make a call to the HPP API to get the exact state of the HPP Session and not rely only on the consumer redirection.

Parameters that will be required to handle the outcome are given to you by replacing the placeholders you have set up in the merchant_urls.success at the creation of the HPP Session. You just need to extract the values from there.

Orders that are created without auto_capture will need to be captured using the Order Management API.

No payment will occur until the order has been captured. This is for use in transactions where the purchased goods are not immediately delivered but are made available at a later time.

Please read the capture guide of Order Management to get all details.

If for any reason the payment session has to be canceled (expiration of an offer, order was paid using another payment method, etc), the HPP API gives to the Merchant the possibility to disable an HPP Session. To do that, it is required to send a delete request on the HPP Session resource.

Please read the disable session call reference of HPP