Magento module reference

This is the reference half of the Magento integration, for developers who are extending the modules rather than installing them. It maps the module tree, lists every configuration path, documents the klarna_ tables and the callback routes, and names the supported extension points. For installation, configuration through the admin and troubleshooting, see Magento and Adobe Commerce.

Why the code says Klarna and the packages say Kustom

The integration was built as Klarna’s Magento module and renamed. Both names are live, in fixed places:

What	Naming
Composer packages	kustom/module-*
PHP namespaces	Klarna\*
Database tables	klarna_*
Configuration paths	klarna/*, payment/klarna_*, checkout/klarna_*
Log file	var/log/klarna.log

This is backward compatibility, not a mistake, and it’s why bin/magento module:status | grep Klarna is the command that lists Kustom modules. Don’t “fix” a namespace or a table name.

The module tree

Installing kustom/module-checkout pulls everything required, in order. The chain is:

Base                       kustom/module-base
├─ Logger                  kustom/module-logger
├─ AdminSettings           kustom/module-admin-settings
└─ Orderlines              kustom/module-orderlines
    ├─ KCO                 kustom/module-kco
    │   └─ KSS             kustom/module-kss
    ├─ KP                  kustom/module-payments
    │   └─ KpGraphQl       kustom/module-payments-graph-ql
    └─ Backend             kustom/module-backend

Optional: KEC (kustom/module-kec), SIWK (kustom/module-siwk), OSM (kustom/module-osm)

Base owns all HTTP communication with Kustom, authentication, environment selection and store-scoped configuration retrieval. Every other module goes through it.

Logger records every API request, response and callback payload, to the klarna_logs table and to var/log/klarna.log. Two cron jobs maintain it: klarna_core_clean_logs daily at midnight, and klarna_core_update_api_log every minute.

Orderlines translates Magento’s totals into Kustom line items — products, shipping, discounts, tax, bundles, gift cards — in minor units, and regenerates them whenever the cart changes. Most integration failures are orderlines failures, so this is the module to understand first.

KCO (payment/klarna_kco) replaces the Magento checkout with the Kustom iframe and responds to Kustom’s callbacks. KSS supplies Magento’s shipping methods into that iframe. Backend is order management: an invoice in Magento becomes a capture at Kustom, a credit memo becomes a refund, a cancellation becomes a cancellation. It only sends — a capture or refund made in the Kustom Merchant Portal is never reported back to Magento, which is why mirroring Portal actions has its own troubleshooting entry.

KP (payment/klarna_kp) is Klarna Payments as an ordinary Magento payment method, with pay_now, pay_later and pay_over_time categories.

Modules being phased out

Three capabilities still ship and still work, but are scheduled for removal as Kustom moves to a vendor-independent checkout. Don’t build new work on them:

• Klarna Payments (KP) — legacy single-payment-method support. Use KCO instead.
• Sign-In-With-Klarna (SIWK) — OAuth identity and address prefill, tables klarna_siwk_token and klarna_siwk_customer.
• On-Site Messaging (OSM) — promotional payment widgets on product, cart, category and checkout pages.

Note the asymmetry this creates: the KP modules are deprecated, but klarna_kp remains a valid payment method code and the GraphQL mutations below still carry Klarna names.

Configuration paths

All paths are store-scoped unless stated otherwise. Password fields are encrypted by Magento at rest.

API

klarna/api/
  debug     boolean, default 0   Enable debug logging
  region    checkbox: au, ca, eu, mx, nz, us

Leaving klarna/api/debug on in production is the single most common cause of an out-of-control klarna_logs table. Turn it on to investigate, then turn it off when you’re done.

Region credentials

Replace {region} with au, ca, eu, mx, nz or us.

klarna/api_{region}/
  api_mode                          select: 0 = production, 1 = playground
  username_production               string, required
  password_production               encrypted, required
  client_identifier_production      string, optional
  username_playground               string
  password_playground               encrypted
  client_identifier_playground      string

Payment methods

payment/klarna_kco/
  active                  boolean
  order_status            select    Initial order status after placement
  shipping_countries      multiselect
  billing_countries       multiselect
  disable_customer_group  multiselect   Customer groups excluded from KCO

payment/klarna_kp/
  active        boolean
  enable_b2b    boolean
  sort_order    integer
  title         string

payment/klarna_kss/
  enabled       boolean   Dynamic shipping options inside the KCO iframe

payment/kec/
  enabled       boolean
  position      select    product, cart, checkout
  theme, shape            Express button styling

Checkout behavior

checkout/klarna_kco/
  terms_url            text, REQUIRED — checkout fails to initialize without it
  guest_checkout       boolean
  enable_b2b           boolean
  auto_focus           boolean   Focus the first field in the iframe
  merchant_prefill     boolean   Pre-fill known customer data
  shipping_in_iframe   boolean
  phone_mandatory      boolean
  dob_mandatory        boolean

Iframe design

checkout/klarna_kco_design/
  color_button, color_button_text, color_checkbox, color_header, color_link   hex
  radius_border                                                              pixels

Shipping dimensions and messaging

klarna/shipping/
  product_unit   select: cm or inch
  length, width, height   product attributes carrying the dimensions

klarna/osm/
  enabled, theme, position

Reading configuration in code

use Magento\Framework\App\Config\ScopeConfigInterface;
use Magento\Store\Model\ScopeInterface;

$username = $this->scopeConfig->getValue(
    'klarna/api_eu/username_production',
    ScopeInterface::SCOPE_STORE,
    $storeId
);

$debug = $this->scopeConfig->isSetFlag('klarna/api/debug', ScopeInterface::SCOPE_STORE, $storeId);

Encrypted values: every password_production and password_playground, plus klarna/api/merchant_id and klarna/api/shared_secret.

Settings that should differ per environment: klarna/api_{region}/api_mode, klarna/api/debug and checkout/klarna_kco/terms_url.

KCO callback routes

Four of these are server-to-server callbacks and must be publicly reachable. The fifth, confirmation, is where the customer’s browser is redirected — a 30x or a session-gated response is normal there. Maintenance mode makes all of them return 503, which breaks the checkout outright.

address_update, shipping_option_update and push answer 200. Validation is the exception: it approves with a 2xx and rejects with a 3xx carrying a Location header, so a handler that returns 200 to block a purchase lets it through instead.

Callback	Route	Fires when	Does
address_update	/kco/api/addressupdate	Customer changes address	Recalculates orderlines and tax
shipping_option_update	/kco/api/shippingmethodupdate	Customer picks a shipping option	Recalculates orderlines with the shipping cost
validate	/kco/api/validate	Just before Kustom authorizes	Final validation, which can reject the purchase
push	/kco/api/push	After authorization	Creates or updates the Magento order
confirmation	/kco/klarna/confirmation	Success redirect	Renders the confirmation page

Database tables

Every table uses the klarna_ prefix and hangs off a Magento core table with cascade delete.

klarna_core_order

The mapping between a Magento order and a Kustom order. Created by Base, read by everything else. Schema at vendor/kustom/module-base/etc/db_schema.xml.

Column	Meaning
klarna_order_id	Kustom’s order identifier
session_id	Checkout session ID
reservation_id	Payment reservation, used for Order Management API calls
order_id	FK to sales_order.entity_id, cascade delete
is_acknowledged	Whether the order has been acknowledged to Kustom
is_b2b	Business purchase flag

Indexed on klarna_order_id, order_id, is_acknowledged. More than one row for a single klarna_order_id means the push callback fired more than once.

klarna_logs

Every API request and response, and every callback payload. Created by Logger. Schema at vendor/kustom/module-logger/etc/db_schema.xml.

Column	Meaning
status	HTTP status of the response
action	create_order, update_order, push, capture, …
klarna_id	Kustom order ID
increment_id	Magento order increment ID
url, method	Endpoint and HTTP verb
service	KCO, KP or OM
request, response	Full JSON payloads

Indexed on action, klarna_id, increment_id, status, plus a composite index.

klarna_kco_quote

Links a Magento quote to a KCO order. Created by KCO. Columns: klarna_checkout_id, quote_id (FK to quote.entity_id), is_active, is_changed — the last flagging that the cart moved since the last update pushed to Kustom.

klarna_payments_quote

KP session state per quote. Created by KP. Columns: session_id, client_token, authorization_token, quote_id, is_active, is_kec_session, payment_methods (JSON). Cleaned weekly by klarna_payments_quote_clean_old_entries.

klarna_shipping_method_gateway

KSS shipping options against a checkout session. Created by KSS. Columns: klarna_session_id, shipping_method_id (a Magento code such as flatrate_flatrate), is_pick_up_point, shipping_amount, tax_amount, delivery_details (JSON).

Cleanup

klarna_logs is pruned daily by klarna_core_clean_logs. klarna_payments_quote is pruned weekly by klarna_payments_quote_clean_old_entries. If cron hasn’t been running, both grow without bound and you’ll need to delete by created_at manually.

Extension points

Five supported ways to change behavior, in rough order of how often they are the right answer. All of them are Magento dependency injection — a di.xml in your own module — rather than edits to the Kustom modules.

Orderlines customization. Add line items Magento’s totals don’t produce — payment or handling fees, packaging charges, environmental levies, membership discounts, custom discounts. This is where fees belong. Adding them anywhere else desynchronizes the total and produces the “order total mismatch” 400. Implement Klarna\Orderlines\Api\OrderLineInterface — collectPrePurchase() reads the quote, collectPostPurchase() the order, and fetch() adds your lines — and register the class as an item of the entities argument on Klarna\Orderlines\Model\Container\Parameter, beside the module’s own items, shipping, discount, tax and surcharge handlers.

Session builder plugins. Magento interceptors on Klarna\Kco\Model\Api\Builder\Kasper, which builds the KCO session. An after plugin on generateCreateRequest(), generateUpdateRequest() or generatePlaceOrderRequest() changes the body of that call. Use them to attach ERP order references, internal tracking IDs, customer segment data or analytics metadata before the session is sent.

Validation checks. The validate callback runs a list of checks before the purchase completes: the validations argument on Klarna\Kco\Model\Cart\Validations\Handler, which ships with shipping amount, shipping method, order total and order items. Add your own — inventory, credit limits, fraud scoring, shipping restrictions, business hours — by implementing Klarna\Kco\Api\CheckoutValidationInterface and adding it to that array. Throwing a Klarna\Base\Exception from validate() rejects the purchase, and the callback sends the customer back with a 303.

Event observers. The KCO module dispatches only a few events of its own: kco_override_load_checkout, whose override_object decides whether the Kustom checkout loads (force_enabled, force_disabled, redirect_url); checkout_kco_controller_success_action on the confirmation page, next to Magento’s own checkout_onepage_controller_success_action, both carrying order_ids; and, for each merchant checkbox, kco_<checkbox id>_save with its checked state, the quote and the order. Anything else in the order lifecycle is Magento’s own events.

Gateway commands. Capture, refund and cancel are Magento payment gateway commands. For custom payment operations, override or add commands in the command pools: the virtual types KcoCommandPool for Kustom Checkout and KPCommandPool for Kustom Payments.

GraphQL and REST

The KP GraphQL module exposes mutations for creating a Klarna Payments session and setting the Klarna payment method on a cart. Guest carts need no authentication beyond the cart_id returned by createEmptyCart. Customer carts take a customer token in the GraphQL headers. Note that these mutations carry the Klarna name, and that KP itself is deprecated — new work should use KCO.

KSS exposes a REST endpoint for shipping options, authenticated with an integration token created under System → Extensions → Integrations. Don’t use an admin token for anything but a throwaway test.

The KP widget script is loaded from https://x.klarna.com/kp/lib/v1/api.js, and the widget needs x.klarna.com and x.klarnacdn.net allowed in your Content Security Policy. Those are the live hosts for the deprecated KP flow, not leftovers — but if you’re on KCO you don’t need them.

Related

• Magento and Adobe Commerce — install it, configure it and fix it when it breaks
• Create the order — the API shape the Orderlines module is building
• Shipping Assistant — the service KSS talks to
• Order management — what the Backend module is synchronizing with
• Open source platform responsibility — what you own once you extend the modules