Authorization callback

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.

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.

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

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

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

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:

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

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

Since Klarna will notify via the authorization callback that the authorization was approved and you may have also received the notification via the front end response, you should avoid creating duplicate orders on your side. By ensuring idempotence, you will be able to prevent unintended side effects and maintain consistency in order processing.

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.

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 successfully received and processed the callback.

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.

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.

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

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.

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.