Klarna Adapter

Overview

Klarna adapter is a payment adapter for Klarna. It has support for Klarna Global and Klarna Shipping. Read more on Klarna Checkout or Klarna Payments documentation.

Environments

There are two environments that you can use.

Configuration

You start by adding Klarna Checkout payment adapter in Checkout configuration.

Create payment

To get a Klarna Checkout snippet, you start by creating a new checkout order for the order.

POST orders/{o_orderId}/payments

A Klarna checkout order will be created and a snippet script will be returned that can be inserted into you checkout page.

{
    "status": "CHECKOUT_INCOMPLETE",
    "htmlSnippet": "<div id='klarna-checkout-container'><script>...;</script></div>"
}

Klarna checkout adapter will also update your order with the payment details needed to get your frontend working.

{
    ...
    "payments": [
        {
            "type": "checkout",
            "id": "ps_paymentId",
            "reference": "7d31e2cf-2d46-4db0-b87d-d65dfaae298f",
            "amount": 10,
            "adapterId": "klarna-checkout-adapter",
            "name": "Klarna Checkout"
        },
    ]
    ...
}

Recurring payment (Optional)

To use Recurring Payments, merchants must activate this feature on both their Klarna/Kustom merchant account and in the Norce Klarna Checkout configuration. When this setting is enabled, all orders placed through this channel will be created in Klarna with the "recurring": "true" option selected. The token will be received upon payment finalization and saved with the order payment. This token represents the customer and their chosen payment method, which can be used to initiate future purchases.

{
    // ...
	"payments": [
          {
              "id": "pFqKphnRcDfGeaYFjyJLpKpmLhs",
              "adapterId": "klarna_checkout_adapter",
              "name": "Klarna Checkout",
              "merchant": "norcecheckouttest",
              "channel": "norce-checkout-se-klarna-recurring",
              "currency": "SEK",
              "type": "default",
              "orderId": "oXOSYKRP",
              "amount": 1148.54,
              "state": "reserved",
              "reference": "9fea967e-aa64-1789-acff-18517f9895a1",
              "attributes": {
                "username": "1e5dbff8-9bfc-42b1-a17d-xxxxxxxxx"
              },
              "actions": [],
              "recurring": {
                "token": "dc50da60-3bf4-4a70-9290-a89629cae418",
                "attributes": {}
              }
         }
	]
    // ...
}

How to Create a New Order and Add Klarna Checkout Payment Using a Previously Issued Token

To generate a new order and process payment through Klarna Checkout using a valid Klarna Checkout token, you can utilize the recurring payment feature. This process allows the creation of a new order without involving the customer, as their payment details are securely stored and reused using the Klarna Checkout token. The customer does not need to participate in or approve the transaction, simplifying the process for subscription services or repeat purchases.

Endpoint

POST /api/checkout/v1/orders/{order_id}/payments/recurring

Request body

{
   "token": "dc50da60-3bf4-4a70-9290-a89629cae418",
   "autoCapture": false
}

In this request, order_id is the identifier of the new order, and the token is retrieved from the previous order where the customer initially provided their payment details and consented to store a token for future use.

If the token is valid, Klarna Checkout will return a response containing a payment reference. The system will then automatically update the order with this payment information and finalize it. If fraud_status is not ACCEPTED, the order will be marked as "Accepted" with a pending payment status.

The autoCapture parameter determines whether the payment should be automatically captured upon order creation.

true: The payment will be captured immediately when the order is created. This is useful for digital goods or scenarios where fulfillment occurs instantly.

false: The payment will only be authorized but not captured until a separate capture request is made. This is typically used for physical goods, allowing merchants to capture the payment only when the order is shipped.

Update payment

When an order has been changed the Klarna widget needs to be updated. You need to suspend the Klarna checkout UI with javascript before calling update on Klarna adapter.

PUT orders/{o_orderId}/payments

The Klarna checkout order will be updated with the new remaining total of the order. When the payment is updated, you need to resume Klarna checkout UI so the new total will be loaded. Read more about suspending and resuming Klarna checkout in Klarna Checkout docs.

Validate checkout (TBD)

When the user clicks on "Place order" in Klarna Checkout UI a validation is sent to the validation callback. At this stage we will set the payment address so you can determine the customer. You can configure Norce Checkout to validate that all products are still available in stock and that all discounts are valid for the customer. A validation url can be configured in Norce Checkout settings.

If validation is successful your validation url return a 200 SUCCESS and Klarna will continue with confirming the payment. At this point the Norce order will go to processing state and the order will be locked to any changes except status update.

If you want to abandon the payment you return 400 BAD REQUEST along with a localized message that can be displayed to the customer in a popup in Klarna Checkout UI.

Confirm payment

When the payment has been confirmed Klarna will call the confirm endpoint. We update the payment and then redirects the user to the confirmation_url of Klarna checkout adapter.

Here is where you want to display the Klarna confirmation widget. You do this by getting the Checkout order from Klarna checkout adapter and render the snippet.

{
    "status": "CHECKOUT_COMPLETE",
    "htmlSnippet": "<div id='klarna-checkout-container'><script>...;</script></div>"
}

Push callback

It is possible that we never receives a confirm payment call due to communication problems but the payment at Klarna is still completed. This is handled by the push callback that is called 2 minutes after the payment is confirmed. The payment will be confirmed in Norce Checkout and an OrderAccepted event will be sent.