Klarna Push Notifications
Version 1.0.0
AsyncAPI 2.6 description of Klarna's outbound HTTP push surface — the set of server-to-server callbacks that Klarna issues to merchant-hosted endpoints when payment, checkout, and order lifecycle events occur. Klarna does not ship a single unified webhook product. Instead, every push surface is activated by the merchant supplying a fully-qualified HTTPS URL on a `merchant_urls` (or equivalent) object during session/order creation. Klarna then issues an HTTP POST to that URL when the relevant event fires. The push surfaces modelled below are the ones publicly documented on docs.klarna.com: 1. Klarna Payments authorization callback - merchant_urls.authorization (Klarna Payments session) - Delivered after a customer authorizes a payment so the merchant can reliably obtain the authorization_token even if the browser round-trip fails. - Source: https://docs.klarna.com/payments/web-payments/integrate-with-klarna-payments/other-actions/authorization-callback/ 2. Hosted Payment Page (HPP) status_update callback - merchant_urls.status_update (HPP session) - Delivered whenever the HPP session transitions between IN_PROGRESS / COMPLETED / FAILED / BACK / CANCELLED / TIMEOUT. - Source: https://docs.klarna.com/payments/web-payments/integrate-with-klarna-payments/integrate-via-hpp/api-documentation/status-callbacks/ 3. Klarna Checkout (KCO) / Kustom Checkout push URL - merchant_urls.push (Checkout order) - Called when a checkout order is completed so the merchant can read the order from the Order Management API and acknowledge it. - Source: https://docs.klarna.com/order-management/manage-orders-with-the-api/view-and-change-orders/acknowledge-your-kco-orders/ - Source: https://docs.klarna.com/api/pages/checkout/ 4. Pending-order / fraud-decision notification URL - merchant_urls.notification (Klarna Payments / KCO) - Called when an asynchronously-evaluated order moves out of the PENDING state (fraud accepted, fraud rejected, or other final assessment). - Source: https://docs.klarna.com/payments/after-payments/order-management/more-actions/pending-orders/ Delivery semantics (documented): - Transport is HTTPS POST initiated by Klarna against the merchant URL. - Connection + read timeout is approximately 2 seconds each; the merchant should respond inside the documented retry window. - Non-2xx responses trigger up to 3 retries with exponentially increasing backoff starting at 1 second. - Delivery is at-least-once — successful 2xx responses may still be retried if Klarna fails to record receipt, so merchants must treat every push as idempotent. Authentication: - Klarna does not publish an HMAC signature header for these callbacks. - The documented practice is for merchants to embed a one-time secret token in the callback URL itself (as a query parameter) when they create the session/order, then verify it on receipt. That pattern is modelled in `components.securitySchemes.urlSecretToken` below.
Channels
Messages
Servers
{merchantBaseUrl}