Klarna Docs - Klarna In-store integration made easy for Partners

Klarna In-store integration made easy for Partners

This guide will guide you through the mandatory and most effective steps to integrate Klarna as a Payment Method in your POS/ECR.

This guide will navigate you through our detailed technical documentation by highlighting the most important and commonly used functions and challenges to integrate Klarna’s In-store solution. Going through this guide step by step will ensure you have a fully future proof integration for your POS/ECR or any relevant system used in face to face payments context.

Who are you. This guide provides the necessary information for any Partner to be able to integrate Klarna Payment in their system when used in physical stores. The integration is thought to be used by multiple merchants using your System to sell goods to end customers.

What is Klarna In-store?

Klarna’s In-store solution is enabling purchases in the physical world using Klarna’s payment methods. The solution is taking advantage of the API referred to as Hosted Payment Page (HPP) to distribute a Klarna Payments (KP) session either through scanning a QR code, sending a SMS or via email.

InteractionsPOS Integration
1. Consumer asks to pay with Klarna
2. Store staff presses the Klarna button on the POS/ECRa. Initiate the transaction
3. Store staff sees the distribution UIb. Show distribution options
4. Consumers get to pay on their phonec. Wait for the result
5. Store staff and consumer see confirmationd. Update POS
6. Get receipte. Print receipt with Klarna Reference

Payment step by step guide

a. Initiate the transaction: create KP Session and HPP Session

When a consumer decides to pay with one of Klarna’s payment methods you need to first create a KP session with relevant cart information. Using the identifier that will be returned, you can create an HPP session to enable the consumer to complete the purchase on their own device.

Klarna Payments API will send you back more details, but your system is here only interested in the KP Session ID that it needs to pass to the HPP API when creating the HPP Session.

Hosted Payment Page API will send you back more details, but your system is here only interested in the URL to poll for the status and the distribution view.

Get better support. Klarna recommends sending in system/platform name and version, as well as module/integration name and version in the User-Agent in each server side call as part of the request header. In the case of issues, all Klarna teams can support you better, by identifying all affected orders.

User-Agent: {partner name}/{system name and version}/{module name and version}

b. Show distribution options: open the distribution view

After creating the HPP Session, you will get a distribution_module.standalone_url that you need to open on the POS screen. In this URL you need to replace one parameter to configure your POS screen capacities, see our default configurations here. This will allow the storestaff to send a SMS or an e-mail to the consumer, or show them a QR code so that they can finalize the purchase on their own device.

Example of integration opening the Distribution View in an iFrame

The standalone_url you got back contains two placeholders. You need to replace at least the {{profile_id} }placeholder that will adapt the store staff’s user experience. You can find here a list of default identifiers that you can use, or learn more on how you can adapt the user journey.

Profile IdConsumer FrontingHardware
a06b28ba-7c92-496e-8242-b1530898eb3fNoKeyboard as input.
fec2b8d9-3971-4786-8bae-4c4b34015fb0NoTouchscreen as input.
84493778-4304-4f32-8de1-042fe9c61d44NoKeyboard and a touchscreen as input.
1fa264b1-d6a9-438b-aa3c-fee132538cb6YesKeyboard as input.
34f03093-06cd-4eec-8ebb-8f514588abefYesTouchscreen as input.
b40e5b60-9374-4fb7-b101-e62c47248b41YesKeyboard and a touchscreen as input.

Letting this identifier be a parameter of the merchant or device configuration is a good way to be future proof. This profile affects the store staff's user experience and not the consumer one.

You can replace {{view_id}} by any identifier respecting [A-Za-z0-9\-]+, this will let you debug easier your integration, or replace it by an empty value.

In-depth documentation of how to control of the Distribution View here including how to embed it directly in your web application or native application →

Battle tested. Klarna’s Distribution View is not just an input field for entering a phone number. It adapts itself to the hardware used and merchant’s preferences, and manages everything during this crucial exchange between the store's staff and the customer. It will give a quick feedback to the store’s staff to handle the customer, and also supports security and legal requirements in all countries.

c. Wait for the transaction: poll the status

While the consumer is finalizing the purchase on their device, you can poll the current status. Once the payment is complete, you can print or share the receipt to the customer with the klarna_reference.

d. Update your system and print the receipt

Now that the purchase is confirmed on the Klarna side, you need to update your system and print the receipt with the correct information.

  1. The customer needs to be able to request a refund. Therefore, a reference needs to be printed so that your system can trackback to the Klarna order_id. A store staff should not be able to refund a Klarna payment by any other payment method (card, cash, gift card, store credit…)
  2. The customer needs to be able to give to Klarna’s customer service the klarna_reference of the payment, so that we can assist them in the best way.

Post-purchase

Refunding the customer

Refunds made from Klarna purchases should be directed to Klarna via the Order Management API. Customers should not receive refunds in other forms, cash or store credit, as Klarna will still expect the customer to settle their debts for Klarna purchases.

Refund an order→

Delayed handover of the goods (optional)

If a store is selling goods that are not handed over directly to the consumer when they complete the payment it is possible to split the payment and capture steps.

Capture an order →

  1. When creating the HPP Session at step a, use PLACE_ORDER instead of CAPTURE_ORDER
  2. When goods are given to the consumer (either by shipment, or because they pick up at the store), you need to make a capture

How to start integrating ?

Klarna has a test environment for any integrators called Playground where you can onboard yourself in a few minutes and start trying things out.

Step 1: Getting Started - Credentials

Before you can start, you will need to create your own set of credentials. Those credentials will give you access to Klarna’s Playground environment of the Merchant Portal - where you can use the same functionalities as a merchant (e.g. generate API credentials, see API calls logs and manage placed orders, etc).

  1. Fill out the form after choosing the region here.
  2. Follow the link from the email Activate your Klarna Merchant Portal account.
  3. Once on the main page of the Merchant Portal, look for the Settings app.
  4. Click on the button Generate new API credentials.
  5. Use these credentials to authenticate your requests with Basic-Auth.

Use a tool to create REST requests (like Postman for example) and go manually through step a and step b of the payment integration to send yourself a link. You’ll be able to complete a fake purchase using our test triggers.

  1. Use the tool you prefer to build your REST requests, using the credentials.
  2. Create sessions like in step a.
  3. Open the distribution_module.standalone_url in a browser like in step b.
  4. Send yourself the payment link by sms or scanning the QR code.
  5. Complete the purchase using our sample data.

Step 3: Look for your order on Merchant Portal

  1. Go to the Orders app and see the order you just completed
  2. Go to the Logs app to see your requests
  3. Go to the Branding app to adapt the Consumer’s look and feel (takes up to 4 hours to replicate)

Going to production

Step 1: Integrating Klarna

Based on the flow presented before the minimal set of features you need to support in order to get the integration verified is defined below:

ActionStep in-depth documentationAPI Endpoints
Create KP sessionPayments API
Create HPP session
Distribution View
Refunding an orderOrder Management API
Capture an orderOrder Management API

Step 2: Parametrization of your integration

When configuring Klarna as a Payment Method on your system, it is mandatory that merchant may configure the following parameters:

ParameterDefinition
EnvironmentMerchant is able to test an integration on our test environment (Playground) as well as production.
Klarna CredentialsMerchant is able to define the credentials to use (Username and Password).
Session ProfileMerchant is able to override the profile_id sent when creating the HPP Session (step a).
Distribution ProfileMerchant is able to override the profile_id used to render the Distribution View (step b).

Step 3: Test your service

Ensuring that your Klarna integration works smooothly is key - we have created a checklist for you to help you validate the most important elements in your Klarna integration. Klarna may reach out to you for additional acceptance tests if necessary.

  1. Some test triggers that will help you:
    a. Get your purchase accepted with sample data
    b. Get your purchase refused using an email address containing ...+denined@... test trigger
    c. Go through the Manual ID Check flow using test-profile-with-manual-identification as the profile_id when creating the session
  2. Download our test cases list and go through all the test cases. Validate the required one and the optional ones and make a PDF document that you can send us back.

Step 4: Validate your Integration & Go Live

  1. Send us at partner.support@klarna.com the executed test cases as well as an attached video of the storestaff experience.
  2. Before going to production with a merchant, you need to fulfil the above mentioned test sheet and send us this form.

Done !

If after reading through this document and reviewing the documentation of our products you still have technical questions you can reach out to our partners support team by e-mail to partner.support@klarna.com, with a reference toIn-store integration in the subject.