Docs
Firmly Agentic Commerce
Docs
Set theme to dark (⇧+D)
  1. Docs
  2. API Reference
  3. ...
  4. ...
  5. Klarna
  6. Start

Start Klarna Checkout

POST https://api.firmly.work/api/v1/domains/{domain}/express/klarna/start

​​ Overview

Initiates a Klarna checkout by creating a payment session with Klarna. Returns the cart enriched with a payment_method object containing the client_token, session_id, and available payment_method_categories needed to render the Klarna Payments widget on the client.

Availability and the host this endpoint runs on are covered in the Klarna Express Checkout overview.

​​ Authentication

  • x-firmly-authorization (string, required) — Device access token from Browser Session

​​ Path Parameters

  • domain (string, required) — The merchant domain (e.g., “staging.luma.gift”)

​​ Prerequisites

Before calling this endpoint:

  • A cart must already exist for {domain} on this device session (created via Browser Session → Add Line Item) and hold at least one line item. A missing cart returns 404 CartNotFound.
  • Shipping info should be set (Set Shipping Info) so the cart total is accurate before the Klarna session is created; the authorize step requires the cart to be in a ready state.

​​ Request Body

  • attributes (object) — Optional gateway-specific attributes. Can be an empty object or omitted entirely for standard Klarna checkout.

​​ Response

Returns the cart enriched with the Klarna payment method details.

  • cart_id (string) — Unique identifier for the cart

  • line_items (array) — Array of items in the cart

  • payment_method (object) — Klarna payment method details

    Payment Method
    • payment_type (string) — Always "Klarna" for this gateway
    • attributes (object) — Klarna session credentials
    Attributes
    • session_id (string) — Klarna payment session identifier
    • client_token (string) — Token used to initialize the Klarna Payments SDK on the client
    • payment_method_categories (array) — Available Klarna payment options (e.g., pay_later, pay_over_time, pay_now). Each entry contains identifier, name, and asset_urls.

  • shipping_info (object) — Delivery address details

  • shipping_method (object) — Selected shipping method with pricing

  • total (object) — Grand total including all costs

  • sub_total (object) — Subtotal before shipping and tax

  • tax (object) — Tax amount

​​ Code Example 


const response = await fetch(
  'https://api.firmly.work/api/v1/domains/staging.luma.gift/express/klarna/start',
  {
    method: 'POST',
    headers: {
      'x-firmly-authorization': authToken,
      'Content-Type': 'application/json'
    },
    body: JSON.stringify({})
  }

);



const cart = await response.json();



// Extract Klarna credentials for the widget

const {
  session_id,
  client_token,
  payment_method_categories
} = cart.payment_method.attributes;



// Initialize Klarna Payments SDK with client_token
Klarna.Payments.init({ client_token });


import requests


response = requests.post(
    'https://api.firmly.work/api/v1/domains/staging.luma.gift/express/klarna/start',
    headers={
        'x-firmly-authorization': auth_token,
        'Content-Type': 'application/json'
    },
    json={}

)


cart = response.json()
klarna_attrs = cart['payment_method']['attributes']
session_id = klarna_attrs['session_id']
client_token = klarna_attrs['client_token']
categories = klarna_attrs['payment_method_categories']


curl -X POST https://api.firmly.work/api/v1/domains/staging.luma.gift/express/klarna/start \
  -H "x-firmly-authorization: YOUR_AUTH_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{}'

​​ Response Example 


{
  "cart_id": "9cf76530-1344-420f-9ca6-c7a96fb6db45",
  "line_items": [
    {
      "line_item_id": "3e66bef5-43f5-4a80-8957-91c5c8233163",
      "sku": "MT12",
      "quantity": 1,
      "description": "Cassius Sparring Tank",
      "price": {
        "currency": "USD",
        "value": 18,
        "number": 1800,
        "symbol": "$"
      },
      "line_price": {
        "currency": "USD",
        "value": 18,
        "number": 1800,
        "symbol": "$"
      },
      "msrp": {
        "currency": "USD",
        "value": 21.6,
        "number": 2160,
        "symbol": "$"
      },
      "image": {
        "url": "https://staging.luma.gift/cassius-sparring-tank.jpg",
        "alt": "Cassius Sparring Tank",
        "type": "default"
      }
    }
  ],
  "payment_method": {
    "payment_type": "Klarna",
    "attributes": {
      "session_id": "kp_abc123def456",
      "client_token": "eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9...",
      "payment_method_categories": [
        {
          "identifier": "pay_later",
          "name": "Pay later",
          "asset_urls": {
            "descriptive": "https://x.klarnacdn.net/payment-method/assets/badges/generic/klarna.svg",
            "standard": "https://x.klarnacdn.net/payment-method/assets/badges/generic/klarna.svg"
          }
        },
        {
          "identifier": "pay_over_time",
          "name": "Financing",
          "asset_urls": {
            "descriptive": "https://x.klarnacdn.net/payment-method/assets/badges/generic/klarna.svg",
            "standard": "https://x.klarnacdn.net/payment-method/assets/badges/generic/klarna.svg"
          }
        }
      ]
    }
  },
  "shipping_info": {
    "first_name": "John",
    "last_name": "Smith",
    "email": "john@example.com",
    "phone": "2065551212",
    "address1": "123 Main St",
    "city": "Seattle",
    "state_or_province": "WA",
    "country": "US",
    "postal_code": "98101"
  },
  "shipping_method": {
    "id": "standard_shipping",
    "description": "Standard Shipping",
    "price": {
      "currency": "USD",
      "value": 10,
      "number": 1000,
      "symbol": "$"
    }
  },
  "total": {
    "currency": "USD",
    "value": 32,
    "number": 3200,
    "symbol": "$"
  },
  "sub_total": {
    "currency": "USD",
    "value": 18,
    "number": 1800,
    "symbol": "$"
  },
  "shipping_total": {
    "currency": "USD",
    "value": 10,
    "number": 1000,
    "symbol": "$"
  },
  "tax": {
    "currency": "USD",
    "value": 2,
    "number": 200,
    "symbol": "$"
  },
  "fees": [
    {
      "description": "Recycle fee",
      "currency": "USD",
      "value": 2,
      "number": 200,
      "symbol": "$"
    }
  ],
  "fee_total": {
    "currency": "USD",
    "value": 2,
    "number": 200,
    "symbol": "$"
  }

}

​​ Error Responses

Errors return a JSON body with code, error, and description. Program against the error value — descriptions are human-readable and may change.

400 — ErrorStartExpressCheckout

Firmly could not create a Klarna payment session — either Klarna rejected the request or the merchant adapter failed to translate it.


{ "code": 400, "error": "ErrorStartExpressCheckout", "description": "Could not start checkout." }
400 — InvalidToken

The x-firmly-authorization header is missing, empty, or not a well-formed JWT. Device-auth can also surface as MissingAuthHeader or PartnerNotFound; see Authentication errors for the full set.


{ "code": 400, "error": "InvalidToken", "description": "Jwt token is invalid." }
401 — InvalidJWTToken

The device JWT is well-formed but its signature does not verify, or required claims are missing.


{ "code": 401, "error": "InvalidJWTToken", "description": "Jwt token is invalid." }
404 — CartNotFound

No active cart exists for this device on this domain.


{ "code": 404, "error": "CartNotFound", "description": "Cart was not found." }
404 — DomainNotFound

The {domain} path parameter does not match any merchant configured with Firmly, or the merchant has been disabled.


{ "code": 404, "error": "DomainNotFound", "description": "This domain was not found in firmly servers." }
404 — GatewayNotFound

Klarna is not enabled as a payment gateway for this merchant. Check payment_method_options before offering it.


{ "code": 404, "error": "GatewayNotFound", "description": "Payment gateway 'klarna' not found" }
412 — OperationNotSupported

The merchant adapter does not implement Klarna express checkout.


{ "code": 412, "error": "OperationNotSupported", "description": "This operation is not supported for this store." }
503 — StoreUnavailable

The merchant’s own API was unavailable or timed out. Retry with backoff.


{ "code": 503, "error": "StoreUnavailable", "description": "Store temporarily unavailable. Please try again later." }
429 — RateLimited

Too many requests from this device. Back off and retry after the Retry-After window — see Rate Limits.


{ "code": 429, "error": "RateLimited", "description": "Too many requests. Please try again later." }