Authorize Klarna Checkout

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

​​ Overview

After the buyer authorizes payment in the Klarna widget (client-side), this endpoint confirms the authorization with Firmly. It stores the authorization_token in the session and returns the cart with the confirmed Klarna payment method.

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”)

​​ Request Body

• attributes (object, required) — Klarna authorization details
  Attributes

  • authorization_token (string, required) — The authorization token received from the Klarna Payments SDK after the buyer approves payment. Obtained from the Klarna.Payments.authorize() callback.

​​ Response

Returns the cart with the confirmed Klarna payment method.

• cart_id (string) — Unique identifier for the cart

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

• payment_method (object) — Confirmed Klarna payment method

  Payment Method

  • payment_type (string) — Always "Klarna" for this gateway
  • attributes (object) — Klarna authorization details

  Attributes

  • session_id (string) — Klarna payment session identifier (from start checkout)
  • authorization_token (string) — The confirmed authorization token

• shipping_info (object) — Delivery address details

• total (object) — Grand total including all costs

• sub_total (object) — Subtotal before shipping and tax

• shipping_total (object) — Shipping cost

• tax (object) — Tax amount

​​ Code Example

// After Klarna.Payments.authorize() callback returns authorization_token
const response = await fetch(
  'https://api.firmly.work/api/v1/domains/staging.luma.gift/express/klarna/authorize',
  {
    method: 'POST',
    headers: {
      'x-firmly-authorization': authToken,
      'Content-Type': 'application/json'
    },
    body: JSON.stringify({
      attributes: {
        authorization_token: 'klarna_auth_token_from_widget'
      }
    })
  }
);

const cart = await response.json();
// Payment is now authorized, proceed to complete order

import requests

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

cart = response.json()

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

​​ 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",
      "authorization_token": "klarna_auth_token_from_widget"
    }
  },
  "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"
  },
  "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": "$"
  }
}

​​ Related Endpoints

• Start Klarna Checkout — Create Klarna session first
• Complete Klarna Order — Finalize the order

​​ Error Responses

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

{ "code": 400, "error": "BadRequest", "description": "Missing Klarna authorization_token" }

{ "code": 400, "error": "ErrorSubmitExpressCheckout", "description": "Could not submit checkout." }

{ "code": 412, "error": "PreconditionError", "description": "A precondition was not completed." }

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

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

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

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

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

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

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

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