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

# Start Klarna Checkout

> Creates a Klarna payment session and returns client credentials for the Klarna widget

## 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

<ParamField header="x-firmly-authorization" type="string" required>
  Device authentication token from Browser Session
</ParamField>

## Path Parameters

<ParamField path="domain" type="string" required>
  The merchant domain (e.g., "merchant.example.com")
</ParamField>

## Request Body

<ParamField body="attributes" type="object">
  Optional gateway-specific attributes. Can be an empty object or omitted entirely for standard Klarna checkout.
</ParamField>

## Response

Returns the cart enriched with the Klarna payment method details.

<ResponseField name="cart_id" type="string">
  Unique identifier for the cart
</ResponseField>

<ResponseField name="line_items" type="array">
  Array of items in the cart
</ResponseField>

<ResponseField name="payment_method" type="object">
  Klarna payment method details

  <Expandable title="Payment Method">
    <ResponseField name="payment_type" type="string">
      Always `"Klarna"` for this gateway
    </ResponseField>

    <ResponseField name="attributes" type="object">
      Klarna session credentials

      <Expandable title="Attributes">
        <ResponseField name="session_id" type="string">
          Klarna payment session identifier
        </ResponseField>

        <ResponseField name="client_token" type="string">
          Token used to initialize the Klarna Payments SDK on the client
        </ResponseField>

        <ResponseField name="payment_method_categories" type="array">
          Available Klarna payment options (e.g., `pay_later`, `pay_over_time`, `pay_now`). Each entry contains `identifier`, `name`, and `asset_urls`.
        </ResponseField>
      </Expandable>
    </ResponseField>
  </Expandable>
</ResponseField>

<ResponseField name="shipping_info" type="object">
  Delivery address details
</ResponseField>

<ResponseField name="shipping_method" type="object">
  Selected shipping method with pricing
</ResponseField>

<ResponseField name="total" type="object">
  Grand total including all costs
</ResponseField>

<ResponseField name="sub_total" type="object">
  Subtotal before shipping and tax
</ResponseField>

<ResponseField name="tax" type="object">
  Tax amount
</ResponseField>

## Code Example

<CodeGroup>
  ```javascript JavaScript theme={null}
  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 });
  ```

  ```python Python theme={null}
  import requests

  response = requests.post(
      'https://cc.firmly.work/api/v1/domains/merchant.example.com/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']
  ```

  ```bash cURL theme={null}
  curl -X POST https://cc.firmly.work/api/v1/domains/merchant.example.com/express/klarna/start \
    -H "x-firmly-authorization: YOUR_AUTH_TOKEN" \
    -H "Content-Type: application/json" \
    -d '{}'
  ```
</CodeGroup>

## Response Example

```json theme={null}
{
  "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

| Code                         | Description                              |
| ---------------------------- | ---------------------------------------- |
| `ErrorCartNotFound`          | No active cart for this domain           |
| `ErrorGatewayNotFound`       | Klarna is not enabled for this merchant  |
| `ErrorOperationNotSupported` | Merchant adapter does not support Klarna |
| `ErrorStartExpressCheckout`  | Failed to create Klarna payment session  |
| `ErrorStoreUnavailable`      | Merchant temporarily unavailable         |

## Related Endpoints

* [Authorize Klarna Checkout](/api-reference/payment/express-checkout/authorize-klarna) - Confirm Klarna authorization
* [Complete Klarna Order](/api-reference/payment/express-checkout/complete-order-klarna) - Finalize the order