# Magento module reference

Reference for the Kustom Checkout modules on Adobe Commerce and Magento: module map, config paths, klarna_ tables, KCO callback routes and extension points.

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](/partners/magento/).

## 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](/partners/magento/#an-order-handled-in-the-kustom-portal-still-looks-open-in-magento)
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

```php
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](/partners/magento/) — install it, configure it and fix it when it breaks
- [Create the order](/checkout/integrate/create-order/) — the API shape the Orderlines module is building
- [Shipping Assistant](/checkout/shipping/#shipping-assistant) — the service KSS talks to
- [Order management](/order-management/) — what the Backend module is synchronizing with
- [Open source platform responsibility](/partners/open-source-responsibility/) — what you own once you extend the modules