Skip to main content
POST
/
api
/
v1
/
domains
/
{domain}
/
express
/
klarna
/
start
Start Klarna Checkout
curl --request POST \
  --url https://cc.firmly.work/api/v1/domains/{domain}/express/klarna/start \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --header 'x-firmly-authorization: <x-firmly-authorization>' \
  --data '
{
  "attributes": {}
}
'
{
  "cart_id": "<string>",
  "line_items": [
    {}
  ],
  "payment_method": {
    "payment_type": "<string>",
    "attributes": {
      "session_id": "<string>",
      "client_token": "<string>",
      "payment_method_categories": [
        {}
      ]
    }
  },
  "shipping_info": {},
  "shipping_method": {},
  "total": {},
  "sub_total": {},
  "tax": {}
}

Documentation Index

Fetch the complete documentation index at: https://developers.firmly.ai/llms.txt

Use this file to discover all available pages before exploring further.

​
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.

​
Authentication

​
x-firmly-authorization
string
required
Device authentication token from Browser Session

​
Path Parameters

​
domain
string
required
The merchant domain (e.g., “merchant.example.com”)

​
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
​
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://cc.firmly.work/api/v1/domains/merchant.example.com/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 });

​
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": "$"
      }
    }
  ],
  "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": 30,
    "number": 3000,
    "symbol": "$"
  },
  "sub_total": {
    "currency": "USD",
    "value": 18,
    "number": 1800,
    "symbol": "$"
  },
  "tax": {
    "currency": "USD",
    "value": 2,
    "number": 200,
    "symbol": "$"
  }
}

​
Error Responses

CodeDescription
ErrorCartNotFoundNo active cart for this domain
ErrorGatewayNotFoundKlarna is not enabled for this merchant
ErrorOperationNotSupportedMerchant adapter does not support Klarna
ErrorStartExpressCheckoutFailed to create Klarna payment session
ErrorStoreUnavailableMerchant temporarily unavailable