Activating callbacks

To ensure optimization of the conversion rates, you should get an authorization token through a server-side callback.

9 min read

When Klarna approves a customer, you receive an authorization token that lets you place an order. While you would typically receive authorization_token as a response to the authorize() call, you are required to implement the server-side callback to a specific URL to receive the authorization_token and session_id in the backend.

By using server-side authorization callback, you can create an order in case of any client-side communication issues.

Payment methods that require complex customer interactions, for example switching between banking apps, are vulnerable to front-end communication issues. If communication breaks down, a valid authorization_token issued by Klarna payments may not reach the client, making placing an order impossible.

This can lead to the customer being charged without the payment getting registered in your checkout. Such errors can affect your store's conversion rates if the customer believes they have completed an order but don't receive a confirmation from your side.

sequenceDiagram autonumber participant C as Consumer participant M as Merchant participant KAPI as Klarna API participant KJS as Klarna.js C->>M:Nagivate to checkout page M->>KAPI: Create Klarna Payment session Note over M, KAPI: Sending "authorization" - Callback URL "merchant_urls": {"authorization": "https://..."} KAPI->>M: Klarna payment session response M->>KJS: Initialize klarna.js M ->> KJS: Load the container C->>M: Select Klarna in Payment selector and clicks 'Pay' M->>KJS: Execute Authorize call alt Authorization Callback KJS->>M: Provide authorization token via Callback URL (valid for 60 minutes) Note over M, KAPI: { "authorization_token": "1eddf502-f3a0-45bf-b1fd-f2e3a2758200", "session_id": "e4b81ca2-----" } end M->>KAPI: Create Order POST {apiUrl}/payments/v1/authorizations/{authorizationToken}/order KAPI->>M: Provide order_id and redirect_url

The diagram above shows the end-to-end flow. Creating the order is a separate step that happens after you acknowledge the callback, not while Klarna is waiting for your response — see Acknowledge the callback before creating the order.

When initiating a payment, include a URL in the authorization field of the merchant_urls object. Klarna payments calls this URL after a successful authorization.

JSON

1 2 3 4 5 6 7 8 9

 ….
    "merchant_urls": {
        "confirmation": "https://...",
        "notification": "https://...",
        "push": "https://..."
        "authorization": "https://..."
    },
    ...

A sample merchant_urls object in the create_session request including the URL for receiving the callback in the authorization field.

Klarna will invoke the URL provided in the authorization field once the session is authorized.

JSON

1 2 3 4 5

{
  "authorization_token": "1eddf502-f3a0-45bf-b1fd-f2e3a2758200",
  "session_id": "e4b81ca2-0aae-4c16-bcb2-29a0a088a35b"
}

A sample callback request from Klarna.

Acknowledge the callback before creating the order

The callback delivers the authorization_token to your backend. It is not a request to create the order while Klarna waits on the connection. Handle it in this order:

1.
Persist the payload durably. Write the authorization_token and session_id to a database row, a queue message, or a durable log entry that survives a restart of your application.
2.
Return a 2xx response immediately. A 204 with an empty body is enough.
3.
Create the order asynchronously. Read the stored token from a background worker, a queue consumer, or a scheduled job, outside the request and response cycle of the callback.

Integration requirement

Store the callback payload and respond with a 2xx status code before you create the order. The authorization_token is valid for 60 minutes, so there is nothing to gain from creating the order while Klarna's connection is still open.

sequenceDiagram autonumber participant KAPI as Klarna API participant M as Merchant callback endpoint participant DB as Merchant storage participant W as Merchant async worker KAPI->>M: POST authorization callback {authorization_token, session_id} M->>DB: Store authorization_token and session_id DB-->>M: Write confirmed M-->>KAPI: 204 No Content Note over KAPI, M: Acknowledgment sent well inside the 2-second timeout W->>DB: Read stored authorization_token W->>KAPI: Create Order POST {apiUrl}/payments/v1/authorizations/{authorizationToken}/order KAPI-->>W: Provide order_id and redirect_url

What goes wrong when the order is created inside the handler

If your callback handler calls the order creation API and only then returns a status code, your response time becomes your order creation time. Order creation routinely takes longer than the 2-second read timeout, so Klarna never sees the response.

From Klarna's side, the delivery has failed, so Klarna retries a callback you have in fact already handled successfully. Two things follow:

Duplicate order attempts. Any system that isn't fully idempotent creates the order more than once for the same session.
Misleading monitoring. Your callback failure rate tracks your own handler latency instead of real delivery problems, which hides the failures you actually need to see.

What the 2-second budget covers

The 2-second connection timeout and the 2-second read timeout apply to the whole exchange, including the TLS handshake — not just to the time your application code spends on the request. Anything slow or dependent on a third party has to run after you've responded.

Keep all of the following out of the callback handler:

Order creation
Fraud checks
Inventory reservation
Synchronous calls to third-party services
Email or notification sending

Treat the handler as a write to durable storage followed by a response, and nothing else. The list below summarizes the pattern.

Do	Don't
Return a 2xx response as soon as the authorization token and session ID are stored.	Return a 2xx response only once the order creation call to Klarna has completed.
Create the order from a background worker after the callback has been acknowledged.	Create the order inside the callback handler while Klarna waits for the response.
Return 2xx again for a callback covering a session you have already handled.	Return 409 Conflict for a duplicate callback, which re-triggers Klarna's retries.
Keep fraud checks, inventory reservation, and notification emails outside the handler.	Run fraud checks, inventory reservation, or email sending before responding.

Securing the callbacks

You must provide the callback URL over HTTPS. To be able to authenticate that Klarna sent the callback, we recommend that you generate a one-time token only for this specific payment session.

This lets you authenticate Klarna as the origin of the call made to you after a successful authorization.

Additionally, you can include a secret token in the authorization URL to further enhance security:

JSON

1 2 3 4 5 6

{
    "merchant_urls": {
        "authorization": "https://example.com/authCallbackEndpoint&secretToken=b37cda64-a6d8-11ec-b909-0242ac120002"
    }
}

The value b37cda64-a6d8-11ec-b909-0242ac120002 passed in the request can be generated by the integrator for every new session.

By including this secret token, you can verify the authenticity of the callback request and ensure that it originates from Klarna.

Merchant idempotence

Integration requirement

The authorization callback is delivered with at-least-once semantics.This means your system may receive the same authorization notification multiple times, even if it previously returned a 2xx response. You must implement idempotent handling to avoid duplicate order creation.

Returning a 2xx response reduces retries but does not guarantee that Klarna successfully received your response. Network issues, timeouts, or connection interruptions may cause Klarna to deliver the same callback again after your system has already processed it.

You may receive the same authorization multiple times due to:

1.
Retry mechanism -- Klarna retries when a non-2xx response is received or a timeout occurs.
2.
Uncertain delivery outcomes -- even if your system returns 2xx, Klarna may retry if the response was not successfully received on our end.
3.
Multiple notification channels -- the same authorization may be delivered via both the server-side callback and the frontend authorize() response.

Best effort callback delivery

Klarna strives to consistently trigger the merchant authorization URL as effectively as possible. However, it's crucial to understand that delivery cannot be guaranteed 100% of the time. This uncertainty stems from various risks associated with the process of communication.

Even with Klarna's commitment to the reliable transmission of callback requests, issues like network disruptions, server downtime, or other unexpected events can affect the successful receipt of callbacks. Therefore, merchants should be ready to manage the occasional failures or delays in receiving authorization callbacks.

In the event of such failures, merchants have the option to use the Read Session API operation to access the most current session status. This approach helps merchants keep track of transaction statuses and ensure a smooth payment experience for the final customer.

Additional information

Successful callback response

Any status code response of the 2xx family (for example, 204) from your server to Klarna's callback is considered successful. This indicates to Klarna that your server has received the callback payload and stored it durably. It does not indicate that the order has been created — Klarna expects order creation to happen after you have responded.

Request timeout

Klarna's callback to your server includes a 2-second timeout: this consists of a 2-second connection timeout and a 2-second read timeout. It's crucial that your server is configured to handle the request within this period to prevent timeout errors.

Retry mechanism for non-2xx responses

If your server returns a response outside the 2xx status code range (for example, 4xx, 5xx), Klarna will initiate a retry mechanism. Klarna will make up to 3 attempts in total , with the delay between retries increasing exponentially, starting at 1 second. This means that failing to respond with a 2xx status code will lead to Klarna attempting the callback again at longer intervals.

Handling multiple callbacks

For responses other than 2xx, Klarna may send the same callback multiple times. Your system must be prepared to handle idempotent operations, ensuring that the same callback does not result in duplicate actions, such as creating the same order multiple times. See more info

Always return a 2xx response to a repeated callback, including one for a session you have already handled. Rejecting it with a 4xx status code such as 409 Conflict tells Klarna the delivery failed, which re-triggers the retry mechanism and produces more duplicate deliveries rather than fewer.

Multiple authorization processes

In instances where an order is not placed following a callback, the customer might be required to undergo another authorization process. Klarna may send a new callback with a different authorization_token in such cases. Your system should be adaptable to manage these situations effectively.

No authentication on callback URL

Do not implement any form of authentication for the callback URL you provide to Klarna. This will ensure Klarna can seamlessly call your system without the need for credential exchange.

Jump to section...