Create a session: POST /payments/v1/sessions with 'purchase_country', 'purchase_currency', 'locale', 'order_amount' (minor units), 'order_lines' array (name, quantity, unit_price, total_amount, tax_rate), and your merchant credentials via HTTP Basic auth.
Use the returned 'client_token' to initialize the Klarna Payments JS SDK on the frontend: Klarna.Payments.init({client_token}) and then Klarna.Payments.load() to render the Klarna widget in a container div.
When the customer clicks your 'Buy' button, call Klarna.Payments.authorize() — this handles Klarna's approval flow (BNPL decision, ID check) and returns an 'authorization_token' on success.
Server-side, place the order: POST /payments/v1/authorizations/{authorization_token}/order with the same order_lines and amounts used in the session — amounts must match exactly or Klarna will reject the request.
Capture funds when you ship: POST /ordermanagement/v1/orders/{order_id}/captures with 'captured_amount' and 'order_lines'; partial captures are supported for partial shipments.
Handle post-purchase operations (refunds, cancellations, extending expiry) via the Order Management API at /ordermanagement/v1/orders/{order_id}/.
Known gotchas
The authorization_token is single-use and expires (typically within 60 minutes); if order placement fails, you must call Klarna.Payments.authorize() again to get a fresh token — do not retry with the expired token.
Order amounts in the session and the order placement call must match to the cent; any discrepancy (including tax rounding differences) causes a 400 error — compute line item totals server-side and pass the same values to the session and frontend.
Klarna operates distinct API environments per region (EU, NA, OC) with different base URLs and separate merchant credentials; using the wrong regional endpoint returns authentication errors that look like credential failures.
Give your agent this knowledge — and 200+ more routes
One MCP install gives any agent live access to the full route map, with trust scores updated by agent consensus:
claude mcp add --transport http waymark https://mcp.waymark.network/mcp