Klarna payment

  • Litium 8

The Klarna payment app can be used to integrate with Klarna to handle payments in your e-commerce solution. It is developed and maintained by Litium.

The Klarna payment app supports Kustom Checkout (KCO). The app supports capture, cancel and refund transactions.

Version dependencies

  • Klarna payment app 1.6.0

    • Supports validation callback.

    • Requires Litium 8.8.0 and later.

Installation

Litium serverless cloud - Use the Cloud CLI to install the app.

Litium legacy cloud - Contact support to install the app in your test and/or production environment.

Local environment - A Docker compose template is available for local installation.

Configuration file

The configuration file must have json format and UTF-8 encoding.

{
  "Klarna": {
    "PaymentAccounts": [
      {
        "PaymentAccountId": "SE",
        "MerchantId": "",
        "SharedSecret": "",
        "Environment": "Test",
        "Region": "Europe", 
        "PaymentOptions": [ "Checkout" ],
        "ShowVATRegistrationNumberField": true,
        "UISettings": {
            "ColorButton": "#FF0000",
            "ColorButtonText": "#FFFF00",
            "ColorCheckbox": "#FF0000",
            "ColorCheckboxCheckMark": "#FFFF00",
            "ColorHeader": "#0000FF",
            "ColorLink": "#00FF00",
            "RadiusBorder": "25",
            "AdditionalCheckboxes": [
            {
                "Id": "newsletter_opt_in",
                "Checked": false,
                "Required": false,
                "Text": {
                    "en-US": "Please add me to the newsletter list, read more here [link](http://www.google.com)",
                    "sv-SE": "Lägg till mig på nyhetsbrevslistan, läs mer här [link](http://www.google.com)",
                    "*": "Please add me to the newsletter list, read more here [link](http://www.google.com)"
                }
            },
            {
                "Id": "newsletter_opt_in_required",
                "Checked": false,
                "Required": true,
                "Text": {
                    "en-US": "(Required) Please add me to the newsletter list, read more here [link](http://www.google.com)",
                    "sv-SE": "(Required) Lägg till mig på nyhetsbrevslistan, läs mer här [link](http://www.google.com)",
                    "*": "(Required) Please add me to the newsletter list, read more here [link](http://www.google.com)"
                }
            }
            ]
        }
      },
      {
        "PaymentAccountId": "DK",
        "MerchantId": "",
        "SharedSecret": "",
        "Environment": "Test",
        "Region": "Europe", 
        "PaymentOptions": [ "Checkout" ]
      },
    ]
  }
}

  • PaymentAccountId: Identifier to select the account. It must be a unique string.

    Note: PaymentAccountId should not contain any spaces. If it contains spaces, it will cause the app to crash when trying to find the correct payment account for the cart's PaymentOptionId. The reason for this is that Litium sends it as "<PaymentAccountId> Checkout" and the app splits into spaces to retrieve the id. More than one space causes it to split incorrectly.

  • MerchantId: Klarna UserName, this is Klarna merchant id followed by a string. This value is assigned by Klarna.

  • SharedSecret: Klarna Password, this value is assigned by Klarna.

  • Environment: Klarna environment. It must be either "Test" or "Live".

  • Region: The region of the Klarna account. It must be one of these values: "Europe", "NorthAmerica", "Oceania".

  • ShowVATRegistrationNumberField: If true, a optional VAT registration number field will be shown in the address form when the customer type is an organisation.

  • PaymentOptions: Must be set to "Checkout".

  • UISettings (optional): These fields are used to customize the UI of the Klarna checkout iframe.

  • AdditionalCheckboxes (optional): Additional checkboxes can be used to interact with consumers. They will be shown on the Klarna checkout screen. The consumers' answers will be stored in the Payment.AdditionalInfo field upon order completion

Server-side callbacks validation

Klarna Payment App supports receiving three server-side callbacks: Address update, Country change and Order validation. If the address or country is changed on the checkout page. Klarna will request to try to verify the changes. Klarna Payment App will receive and call Litium for updating the address.

If the country is changed, Litium will respond that it needs to be redirected to the checkout page to update the new country.

If the address is changed, Litium will validate the Address and then update it to the cart. The custom address validation rules must be derived from IValidationRule<ValidateCartAddressArgs> class. These rules will also be applied when the cart is validated. E.g:

internal class FirstNameNotEmpty : ValidationRuleBase<ValidateCartAddressArgs>
{
    public override ValidationResult Validate(ValidateCartAddressArgs entity, ValidationMode validationMode)
    {
        var result = new ValidationResult();
        var name = entity.BillingAddress.FirstName;
        if (string.IsNullOrEmpty(name))
        {
            result.AddError("Address", "First name must be not empty.");
        }

        return result;
    }
}

There are two strings defined as website text that are used by the validation:

  • sales.addressupdate.generalError: will be used if any exception occurs.

  • sales.addressupdate.haschanged: will be used when the country is changed.

These keys are translated in Litium BO. Learn how to use website text.

The order validation callback will trigger the Pre-order validation in Litium.

Selling to organizations

In order to handle the checkout iframe displaying form of Person or Organization, the CustomerType of CheckoutFlowInfo should be defined. 

  • If CustomerType is not specified, the checkout iframe will display form for both Person and Organization.

  • If CustomerType is Person, the checkout iframe will display Person's form.

  • If CustomerType is Organization, the checkout iframe will display Organization's form.

Note: There is a Type property of the CustomerInfo class, which is used to determine if the logged in user is a person user or a organization user. If it is a person user and CustomerType is set to Organization, Klarna won't accept it, and vice versa.

When an organization buyer places an order, some information about the organization is stored in AdditionInfo property of the Payment. The following keys is available:

  • Klarna_Organization_Registration_Id

  • Klarna_Vat_Id

  • Klarna_Billing_Address_Reference

  • Klarna_Shipping_Address_Reference

Allow separate shipping address

If the AllowSeparateShippingAddress property of CheckoutFlowInfo is true, it will allow the user enter a separate shipping address. Otherwise, the shipping section will not be visible and the shipping address of a completed order will be the same as the billing address

Using Klarna Shipping Assistant

To enable the use of Klarna Shipping Assistant:

  1. Configure the Direct Shipment app to provide a shipping option with integration type set to PaymentCheckout.

  2. Add this shipping option to channels where you want to use KSA. Additional shipping options configured on the channel will be sent to Klarna and selectable in KSA. Note: The fee for the integrated shipping option should be set to 0 in Litium.

If you activate a TA system integration with KSA, the additional shipping options configured on the channel in Litium will be used as fallback if the TA system integration fails.

The field mappings for shipping data (height, width, length, weight and tags) in Litium backoffice will be used by the Klarna app to provide information to the TA system.

Note: KSA will add any fee for shipping options from the integrated TA system to the order, the shipping_option_changed callback is currently not supported by the Klarna payment app. This means that Litium will not be able to calculate any free shipping discounts for these shipping options.

When an order is placed, Litium will save the data received from Klarna about the selected shipping options as Additional Info on the ShippingInfo for the order.

External payment methods

Klarna can show additional payment methods in the checkout iframe. When the customer selects the external payment method and clicks the buy button, the buyer will be redirected to the provided URL (RedirectUrl field which is set in the configuration file). On the redirected page the buyer will finalize the purchase. A list of supported external payment methods and additional requirements for integration can be found in the Klarna documentation.

Please note that the Klarna app is only responsible for redirecting the buyer to the provided URL. The merchant is responsible for implementation of the logic needed to switch to the other payment method in Litium, and providing the buyer with UI to complete the purchase flow.

External payment methods is set in the ExternalPaymentMethods property on each payment account in the configuration file.

"ExternalPaymentMethods": [
    {
        "Name": "PayPal",
        "RedirectUrl": "https://paypal.com/?klarnaOrderId={klarnaOrderId}&paymentAccountId={paymentAccountId}&cartContextSystemId={cartContextSystemId}",
        "ImageUrl": "https://www.paypalobjects.com/digitalassets/c/website/logo/full-text/pp_fc_hl.svg",
        "Fee": 55,
        "Description": {
            "en-US": "Description en-us PayPal",
            "sv-SE": "Description sv-se PayPal",
             "*": "Description PayPal"
        },
        "BuyButtonLabel": "Continue",
        "Countries": [ "se", "gb" ]
    },
    {
        "Name": "Amazon Pay",
        "RedirectUrl": "https://pay.amazon.com/",
        "ImageUrl": "https://amazon-pay.brightspotcdn.com/75/8c/05780a7c41eb91759c77310a6f85/amazonpay-logo-rgb-clr.svg",
        "Fee": 25,
        "Description": {
            "en-US": "Description en-us Amazon Pay",
            "sv-SE": "Description sv-se Amazon Pay",
            "*": "Description Amazon Pay"
        },
        "BuyButtonLabel": "Complete",
        "Countries": [ "se", "gb" ]
    }
]
  • Name (string) (required): The name of the payment provider, only supported External Payment Methods in KCO.
  • RedirectUrl (string) (required): URL to redirect to. Max 2000 characters.
    When configuring the redirect URL you can use placeholders that will be filled with current values by the Klarna app. The following placeholders are available:
    • {klarnaOrderId}: id of the order in Klarna Checkout. Can be used to fetch data from the Klarna order using Klarna Checkout API (eg billing and shipping address and selected shipping option).
    • {paymentAccountId}: the payment account of the Klarna app used to initialise the order in Klarna.
    • {cartContextSystemId}: the id of the CartContext in Litium connected to this payment.
  • ImageUrl (string): URL to an image to display as icon for the payment method. Max 2000 characters.
  • Fee (long): Minor units. Includes VAT.
  • Description (string): Multiple languages are supported, or use "*" for all locales. Max 500 characters.
  • BuyButtonLabel (string): Can be "Continue" or "Complete".
  • Countries (array of strings): Purchase countries for which the payment method should be displayed. ISO alpha-2 codes.

Sending Extra Merchant Data to Klarna

When creating an order in Klarna, the merchant can provide additional data about the purchase in an object Klarna calls "attachment". This is required when using Klarna to sell some types of goods, like travel or event tickets, hotel reservations or vouchers.

Attachment payload is extracted from CheckoutFlowInfo.AdditionalData with key KlarnaPayment_attachment, the content should be the full attachment object serialized into a json-string that contains the body and content_type.

See Klarna Checkout API and Attachment Schema (klarna.com) for attachment details.
Was this page helpful?
Thank you for your feedback!