Klarna Checkout

Zuletzt bearbeitet am: 08.12.2022

Requirements

Klarna merchant account

Before you can set up and use Klarna in Shopware, you need to open a merchant account at Klarna. A separate account in Klarna Playground is required to perform test orders. Our merchant support will be happy to assist you in activating payment methods and countries.

Technical requirements

In order to install the Klarna plugin, you need a running environment of Shopware 5. For installation instructions, please see Getting Started with Shopware 5.

  • Shopware (Version >= 5.6)
  • PHP (Version >= 7.2 and <= 8.1)
  • SSL encryption

Klarna's systems must be able to access your store to send payment updates. Pay particular attention to this if you have a password query (htpasswd) switched in front of your page.

To avoid rounding errors, the PHP extension bcmath should be installed and activated on the server.

Installation and configuration

Installation via plugin manager

Install and activate the plugin via the Plugin Manager in the Shopware 5 backend.

Plugin configuration

After the successfully completed installation and activation of the plugin, you can edit the plugin settings via Settings -> Plugin Manager -> Installed -> Klarna Payments -> Open. The following configurations are available there

Name Description
Test or Live Mode In test mode only test orders are created, no payments take place. Make sure you use live mode and use your live credentials as soon as you want to use Klarna productively in your store and real orders are placed.
Live Merchant ID The Klarna API Key provided by Klarna. You can retrieve it at https://eu.portal.klarna.com/.
Live Merchant Password The Klarna API password provided by Klarna. You can retrieve it at https://eu.portal.klarna.com/.
Test Merchant ID The Klarna API Key provided by Klarna. You can retrieve it at https://playground.eu.portal.klarna.com/developer-sign-up.
Test Merchant Password The Klarna API password provided by Klarna. You can retrieve it at https://playground.eu.portal.klarna.com/developer-sign-up.
Plugin responds to order status Should the automatic Klarna actions "Full capture at (order status)" and "Full refund at (order status)" be enabled? Details about the configuration can be found here.
Plugin reacts to Pickware order updates Should the automatic actions "Partially capture at (order item status)" and "Partially refund at (order item status)" be activated for Pickware order updates?
Trigger refund when shipped quantity is reduced in Pickware If enabled, trigger refund when shipped quantity is reduced in Pickware
Capture Full at (Order Status) Select the order status where the full remaining amount of an order should be captured in Klarna.
Refund Full at (Order Status) Select the order status where the entire amount already captured should be refunded to the customer by Klarna. Amounts of the orders that have not yet been captured will be released and can no longer be captured.
Partial capture at (Order item status) Select the status of the order item where amount of the item should be captured at Klarna.
Partial refund at (Order item status) Select the status of the order item where the amount of the item should be refunded by Klarna to the customer.
Buy Button Color Only for Klarna Checkout: Color of the buttons within the Klarna iFrames
Buy Button Text Color Only for Klarna Checkout: Text color of the buttons within the Klarna iFrames
Checkbox Color Only for Klarna Checkout: Color of the checkbox within the Klarna iFrames
Checkbox Hook Color Only for Klarna Checkout: Color of the checkbox hooks within the Klarna iFrames
Header Color Only for Klarna Checkout: color for the header within the Klarna iFrames
Link Color Only for Klarna Checkout: color for the links within the Klarna iFrames
Frame Radius The frame radius in pixels
Link to T&C URL to the general terms and conditions of your store
Link to right of withdrawal URL to the right of withdrawal of your store
Allow different shipping address Allow different shipping address for checkout
Disable Autofocus Deprecated, has no effect anymore
Check inventory before creating order? If "Yes", the inventory of the items in the shopping cart will be checked again before creating the order
External payment methods in checkout Select active payment methods which should also be available in checkout TODO
External Checkouts Select active payment methods, which should also be available in the checkout TODO
DHL Packstation Shipping Method Select an active shipping method which will be used for shipping to a DHL Packstation TODO
Create customer account (checkbox) Choose from different options if and how the checkbox should be displayed in the checkout to register as a customer in Shopware with the order
Subscribe to Newsletter (Checkbox) Choose from different options if and how the checkbox should be displayed in the checkout to register to the newsletter in Shopware with the order
Individual Checkbox Choose from different options if and how an individual checkbox should be displayed in the checkout TODO
Should technical error messages be displayed in case of an error? Should technical information be displayed in the checkout if an error occurs
Log level Select how detailed Klarna should log events. Production: Only errors are logged; Debug: All information from and to Klarna is logged
Log expiration time Select how many days log files should be stored before they are automatically deleted
Shipment number separator Specify a separator to allow multiple shipment numbers for one order to be transferred to Klarna
Enable On-Site Messaging? Select if you want to enable Klarna on-site messaging
Test or Live Mode for Klarna On-Site Messaging Do you want to use test or live mode for on-site messaging? This setting is independent from the setting above for the payment process
Enable On-Site Messaging on the product detail page? Select whether to display on-site messaging on the product detail page
Enable On-Site Messaging in Off-Canvas Shopping Cart? Select whether to display on-site messaging in the off-canvas shopping cart
Enable On-Site Messaging in Shopping Cart? Select whether to display on-site messaging in the shopping cart
Enable On-Site Messaging Top strip promotion on home page? Select whether to display on-site messaging on the home page header
Enable On-Site Messaging in Footer Area Choose if you want the On-Site Messaging to be displayed in the footer
On-Site Messaging Live Client ID This field cannot be edited and is automatically populated by the plugin once on-site messaging is enabled
On-Site Messaging Test Client ID This field cannot be edited and will be filled automatically by the plugin once on-site messaging has been activated

Configure payment method

The Klarna Checkout plugin includes the payment method Klarna Checkout, which must also be activated after installing and activating the plugin.

Please activate the payment type under 'Settings -> Payment types'.

The following fields must not be customized:

  • Name
  • Name
  • template
  • system class
  • database table

Assign payment type to shipping types

Before the Klarna payment method can be used, it must be enabled for the different shipping methods. Navigate to 'Settings -> Shipping costs', select a shipping method for which the Klarna payment method should be available and select the tab 'Payment method selection'.

Move the Klarna payment types from Available to Selected.

Repeat the process for all shipping methods you want to be available for the Klarna payment method.

Configure external payment methods

Store the desired external payment types within the plugin configuration.

Please note that external payment types are displayed only with defined names. All available names for external payment types can be found in this list.

Images for external payment types

For external payment types, you can define an image that will be displayed in Klarna Checkout for the respective payment type. This is possible within the free text fields of a payment type.

Please enter a complete URL to an image here.

An image is optional for external payment types.

Configure external checkouts

Store the desired external checkout within the plugin configuration.

Currently only PayPal Express and Amazon Pay are supported as external checkouts.

Images for external checkouts

For external payment types, you need to provide an image that will be displayed in the Klarna Checkout for the respective payment type. This is possible within the free text fields of a payment type.

Please provide a full URL to an image when doing so.

An image is required for external checkouts.

Uninstall plugin

The plugin can be uninstalled via the Plugin Manager in the Shopware 5 backend.

When uninstalling the plugin, the payment type will be set to inactive, but no orders or payment types will be deleted.

Also, do not delete the payment types manually, because otherwise there may be problems with orders that were paid with Klarna.

Special configuration

Phone number as a required field

If you want to display phone number as a required field in Klarna Checkout, you can configure it accordingly in Settings -> Basic Settings -> Storefront -> Login / Registration.

Date of birth as a mandatory field

If you want to display the date of birth as a mandatory field in Klarna Checkout, you can configure this accordingly under Settings -> Basic Settings -> Storefront -> Login / Registration.

Address addition line 1 & 2

The address addition lines must not be marked as mandatory fields.

klarna on-site messaging

Activate on-site messaging

If you are not yet activated for Klarna On-Site Messaging, set the option 'Activate On-Site Messaging' to "Yes" and save the plugin configuration from the Klarna Payments plugin again. You will now be guided through the activation process. You must accept the Terms of Usage (ToU) in order to use it.

Display options

Product detail page

Off-canvas shopping cart

Shopping cart

Top strip promotion

In shopping worlds

Use the "Klarna Banner" element for this and configure it according to your wishes in a shopping world.

Individual positioning

It is possible to integrate on-site messaging placements in your theme as you wish. For this, use the templates in the path frontend/bestit_klarna_onsite_messaging/placements from the Klarna plugin.

credit-promotion.tpl

Name Values Description
purchaseAmount value in cents (e.g. 1903) (required) The purchase value of the item(s) in cents. 1903 stands for 19,03€
refreshOnLoad false / true (optional) true: The placement will be re-initialized. This is necessary if the placement tag is added to the page content after the "pageload" event, as is the case with Ajax-loaded content.
shouldUpdate false / true (optional) true: The placement is reinitialized as soon as the price (purchaseAmount) changes. For example when the number of items to be purchased changes.

sidebar-promotion.tpl

homepage-promotion.tpl

Name Values Description
bannerType box / tall / wide (optional) The different types of banners Klarna provides.
refreshOnLoad false / true (optional) true: The placement will be reinitialized. This is necessary if the placement tag is added to the page content after the "pageload" event, as is the case with Ajax-loaded content or shopping world content.

top-strip-promotion.tpl

Technical information for developers

Custom checkbox

The custom checkbox can be filled with any function, which will be executed when the customer activates the checkbox in Klarna Checkout.

Customize checkbox text

The text can be customized via a text module in the Shopware backend. This is located in the namespace frontend/bestit/klarna/checkboxes with the name custom_event_checkbox.

Customize checkbox function

To extend the checkbox with a function a subscriber must be registered on the event BestIt_Klarna_Checkout_Custom_Checkbox. See the following example for a subscriber.

<?php

namespace App\Subscriber;

use BestitKlarnaCheckout\Components\Api\Model\Order as KlarnaOrder;
use BestitKlarnaPayments\Components\Constants;
use Enlight\Event\SubscriberInterface;
use Enlight_Event_EventArgs;

class SomeSubscriber implements SubscriberInterface
{
    public static function getSubscribedEvents()
    {
        return [
            'BestIt_Klarna_Checkout_Custom_Checkbox' => 'doSomething',
        ];
    }

    public function doSomething(Enlight_Event_EventArgs $args)
    {
        /** @var KlarnaOrder $klarnaOrder */
        $klarnaOrder = $args->get('klarnaOrder');

        // Do something with the order...
    }
}

Extra Merchant Data

The "Extra Merchant Data" events allow you to submit additional information and data to Klarna.

Order completion

The event 'BestitKlarnaCheckout\Components\Constants::EVENT_CREATE_ORDER_ATTACHMENT' can be used to add additional data during order completion. Its implementation must return an object of the class BestitKlarnaOrderManagement\Components\Api\Model\Attachment. See the following example:

<?php

namespace App\Subscriber;

use BestitKlarnaOrderManagement\Components\Api\Model\Attachment;
use BestitKlarnaCheckout\Components\Constants;
use Enlight\Event\SubscriberInterface;

class SomeSubscriber implements SubscriberInterface
{
    public static function getSubscribedEvents()
    {
        return [
            Constants::EVENT_CREATE_ORDER_ATTACHMENT => 'createOrderAddEmdData',
        ];
    }

    public function createSessionAddEmdData()
    {
        $attachment = new Attachment();

        $attachment->contentType = 'application/vnd.klarna.internal.emd-v2+json';
        $attachment->body = json_encode([
            'marketplace_seller_info' => [[
                'product_category' => 'Women\'s Fashion',
                'product_name' => 'Women Sweatshirt',
            ]],
        ]);

        return $attachment;
    }
}

Other

B2B sale

Selling to other companies is only possible with Klarna in certain countries. For this, see the answer to the question Can I sell to other companies with Klarna? from Klarna merchant support.

Within the Klarna checkout, the customer has the option to select a company address for B2B sales. In doing so, the customer is then redirected to the Shopware Standard Checkout, wherein the order can be completed as usual with other payment methods.