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:
acquiring_channel parameter set to in_store to indicate the payment will happen in a physical storedistribution object, including the distribution method set to one_qr and the URL that will receive status updatesA 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.
{
"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.
| Parameter | Type | Required or optional | Description |
|---|---|---|---|
method | string | The distribution method. Supported values are:
| |
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. |
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.distribution object, containing result_url which needs to be called to receive the QR (link to Monitor the status page){
"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, similar to e-commerce. 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. |