Klarna Checkout Adapter

Overview Document: Payment Adapters Overview

Overview and Unique Capabilities

The Klarna Checkout Adapter integrates Klarna Checkout with Norce Checkout. This page focuses on the unique technical details and configuration for Klarna.

Supported payment methods and other features: Features Overview

Configuration in Norce Admin

The adapter is configured using the following unique details obtained from Klarna:

API Settings (required)

Redirect URLs (required)

Shipping Countries (required)

Optional Configuration

The merchantReferenceSource option determines how Klarna's merchant_reference1 and merchant_reference2 fields are populated:

• OrderId: merchant_reference1 = Order.Id, merchant_reference2 = Order.Cart.Reference
• OrderCartReference: merchant_reference1 = Order.Cart.Reference, merchant_reference2 = Order.Id
• OrderReference: merchant_reference1 = Order.Reference, merchant_reference2 = Order.Id

Checkout UI Customization

External Payment Methods

External payment methods allow you to offer additional payment options within the Klarna Checkout iframe that redirect customers to external payment providers. Configure these in the externalPaymentMethods array:

Example configuration:

{
  "externalPaymentMethods": [
    {
      "name": "Swish",
      "redirectUrl": "https://your-store.com/checkout/swish?orderId={orderId}",
      "imageUrl": "https://your-cdn.com/swish-logo.png",
      "description": "Pay instantly with Swish",
      "countries": ["SE"]
    }
  ]
}

Shipping Options (Klarna-Provided Shipping)

When providesShipping is enabled, you can configure static shipping options that appear within the Klarna Checkout iframe. Configure these in the shippingOptions array:

Example configuration:

{
  "shippingOptions": [
    {
      "id": "home-delivery",
      "name": "Home Delivery",
      "description": "Delivered to your door within 2-3 business days",
      "price": 4900,
      "taxAmount": 980,
      "taxRate": 2500,
      "preselected": true,
      "shippingMethod": "Home"
    },
    {
      "id": "pickup-point",
      "name": "Pickup Point",
      "price": 0,
      "taxAmount": 0,
      "taxRate": 2500,
      "shippingMethod": "PickUpPoint"
    }
  ]
}

Klarna API Environments

In addition to the generic Norce Adapter URLs (see Payment Adapters Overview), Klarna uses the following external API environments:

Creating a Payment

To create a Klarna Checkout order and receive the HTML snippet for embedding:

POST /api/checkout/v1/orders/{order_id}/payments
Host: {slug}.api-se.stage.norce.tech
x-merchant: {merchant}
x-channel: {channel}
Authorization: Bearer {token}

The response includes the Klarna Checkout HTML snippet:

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

Embed the htmlSnippet in your checkout page to display the Klarna Checkout iframe.

Creating a Recurring Payment

To create an order using a previously stored recurring token:

POST /api/checkout/v1/orders/{order_id}/payments/recurring
Host: {slug}.api-se.stage.norce.tech
x-merchant: {merchant}
x-channel: {channel}
Authorization: Bearer {token}
Content-Type: application/json

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

The autoCapture parameter determines whether the payment should be captured immediately:

• true: Payment is captured immediately (useful for digital goods)
• false: Payment is only authorized, requiring a separate capture request

If the token is valid and fraud_status is ACCEPTED, the order is completed immediately. If fraud status is not accepted, the order is marked as "Accepted" with a pending payment status.

Updating a Klarna Checkout Order

When the cart changes during checkout, update the Klarna order to reflect the new totals. First suspend the Klarna Checkout UI with JavaScript, then call the update endpoint:

PUT /api/checkout/v1/orders/{order_id}/payments/{payment_id}
Host: {slug}.api-se.stage.norce.tech
x-merchant: {merchant}
x-channel: {channel}
Authorization: Bearer {token}

After the update completes, resume the Klarna Checkout UI to display the new totals. See Klarna Checkout documentation for details on suspending and resuming the checkout.

Validation Callback

When the customer clicks "Place order" in the Klarna Checkout UI, a validation request is sent to the adapter. At this stage, the adapter updates the payment address so you can identify the customer. You can configure Norce Checkout to validate that all products are still available in stock and that all discounts are valid.

If validation succeeds, the adapter returns HTTP 200 and Klarna continues with confirming the payment. The Norce order transitions to the processing state and is locked from further changes except status updates.

If validation fails, the adapter returns HTTP 400 with a localized error message that Klarna displays to the customer in a popup. The customer is then redirected to the validationErrorUrl.

Confirmation Page

After payment is confirmed, Klarna redirects the customer to the confirmation callback endpoint, which then redirects to your configured confirmationUrl. On your confirmation page, retrieve the Klarna Checkout order to display the confirmation snippet:

GET /api/checkout/v1/orders/{order_id}/payments/{payment_id}
Host: {slug}.api-se.stage.norce.tech
x-merchant: {merchant}
x-channel: {channel}
Authorization: Bearer {token}

The response includes the confirmation snippet:

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

Troubleshooting (Klarna Specific)

In addition to the generic troubleshooting steps:

• Review the order status directly in Klarna's Merchant Portal.
• If Capture fails, verify the Norce order is in the reserved state and that the Klarna order status is AUTHORIZED.
• For validation failures, check that all products are still available and discounts are valid.
• Use the Klarna-specific refresh call to update available payment actions:

POST /api/order/v1/orders/{order_id}/payments/{payment_id}/refresh-kco
Host: {slug}.api-se.stage.norce.tech
x-merchant: {merchant}
x-channel: {channel}
Authorization: Bearer {token}

Links and References

• Klarna Checkout Adapter (Business Overview)
• Klarna Checkout Adapter OpenAPI Specification
• Migrate to Kustom Checkout
• Klarna Checkout Documentation (External)
• Klarna Order Management API (External)