Klarna Docs - Monitor the status

Monitor the status

Learn how to monitor the distribution status of an in-store payment.

To monitor the distribution status, you have to get the distribution result from Klarna. You can do so in one of two ways:

We recommend subscribing to a webhook as polling may cause reaching Klarna API's rate limits.

If you have provided a URL endpoint when initiating the payment session, you'll get the distribution status updates via a webhook notification instead of having to poll the server for status updates.

The URL provided as the status_update parameter must use HTTPS, but to be able to authenticate that the notification comes from Klarna, we recommend you generate a one-time token that you'll only use for this specific In-store payment session.

JSON
    "distribution": {
        "method": "one_qr",
        "callback_urls": {
         "status_update": "https://example.com/statsCallbackEndpoint?klarnaId={generic_id}&secretToken={token}"
        }
   }

{generic_id} is an id that is generated by your system which you can use to correlate the payment session when you receive a callback.

For extra security, when you get a webhook notification and the distribution status is COMPLETED, send a GET request to the distribution result endpoint. This lets you validate if the notification of the status update was sent by Klarna.

The webhook sends the distribution result payload for the following distribution status changes:

Distribution statusDescriptionAction to take
DISTRIBUTEDThe payment link has been distributed.Use the link from the distribution result endpoint and display the QR code to the customer.
ACCESSEDThe customer has accessed the payment link.No action.
COMPLETEDThe customer has completed the payment and a new order has been automatically placed.Get the order id from the distribution result endpoint or webhook.
CANCELEDThe payment session has been canceled by either partner or consumer.No action.
FAILEDThere was a failure in distribution or connecting the customer for various reasons.Read the error code sent in response. Based on the error, either create a new session or retry distribution using retry endpoint. If there was failure in short code use QR code URL or payment link URL as fallback

To get the distribution result from Klarna, send an empty request body to the result endpoint.
Link to result endpoint is included in distribution.result_url field in session initiation response.

Success response

In response to your request, you'll receive the distribution status, a QR code image URL, and a payment link URL.

If a short code was provided, the customer is automatically redirected to complete the payment. Continue monitoring the status.

If you don't want to provide a short code, you can either remove the property completely or send a null value instead.

ParameterTypeDescription
statusstringThe distribution status of the payment. Depending on the distribution status, you can take some additional actions.
qrstringThe URL that contains the QR code and the QR code has a payment link embedded. You can display this QR code to customers to scan and pay.
payment_linkstringThe payment link URL. You can distribute the link by encoding it as a QR code or by sending it in an SMS.

The distribution statuses change when an action is performed either by you, the customer, or by the system.

The distribution statuses in an ongoing In-store session.

Below is a list of all possible distribution statuses, along with actions you can take for each.

Distribution statusDescriptionAction to take
WAITINGThe payment link has not been distributed yet.Try to distribute the payment again if enough time has passed since the last attempt, for example, after 2 minutes.
DISTRIBUTEDThe payment link has been distributed.Use the link from the distribution result endpoint and display the QR code to the customer.
ACCESSEDThe customer has accessed the payment link.No action.
COMPLETEDThe customer has completed the payment and a new order has been automatically placed.Get the order id from the distribution result endpoint or webhook.
CANCELEDThe payment session has been canceled by either partner or consumer.No action.
FAILEDThere was a failure in distribution or connecting the customer for various reasons. Read the error code sent in response. Based on the error, either create a new session or retry distribution using retry endpoint. If there was failure in shortcode use QR code URL or payment link URL as fallback
JSON
{
  "status": "FAILED",
  "retry_url": "https://api.klarna.com/iss/v1/distributions/{session_id}/retry",
  "qr": "https://pay.klarna.com/{region}/iss/v1/distributions/{session_id}/qr/{token}",
  "payment_link": "https://pay.klarna.com/{region}/hpp/payments/{token}",
  "error": {
    "code": "CONSUMER_SESSION_NOT_FOUND",
    "retryable": true
  }
}
Failure error code  SignificanceExpected action
CONSUMER_SESSION_NOT_FOUNDA valid customer session with a provided short code couldn't be found. Hence, the session can't be distributed.
  • Retry by entering the correct short code using either create session api or retry api.  
  • Ask the customer to verify if the short code has expired and to re-scan the QR code or generate a new QR code.
UNKNOWNSystem errorThe session failed due to an internal server error. You may retry by creating a new session. If errors persist, contact Klarna merchant support.

Once the payment is completed, a new order gets created in Klarna's systems.
A message is displayed to the customer informing them that the payment is done. The module page displays the payment status.

The new order is automatically placed and captured. You can retrieve the order identifier from the distribution result URL specified when creating the payment session.

If you've provided the distribution webhook URL as the callback_url parameter, you'll get the order identifier via a webhook notification.

JSON
  {
    "status": "COMPLETED" 
    "order_id": "588314f6-dd10-11ed-afa1-0242ac120002",
    "klarna_reference": "XDC23412"
  }

The order identifier (order_id) is returned to the distribution result endpoint URL and the webhook URL.

If a payment error occurs, you may retry the process by first canceling the existing payment session and initiating a new payment.

If the session response is FAILED and retryable is set to true , try redistributing the session.

JSON
 "distribution": {
       "method": "one_qr",
       "short_code": "4212",
       "callback_urls": {
         "status_update": "https://example.com/callback"
        }
   }