August 20, 2024

Klarna and Spree integration

Klarna is one of Europe’s largest banks and is providing payment solutions for 60 million consumers across 100,000 merchants in 14 countries. Klarna offers direct payments, pay after delivery options and installment plans in a smooth one-click purchase experience that lets consumers pay when and how they prefer to.

The integration of Klarna with your Spree Commerce store can be done quickly and easily following the guidelines mentioned below.

The benefits of using Klarna for your eCommerce business

Klarna Checkout

Klarna Checkout is a “one-stop-shop” platform. By providing harmonized presentations of payment and delivery options, coupon collection and up-selling, it lets merchants sell globally with a personalized purchase experience, using only one partner.

Pay Now

Simple and secure direct payments. A flexible-friction payment method for instant payments and subscriptions. Pay now offers one-click payments when possible, and dynamically asks for more data when needed to keep the customer safe.

Pay Later

Buy now and pay later at your convenience with a few simple steps. Interest-free invoice payments that are locally optimized and globally compliant.

Slice it

Flexible consumer finance that lets customers pay over time. Klarna’s Slice it is a modern installment product that gives your customers the intuitive control and flexibility they need to make spreading the costs of a purchase over time worry and hassle free. Slice it increases purchasing power for your customers, which in turn boosts sales for you.

Merchant Portal

With Klarna comes a brand new order-handling system: the Merchant Portal. You can choose between different apps that brings value to your merchants business such as Merchant Insights, On-site marketing and Boost (Klarna funding).

How to integrate Klarna with Spree

Check out: Klarna Payments Integration for Spree

Installation (beta)

This gem is currently in a public beta phase. For the time being it will only be installable via git:

gem 'klarna_client', github: 'bitspire/klarna_client'
gem 'spree_klarna_payments', require: 'klarna_gateway', github: 'bitspire/spree_klarna_payments'

And then execute:

$ bundle

In your project include the migrations, JavaScript and stylesheets:

$ rails generate klarna_gateway:install

Please note that the version is still 0.9. We want to have the option to make breaking changes during the transition to 1.0.

Spree configuration

After the installation, create a new payment method and select Spree::Gateway::KlarnaCredit as the gateway. After saving the payment method, you can configure your Klarna credentials and set design options for how Klarna is displayed to the customer in the checkout.

The “country” option is mandatory and refers to the region the account is associated with. In the example above it’s us for the USA, other values would be uk for the United Kingdom and de for Germany.

There are two other things to configure. Set the payment method to “active” and only enable it in the frontend. Some payment methods can be used in the backend by the merchant. As this is not appropriate for Klarna Payments, it should be disabled. You can also configure to automatically capture the payments when the customer confirms their order. The test mode allows you to test the integration with test data. Disable this option for production use.

Note: After you ran klarna_gateway:install the initializer in config/initializers/klarna_gateway.rb allows some configuration. It’s usually not necessary to touch the file unless you’re sure what you’re doing.

Technical information

The integration adds the necessary code to the checkout. It consists of mainly of three parts:

a template to display the iframe when Klarna is selected as the payment method
a JavaScript library/jQuery plugin to handle sessions and authorisation
a CSS file with very little code to display the iframe correctly

The template can be overwritten by copying the file to app/views/spree/checkout/payment/_klarna_credit.html.erb in the main application. Note the initialisation JS code which is required for the integration to work.

JavaScript library

The JavaScript library is used to initialize a session with Klarna, authorize the requested amount and handing the obtained authorization token to Spree. This token is later used when authorizing the payment in Spree.

If the checkout (template) was modified, it can be necessary to adapt the integration as well. The KlarnaGateway library was extracted to make that easier. It is initialized as follows:

KlarnaGateway.loadSdk(this, document, function() {
  jQuery(".klarna_credit_box").klarnaAuthorize();
});

loadSdk will load the Klarna JavaScript SDK from the CDN and call the provided callback function when the file was loaded. Note that it’s also possible to do that manually by including the file with a <script> tag. Please see the JavaScript SDKdocumentation for more details.

The initialization is done in klarnaAuthorize() on the payment step page in the checkout. It will create a session with Klarna and load the iframe when Klarna is selected by the user. It is called on the container (.klarna_credit_box in this case) in which the iframe will be inserted.

To make customizations easier klarnaAuthorize() takes some optional arguments. Here they are with their defaults:

$(container).klarnaAuthorize({
  // Element that stores the authorization token. This will usually be a hidden input
  // field for the payment source.
  authorizationToken: $("#klarna_authorization_token", this),

  // The form that is submitted on the payment page. The submit event is prevented so
  // the payment can be authorized before progressing any further.
  form: $("#checkout_form_payment"),
  
  // Load the Klarna iframe directly after page load, not only when Klarna was selected.
  loadDirectly: false,

  // Function to perform when the form is being submitted. It is executed before the authorization
  // is being requested.
  onSubmit: function(settings) {},

  // Function to perform when the authorization process is aborted, e.g. because there was an
  // error or the user did not input required information.
  onAbort: function(settings) {},

  // Elements that trigger a check whether Klarna is selected. The iframe is only loaded
  // when Klarna is selected
  paymentChangedElements: $("input[name=\"order[payments_attributes][][payment_method_id]\"]"),

  // Where to find the payment method id. This is necessary if there are more than one Klarna
  // payment methods in the store.
  paymentId: $(this).data("payment-method-id"),

  // Wraper for the whole payment method. This is being hidden when Klarna returns with `show_form == false`.
  paymentMethodWrapper: $(".form-payment-method-klarna_credit"),	
  // The session URL of the store. The store needs to create a session from the server
  // side. This should not be changed.
  sessionUrl: Spree.url(Spree.pathFor("/klarna/session")),

  // The submit button that triggers the authorization. This button will be disabled while
  // the autorization is issued.
  submitButton: $("form.edit_order :submit")
})

Klarna API documentation

Klarna’s API is used by the payment gateway
Javascript SDK for the frontend part

For more information see Klarna’s Developers Portal.

Example of Klarna and Spree integration

Finery London is an online womenswear brand with a unique point of view and a mission to make modern, inspiring and sophisticated styling accessible, without compromising on quality. The company uses Spree for its modern and elegant eCommerce platform and Klarna for its Pay after Delivery payment method.