Public Release Note - Klarna Service Connector 6

1 Introduction

Welcome to the Intershop Klarna connector! The service connector adds Klarna Invoice and Part Payment to your Intershop Commerce Management installation.This Public Release Note provides important product information, including version information and dependencies. It also outlines the basic setup and configuration steps.

1.1 References

1.2 Version Information and Dependencies

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

Intershop Commerce ManagementKlarna Connector
7.8.2.0+6.1.7
7.9.3.1+6.1.7
7.10.2.2+6.1.7

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.

CartridgeDescriptionRequired
ac_payment_klarnaIncludes all of the base functionality and business logic which is used both in the storefront and the back-office applications.(tick)
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.

(tick)
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.
(error)
ac_payment_klarna_responsive_sfThe 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.
(error)

The sources for "as_payment_klarna_responsive_sf" and "ac_payment_klarna_responsive_sf" can be downloaded here (use your repository login and password for authorization):

https://repository.intershop.de//releases/com.intershop.public.source/s_payment_klarna/6.1.7/zips/s_payment_klarna-zip-src-6.1.7.zip

2 Feature Overview

2.1 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:

The payment form differs for the supported countries.

2.2 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:

OperationDescriptionValid for transaction state
CancelCancels the money reservation. The payment is deleted and no further operations are available.authorized
CaptureCaptures the reserved amount. The merchant receives the payment. The transaction is captured now.authorized
ReduceReduces the reserved amount. The transaction is still authorized.authorized
RefundRefunds a captured amount. Multiple refunds are possible.

captured, refunded

 

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

Transaction flow

2.3 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.

Pendig transactions flow

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.

2.3.1 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.

2.4 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.

2.5 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:

A PClass stored in DE_EUR_PClasses.json
{
    "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.

Please note: there is one implicit PClass that is never downloaded - this is payment by invoice in 14 days. The system considers that it is always present although it is not represented as a file.

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.

2.6 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.

2.7 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.

2.8 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

Note

The support for any of these may be specific to the type of the Klarna merchant account.

2.9 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.

StateNOT APPLICABLERESTRICTEDComment
The basket display type in the storefront is NET.(tick)  
There is no PClass for the country and currency code combination of the current basket.(tick) 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.(tick)  
Baskets with multiple shipping. (tick)Multiple shipping is not supported by Klarna.
Incompatible shipping and invoice address.(tick)(tick)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.

3 Setup

This section outlines some of the basic setup steps.

Note

Managing and deploying the Klarna Service Connector requires a continuous integration environment set up, configured as described in Cookbook - Setup CI Infrastructure.

3.1 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.

Warning

The Klarna Service connector comes with a dummy merchant account. It will not work out-of-the box even in the demo scenario. Please obtain a merchant ID and shared secret from Klarna in advance.

3.2 Set Up the Assembly

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

3.2.1 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:

build.gradle
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).

3.2.2 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).

3.3 Database Initialization

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

CartirdgeComment
ac_payment_klarna

This cartridge contains script that creates a background job that polls the statuses of pending payment transactions. The job is called KlarnaCheckOrderStatus by default and is global for the system. It processes all the channels in which Klarna is enabled. It is disabled by default. Running DBInit for this cartridge may be skipped but in this case the job should be created manually in the SMC if it is necessary to handle pending transactions.

The job 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 fairly well in any domain.

 

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

3.4 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.

PropertyDescriptionValues (sample)
intershop.payment.KLARNA_INVOICE.currenciesA comma separated list with all currencies that may be supported by the Klarna Invoice service.
EUR, SEK, DKK, NOK
intershop.payment.KLARNA_INSTALLMENTS.currenciesA comma separated list with all currencies that may be supported by the Klarna Installments service.
EUR, SEK, DKK, NOK
intershop.payment.KLARNA.country.<currency>

A comma separated list of countries in which a given currency is supported. For example:

intershop.payment.KLARNA.country.EUR = DE, NL, AT, FI

defines that Euro is used in Germany, Netherlands, Austria and Finland.

DE, NL, AT, FI
intershop.payment.KLARNA.check.pno.countriesA comma separated list of countries in which SSN check is performed. At the time of writing this is possible only in Sweden.
SE
intershop.payment.KLARNA.check.pno.no.address.failsDefines the behavior of the dummy SSN check implementation. If set to true and address cannot be downloaded for the given SSN then the authorization will fail.
true or false
intershop.payment.KLARNA.klarnaDebugShould be used only during development. Activates the built in debug of the Klarna library. Prints messages in the standard output.
true or false, might be commented
intershop.payment.KLARNA.testGatewayDownloadURLPatternThe pattern used to generate the download invoice link on the test gateway. Contains a placeholder for the invoice number.https://test.example.com/invoices/{invoice_num}.pdf
intershop.payment.KLARNA.liveGatewayDownloadURLPatternThe pattern used to generate the download invoice link on the live gateway. Contains a placeholder for the invoice number.https://live.example.com/invoices/{invoice_num}.pdf
intershop.payment.KLARNA.logoURLPatternThe pattern used to generate the URL of the Klarna logo image for the different countries. Contains a placeholder for the country.https://cdn.klarna.com/{country}/logo.gif
intershop.payment.KLARNA.cancelDelayThe delay in seconds of the automatic cancellation of pending orders. 5 seconds by default.5
intershop.payment.KLARNA.applicabilityOnIncompatibleAddressesDetermines if the payment method should be not applicable or restricted in case that the shipping and invoice addresses are considered incompatible. There are two possible values NOTAPPLICABLE or RESTRICTED.NOTAPPLICABLE or RESTRICTED.
intershop.payment.KLARNA.src.careOf

Defines the source of the careOf address field. For example this might be the Street3 (or Address3) field of the ICM address representation. If commented out, no careOf will be ever sent to Klarna. Possible values if defined:

  • Address.LINE1 - maps the careOf field to street1 ICM address field;
  • Address.LINE2 - maps the careOf field to street2 ICM address field;
  • Address.LINE3 - maps the careOf field to street3 ICM address field;
  • commented out - careOf is not sent to Klarna

Please note, that this mapping may not function correctly for some fields if restriction on different addresses is activated.

Address.LINE1 or Address.LINE2 or Address.LINE3
intershop.payment.KLARNA.src.houseNo

Defines the source of the houseNumber address field. For example this might be the Street3 (or Address3) field of the ICM address representation. If commented out, the value of the field will be retrieved from the payment instrument populated by the user. If there is no such value then its resolution will be skipped. Possible values if defined are the same as the values for key intershop.payment.KLARNA.src.careOf.

 

Please note, that this mapping may not function correctly for some fields if restriction on different addresses is activated.

Address.LINE1 or Address.LINE2 or Address.LINE3

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.

4 Configuration

4.1 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:

4.2 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.

NameDescription
Merchant IDIdentifier of the merchant in the Klarna system. Assigned by Klarna on opening of merchant account. This identifier is not secret information.
Shared Secret

A shared secret key. Assigned by Klarna. Should be kept secret and should be known only to Klarna and to the merchant. This shared secret is used for authentication in a custom authentication schema. At the time of writing this is:

Authorization: {XMLRPC-VERSION} {DIGEST}

{XMLRPC-VERSION} = xmlrpc-4.2

{DIGEST} = base64encode(hex(sha256("[merchant_id]:[currency]:[shared_secret]")))

Use live GatewayDetermines whether the live or test Klarna system should be used
Decline Pending OrdersDetermines whether the pending orders should be immediately declined, or their status should be pulled regularly by the shop from the Klarna system.
Prohibit multiple addressesDetermines if the invoice and shipping addresses should be the same. By default different addresses are allowed, but anyway they should belong to the same user (the first and last name and the telephone numbers should be the same). If checked the addresses should be completely the same.
Invoice ShipmentDetermines how the invoice should be shipped to the customer. Global for each service.

4.3 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.

Warning

The initialization executes some very important functions. It tests the connectivity with the Klarna system but also downloads the available PClasses. The services cannot work correctly without PClasses.

4.4 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.

4.4.1 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.

4.4.2 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.:

There is no one-to-one mapping between the properties of an "Intershop" address and a "Klarna" address. The comparison might be project specific.

4.4.3 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.

4.5 Replacing the Capabilities of the Connector

The Klarna Connector comes with the following list of implemented capabilities - Authorize, Cancel, Capture, ReduceRefund 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.

4.6 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:

5 Limitations

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

LimitationDescription
Multiple shipping

Multiple shipping is not supported.

If the service connector detects that the basket contains products which are shipped to multiple addresses then the Klarna payment methods will be restricted for this basket. The connector is usable (for some baskets) even if the setting MultipleShippingAllowed is set to true.

Gross base price displayKlarna supports only gross base price display with gross based taxation service.
Zero basketsBaskets with zero total amounts are not supported for checkout by Klarna.
Digital goodsBuying only digital goods is not supported scenario due to the lack of a real postal address required by Klarna.
Saving for later purchases

Neither invoice nor partial payments support the saving of the payment instrument for later usage. That limitation comes from the fact that the payment instrument is bound to a specific country. The corresponding checkbox should be unchecked in the management application as shown on the next screenshot.

ProductsProduct names or id-s may contain only characters from the Basic Latin and Latin-1 Supplement blocks of the Unicode table.
All other characters will be removed from the name before sending the request to Klarna. If the ID contains such character, payment will fail with error from Klarna.

6 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.

7 Changelog

7.1 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

7.2 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

7.3 Version KLARNA/6.1.2

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

7.4 Version KLARNA/6.1.1

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

7.5 Version KLARNA/6.1.0

  • KLARNA-82 - Reusable address fields

7.6 Version KLARNA/6.0.0

  • KLARNA-69 - Provide Klarna for ICM 7.8

 

Disclaimer

The information provided in the Knowledge Base may not be applicable to all systems and situations. Intershop Communications will not be liable to any party for any direct or indirect damages resulting from the use of the Customer Support section of the Intershop Corporate Web site, including, without limitation, any lost profits, business interruption, loss of programs or other data on your information handling system.

Customer Support
Knowledge Base
Product Resources
Support Tickets