Klarna payment

The Klarna payment app can be used to integrate with Klarna to handle payments in your e-commerce solution.

It is used for accepting payments with Klarna Checkout (KCO) or Klarna Payments using Hosted Payment Page (HPP) in Litium. For earlier versions of Litium, please see the Klarna extension

The Klarna payment app 1.3.0 supports the cancellation and refund of payments. Please note that Klarna payment app 1.3.0 requires Litium 8.2.3 and later.

The Klarna payment app 1.4.0 supports Klarna Shipping Assistant and the B2B flow in Klarna Checkout. Please note that Klarna payment app 1.4.0 requires Litium 8.4.1 and later.

lappnotice.jpg

Please also note that the environment must be either a live environment or a test environment for the configuration file to be accepted.

Values to replace in the template:

  • ports
  • environment
    • ASPNETCORE_HTTPS_PORT
    • AppMetadata__AppUrl
    • LitiumApi__ApiUrl
    • AppConfiguration__DisableCallbacks: If you are developing and are behind a firewall, you may need to disable background calls from external systems. The reason is that the external system cannot reach the addon app in your local environment and the app will not work as expected.
version: '3'
services:
  klarna-payment:
    image: registry.litium.cloud/apps/klarna-payment:1.4.0
    dns: 
    - 192.168.65.2
    restart: unless-stopped
    ports:
    - "10030:80"
    - "10031:443"
    environment:
    # Enable HTTPS binding
    - ASPNETCORE_URLS=https://+;http://+
    - ASPNETCORE_HTTPS_PORT=10031
    # Configuration for HTTPS inside the container, exported dotnet dev-certs with corresponding password
    - ASPNETCORE_Kestrel__Certificates__Default__Password=${CERT_PWD}
    - ASPNETCORE_Kestrel__Certificates__Default__Path=/https/localhost.pfx
    # Folder for the configuraiton, this is volume-mapped
    - CONFIG_PATH=/app_config
    # Folder where logfiles should be placed, this is volume-mapped
    - APP_LOG_PATH=/logs
    # Don't validate certificates
    - AppConfiguration__ValidateCertificate=false
    # Disable callbacks
    - AppConfiguration__DisableCallbacks=true
    # Url to this app
    - AppMetadata__AppUrl=https://customer-app-klarna-payment.localtest.me:10031
    # Url to the litium installation
    - LitiumApi__ApiUrl=https://customer.localtest.me:5001
    volumes:
    - ./data/klarna-payment/config:/app_config
    - ./data/klarna-payment/data:/app_data
    - ./data/klarna-payment/logs:/logs
    - ./data/klarna-payment/DataProtection-Keys:/root/.aspnet/DataProtection-Keys
    - ./data/https:/https:ro

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 should be "Test" or "Live".
  • Region: The region of the Klarna account. It should 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: It must be "Checkout".
  • UISettings (optional): These fields are used to customize the UI of the Klarna checkout iframe.
  • AdditionalCheckboxes: 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 on the order completion

Server-side callbacks validation

Klarna Payment App supports receiving 2 server-side callbacks: Address update and Country change. 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 2 translation keys:

  • sales.addressupdate.generalError: it will be used if there is any exception occurs.
  • sales.addressupdate.haschanged: it will be used when the country is changed.

These keys are translated in Litium BO, follow this link to learn how to use website text.

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 CustomerInfo class, which is used to determine if the logged in user is a person user or a organization user, if it is person user and CustomerType is 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 compeleted 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 order.

Is this page helpful?
Thank you for your feedback!