Introduction

References

• Concept - Payment Framework
• Cookbook - Payment

Version Information and Dependencies

This delivery and the accompanying documentation are valid for the following combinations of software versions:

This version of the connector is based on the Payment API 2.8.0.

The next table provides information about the cartridges included in the package. Not all of these cartridges are required.

Cartridge	Description	Required
ac_payment_klarna	Includes all of the base functionality and business logic which is used both in the storefront and the back-office applications.
ac_payment_klarna_bo	Includes functionality which is available solely in the Commerce Management application. E.g., this is the initialization of the payment connector which downloads the PClasses.
as_payment_klarna_responsive_sf	The sole purpose of this cartridge is to enable the Klarna payment connector for the following application types: intershop.B2CResponsive intershop.SMBResponsive The cartridge may be skipped if the custom project does not support these application types or Klarna should not be available in all of them.
ac_payment_klarna_responsive_sf	The cartridge provides some functionality which is relevant in the workflow of the responsive storefront only. E.g., when the invoicing country of the basket is changed irrelevant Klarna payment instruments are deleted.

The source for "as_payment_klarna_responsive_sf" and "ac_payment_klarna_responsive_sf" is available here

...YOUR_REPOSITORY.../releases/com.intershop.public.source/s_payment_klarna/6.1.7/zips/s_payment_klarna-zip-src-6.1.7.zip

Feature Overview

Payment Options

The Klarna connector offers two payment options - invoice and part payment. With the first option the customer will pay with a single invoice. With the second option the customer will pay by several installments. Both payment methods come as a separate services and should be configured separately. Below is a sample payment form filled by an end user for invoice payments:

Merchant Operations

When the user fills in the payment form correctly he/she is redirected to the order review page. Later on, the system will attempt direct authorization by contacting the Klarna system. The user never needs to leave the site of the merchant. Sensitive payment data (e.g., credit card numbers) is neither required, nor stored or transmitted. After the order has been completed, the transaction is usually authorized. The connector supports the following operations in the merchant back-office:

The next figure illustrates the possible changes of transaction states during the normal transaction flow.

Pending Transactions

Due to some fraud checks Klarna cannot authorize some of the payment requests immediately. These transactions are set to a Pending state. The connector checks the state of the pending transactions in the Klarna system regularly by using a background job. Depending on the result of the transaction check a transaction may be cancelled, authorized or left in a pending state. Usually the final state (authorized or cancelled) is resolved in less than 24 hours. The next figure illustrates this workflow.

The merchant cannot do anything with pending transactions. The merchant may configure the system to automatically cancel any pending transactions. In this case the connector will put the transaction in a queue for a delayed cancellation request. By default the transaction stays in this queue at least 5 seconds. This is necessary for technical reasons - the Klarna system cannot cancel pending orders immediately - it needs a few seconds to put the transaction in an up-to-date state.

Transaction Status Polling

The job that polls the state of the pending transactions is called KlarnaCheckOrderStatus by default. It is created by the database initialization script located in ac_payment_klarna. It is global for all shops that use Klarna and is installed in the root domain. It is disabled by default and should be configured according to the project requirements and expectations. In the demo scenarios it is recommended to run the job manually. The configuration may be completed in the SMC as shown on the next figure.

The job may be deleted and/or manually recreated. Its properties are:

• Default Name (may be changed): KlarnaCheckOrderStatus
• Default Description (may be changed): Check all Klarna orders having the payment status pending.
  
• Pipeline Name: ProcessKlarnaCheckOrderStatus
• Pipeline Start Node: Start

By default the job will be installed in the root domain but this is not required. The job should run well in any domain.

Supported Countries

Klarna does not operate in all countries. The following countries may be supported - Germany, Austria, Netherlands, Norway, Sweden, Finland and Denmark.

The corresponding currencies should be supported too. E.g., if the invoicing country is Norway then Norwegian krone should be enabled in the shop.

PClasses

The so called PClasses are little pieces of data formatted as JSON which determine what kind of payment options are available under certain conditions (e.g., pay once in 14 days, pay once after 6 months, etc). PClasses are stored in files in the shared file system following the naming convention below:

<country>_<currency>_PClasses.json

Here:

• <country> - the country for which the PClass is valid - e.g. DE, AT, SE, etc
• <currency> - the currency for which the PCLass is valid - e.g. EUR, SEK, etc.

Example of a valid PClass file name for Germany and Euro: DE_EUR_PClasses.json

The most important properties that are stored in a PClass and in its name which have semantics for the connector are:

• country - the invoicing country for which is the PClass;
• currency - the purchase currency for which an order will be possible;
• the type of the PClass - e.g., invoice or installments, fixed or flexible;

All other properties are used for display purposes only and do not influence the workflow.

Below is a sample PClass which determines that Klarna part payment is available in Germany for payments in EUR:

{
    "description": "Ratenkauf",
    "months": 24,
    "startfee": 0.0,
    "invoicefee": 1.95,
    "interestrate": 14.95,
    "minamount": 0.0,
    "country": "DE",
    "id": 3113,
    "type": 1,
    "expire": 0,
    "eid": 1395
}

PClasses affect the available payment options in the storefront. If there is no PClass for a given country/currency pair the payment with Klarna may be disabled.

The PClasses are downloaded form Klarna when the connector is "initialized". The connector is initialized when the "Initialize" button in the back office is pressed. This is described separately in this document. The end user chooses a PClass which is represented as a payment option in the storefront UI.

SSN Checks

The forms in which the user enters payment data are different for each supported country. In some countries the so called SSN is required. This is the personal number of the customer (people are assigned unique numbers in these countries). The connector may send a special request to Klarna which verifies that the SSN is correct and downloads the invoicing address registered for this number. Custom projects may implement some fraud checks based on the downloaded address. Currently there is an appropriate extension mechanism which can be utilized during the authorization process by custom projects. Nevertheless additional development is needed. Only a dummy implementation is provided with the standard connector.

Invoice Download

The customer may download Klarna invoices of captured transactions in the first 30 days after the transaction had been captured. The download link is available in the My Account section as shown on the next screenshot.

After 30 days the link becomes inactive.

Invoice Shipment

The merchant may define how Klarna invoices should be sent to the clients. This is a setting defined in the configuration of the payment service (in other words it is channel specific). Available options currently are:

• Mail
• EMail
• Klarna Mobile

Applicability Restrictions

A payment method in ICM may be considered as:

• Applicable - the method is available in the storefront and can be used by the customers;
• Not applicable - the method is hidden and invisible in the storefront application;
• Restricted - the method is visible in the storefront but it is disabled, it can't be used by the customer;

The table below describes the situation in which Klarna is considered restricted or not applicable.

State	NOT APPLICABLE	RESTRICTED	Comment
The basket display type in the storefront is NET.
There is no PClass for the country and currency code combination of the current basket.			The country of the invoice address is considered. But anyway the invoice and shipping addresses should be in the same country.
The basket is covered by another payment instrument.
Baskets with multiple shipping.			Multiple shipping is not supported by Klarna.
Incompatible shipping and invoice address.			This restriction applies if the shipping and invoice addresses are completely or partially different. Depending on the UI based configuration the addresses should be either completely the same or they should belong to the same user (first and last name, country and phone have to be the same). If this is not the case then the restriction is applied. If Klarna is restricted or not applicable is configurable.

Setup

This section outlines some of the basic setup steps.

Preconditions

• A merchant account should be obtained from Klarna.
• The distribution of the Klarna Service Connector should be available on an accessible Nexus server.
• A set up and configured CI environment - see Cookbook - Setup CI Infrastructure.
• A running Intershop Commerce Management installation that matches the system requirements.
• Knowledge of how to add the delivered artifacts to the continuous integration environment.
• Knowledge of how to deploy to a test or production environment.

Set Up the Assembly

To add the Klarna Service Connector to your Intershop Commerce Management system, it is possible to:

Incorporate the Cartridge into an Already Existing Assembly

Below is a hint about what may be added to the build.gradle file of the assembly:

cartridges {
        def storefrontCartridges = [
            'app_sf_responsive',
            'app_sf_responsive_cm',
            'app_sf_responsive_b2c',
            'app_sf_responsive_smb',
            'as_responsive',
            'app_sf_responsive_b2b',
            'app_sf_responsive_costcenter',
            'as_responsive_b2b',
//
 this are the two cartridges, which we delivered in source code and you 
have to add these files to your responsive source project
                 'ac_payment_klarna_responsive_sf',
                 'as_payment_klarna_responsive_sf'
           ]
        include(*(storefrontCartridges.collect { project(":$it") }), in:[development, test, production])

…..

        //standard klarna provider 
        def klarnaPaymentProvider = [
            'ac_payment_klarna',
            'ac_payment_klarna_bo'
        ]
        
        include (*(klarnaPaymentProvider.collect {"com.intershop.services.payment_klarna:$it"}), in: [development, test, production])    
    
        order = listFromAssembly(baseAssembly) + storefrontCartridges + klarnaPaymentProvider
    }
...
assemblyBuild {
    database {
        inherit(baseAssembly)
        initCartridges = ['ac_payment_klarna']
    }
}

Furthermore you have to adapt the ac_payment_klarna_responsive_sf/build.gradle file in the following way:

apply plugin: 'static-cartridge'
  
intershop
{
       displayName = 'Adapter - Payment Klara - Responsive SF integration'
}
  
  
dependencies
{
//   compile project(':ac_payment_klarna') --> will be replaced by:
     compile group: 'com.intershop.services.payment_klarna', name: 'ac_payment_klarna'
  
// compile group: 'com.intershop.responsive', name: 'app_sf_responsive' --> will be replaced by:
   compile project(':app_sf_responsive')
}

Now you have to insert the following lines into file: „intershopBuild.version“

com.intershop.services.payment_klarna:ac_payment_klarna = 6.1.7
com.intershop.services.payment_klarna:ac_payment_klarna_bo = 6.1.7

For details about adding cartridges to an assembly see the corresponding recipe in the Cookbook - Gradle Assembly Tools (valid to 7.8).

Create a New Assembly Inheriting from an Intershop Commerce Management Based Assembly

Of course, a new assembly may be created that inherits from ICM base assembly - see the corresponding recipe in the Cookbook - Gradle Assembly Tools (valid to 7.8).

Database Initialization

There are two cartridges that contain database initialization scripts. The following table summarizes the details.

ac_payment_klarna

The connector may be initialized automatically as part of the CI process (initialization cartridges are specified in the build.gradle of the assembly). Or manually if ever needed, e.g., dbinit -t=ac_payment_klarna

Defining File-Based Configuration

Before deploying the new assembly to a test or production environment, you may want to adjust some file-based configurations required by the Klarna Service Connector. The table below explains the meaning of these properties.

EUR, SEK, DKK, NOK

EUR, SEK, DKK, NOK

DE, NL, AT, FI

SE

true or false

true or false, might be commented

According to Recipe: Change Deployed File Content With Filters this setting may be overridden by <IS_SHARE>/system/config/cartridges/ac_payment_klarna.properties.

For details about adding new configuration files, see Recipe: Deploy Custom Files.

Configuration

Enabling within the Organization Management

In the Organization Management application, the managed services corresponding to the Klarna Connector are by default named Klarna Invoice and Klarna Installments. The first one is used for payment by invoice (one payment per purchase), the second one is used for payment by installments. The services have to be enabled for the Sales Organization in which the connector will be used. This is shown on the next screenshot:

Apply UI-Based Configuration

The Klarna Connector requires some post-deployment configurations in Organization Management and Commerce Management. For details about enabling a payment service, see - Recipe: Enable a Payment Service. The following screenshot shows the configuration UI.

The table below explains the settings that may be set at the payment service. The configurations are the same for both the Klarna Installments and Klarna Invoice services.

Connector Initialization

Once the connector is configured, the payment services must be initialized in the channel context of the Commerce Management application. To do so, use the ad-hoc Initialize button. The button is available in the Preferences tab, as shown in the the screenshot below.

Personal Number Check

In certain countries Klarna may fetch registered addresses based on a personal number (or social security number) provided by the customer. At the time of writing this is Sweden only. The Klarna connector may be customized to use this check and to show error messages in case that the registered addresses do not match the shipping and billing addresses of the shopping cart. This intends to enhance the security of the integration. The check is currently triggered only during the authorization phase.

Enabling the Check

The SSN check is enabled by a configuration property. The property intershop.payment.KLARNA.check.pno.countries enumerates the countries in which the PNO check is performed. Example:

intershop.payment.KLARNA.check.pno.countries = SE

If the value is empty or the key is missing then no check is performed at all.

Default Implementation

In the standard connector there is only a dummy check enabled for Sweden. It sends the SSN that the customer entered to Klarna and the check simply fails if no address can be retrieved for this specific SSN. No other checks are implemented. The check is triggered during the authorization. Its behavior can be disabled by overriding the configuration property intershop.payment.KLARNA.check.pno.no.address.fails and setting it to false.
In case that the check fails then error messages are shown to the end user, e.g.:

Replacing the Default Implementation

Custom projects that would like to replace the dummy implementation should provide their own custom Guice binding for the interface com.intershop.adapter.payment.klarna.capi.pno.KlarnaServicePNOCheck. This is a functional interface with one method:

public List<Incident> checkAddresses(PaymentContext context, Payable payable, List<KlarnaAddressDetails> addresses);

The address list passed as an argument is retrieved from Klarna and should be verified against the provided payment context and payable. In case that the addresses cannot be verified successfully a list with errors should be returned which will be eventually shown to the end user.

Replacing the Capabilities of the Connector

The Klarna Connector comes with the following list of implemented capabilities - Authorize, Cancel, Capture, Reduce, Refund and Validate (just a stub). All of these capabilities are initialized by factories. The interfaces of these factories are located in package com.intershop.adapter.payment.klarna.capi.service.capabilities. Capability XXX is initialized by factory XXXFactory. If a project wants to replace some capabilities then it may provide its own Guice binding for this factory. If the custom implementation of the factory returns null then the capability will be disabled.

Localization

The Klarna connector provides English and German localization files for the payment specific input field labels, error messages etc.

You can find the existing localization files here:

<IS.INSTANCE.SHARE>/system/cartridges/ac_payment_klarna/release/localizations

<IS.INSTANCE.SHARE>/system/cartridges/ac_payment_klarna_bo/release/localizations

For details about localization, see:

• Concept - Localization
• Cookbook - Localization (valid to 7.9)

Limitations

This following table summarizes known limitations with this implementation of the connector.

Known Issues

• Due to limitations in the Payment API the Payable argument of the Validate capability is always null in any implementation. This is a known bug tracked as IS-16943 - The parameters context and payable of the Validate capability are never passed.

Changelog

Version KLARNA/6.1.7

• KLARNA-150 - Dependencies to common XML libraries externalized
• KLARNA-149 - Remove unnecessary messages from log file
• KLARNA-133 - Fix side effects when in checkout UI when using multiple Payment Connectors in parallel

Version KLARNA/6.1.5

• KLARNA-147 - No error message shown in case of denied payment
• KLARNA-136 - Net Total at Klarna is wrong after reduce / refund
• KLARNA-127
  
  • A denied payment authorization results in an error log entry.
  • Errors reported by Klarna are reported twice.

  • Klarna reduce function is not processed in the Klarna Backoffice

Version KLARNA/6.1.2

• KLARNA-126 - Provide source for integration in responsive storefront

Version KLARNA/6.1.1

• KLARNA-120 - Fix localization issue.
• KLARNA-119 - Provide Klarna for ICM 7.9

Version KLARNA/6.1.0

• KLARNA-82 - Reusable address fields

Version KLARNA/6.0.0

• KLARNA-69 - Provide Klarna for ICM 7.8