Start a payment session

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 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}](https://docs.klarna.com/api/api-urls/) /payments/v1/sessions endpoint.

Sample request

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.

JSON

1 2 3 4 5 6 7 8 9 10

{
    "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": [
        {

Extra merchant data

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 API

data in the request.

Sending customer data

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

1 2 3 4 5 6 7 8 9 10

{
    "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 API

for a full list of supported request information.

The billing_address object to send billing address information

Distribution object

Parameter	Type	Required or optional	Description
`method`	string
`short_code`	string	optional, populate only when short code is available	A 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_urls`	object	optional	Include this object if you want to use a webhook instead of polling to get the distribution result.
`status_update`	string	optional	The URL to which the status updates will be sent.

Success response

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

1 2 3 4 5 6 7 8 9 10

{
    "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.

Error handling

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 code	Description	Action to take
`BAD_REQUEST`	The 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_DENIED`	API credentials are incorrect and permission is not available	Don’t retry the session and contact Klarna’s merchant support.
`UNKNOWN`	System error	Don’t retry the session and contact Klarna’s merchant support.