Klarna Docs - Initiate an in-store payment
API and SDKsSupport
Initiate an in-store payment

This guide walks you through initiating a payment and letting your customers pay with Klarna in your physical store.

If you're an existing e-commerce partner, you may already be familiar with the Klarna payments API. The request and actions described in this guide use the same API, modified for the in-store scenario.
To let your customer pay with Klarna in a physical store, start a new Klarna payments session by sending a POST request to the {apiURL}/payments/v1/sessions endpoint.

To start an in-store payment session, include the following in your request:

  • the acquiring_channel parameter set to in_store to indicate the payment will happen in a physical store
  • the distribution object, including the distribution method set to one_qr and the URL that will receive status updates

A sample request to initiate an in-store payment session.

When initiating a payment session, it is required to send EMD as part of the request similar to the sample request.

This guide describes how to send all required EMD data in the request.

In some cases, you might want to send billing address when creating a payment session in order to improve the payment experience at the point of sale, for example by pre-filling the checkout form with information that is already know and reducing the need for the customer to manually fill in all fields.

JSON
{
    "acquiring_channel": "in_store",
    "purchase_country": "SE",
    "purchase_currency": "SEK",
    "locale": "en-SE",
    "merchant_reference1": "ON4711",
    "order_amount": 18000,
    "order_tax_amount": 3000,
    "order_lines": [
        {

In this case, please include the following to send billing address. You can refer to create a session for a full list of supported request information.

  • The billing_address object to send billing address information
ParameterTypeRequired or optionalDescription
methodstringThe distribution method. Supported values are:
  • one_qr
short_codestringoptional, populate only when short code is availableA numerical code consisting of 2–20 digits that links a payment session with the customer. The code is displayed on the customer’s device when they scan a static QR code. The cashier enters the code into the device at the till. Then, the short code is included in a POST request to the Klarna payments API.
callback_urlsobjectoptionalInclude this object if you want to use a webhook instead of polling to get the distribution result.
status_updatestringoptionalThe URL to which the status updates will be sent.

In response to your request, you receive:

  • session_id, a payment session identifier.
  • payment_method_categories, an array that lists the available payment methods. This information is returned by the API, but you don’t need to take any actions related to it.
  • the distribution object, containing result_url which needs to be called to receive the QR (link to Monitor the status page)
JSON
{
    "session_id" : "{session_id}",
    "payment_method_categories": [
        {
            "identifier": "klarna",
            "name": "Pay with Klarna",
            "asset_urls": {
                "descriptive": "https://x.klarnacdn.net/payment-method/…",
                "standard": "https://x.klarnacdn.net/payment-method/…"
            }

A sample success response to initiate an in-store payment session request.

The errors listed below can occur when you initialize a payment session, learn more in Error handling guide.

You can retrieve the error from the distribution result endpoint or by subscribing to a webhook.

Error codeDescriptionAction to take
BAD_REQUESTThe shortcode should be within the limits and integers only. Otherwise any of the fields needs to be in appropriate format.Create request with an appropriate input
PERMISSION_DENIEDAPI credentials are incorrect and permission is not availableDon’t retry the session and contact Klarna’s merchant support.
UNKNOWNSystem errorDon’t retry the session and contact Klarna’s merchant support.