Getting the distribution status from a webhook

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.

Securing the webhooks

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

1 2 3 4 5 6 7

    "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 status	Description	Action to take
`DISTRIBUTED`	The payment link has been distributed.	Use the link from the distribution result endpoint and display the QR code to the customer.
`ACCESSED`	The customer has accessed the payment link.	No action.
`COMPLETED`	The customer has completed the payment and a new order has been automatically placed.	Get the order id from the distribution result endpoint or webhook.
`CANCELED`	The payment session has been canceled by either partner or consumer.	No action.
`FAILED`	There 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

Getting the distribution result by polling

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.

JSON

1 2 3 4 5 6

{
     "status": "distribution status", 
     "qr": "https://pay.klarna.com/{region}/iss/v1/distributions/{session_id}/qr/{access_id}",
     "payment_link": "https://pay.klarna.com/{region}/hpp/payments/xxxxxxx"
  }

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

Success response parameters

Parameter	Type	Description
`status`	string	The distribution status of the payment. Depending on the [ distribution status], you can take some additional actions.
`qr`	string	The 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_link`	string	The payment link URL. You can distribute the link by encoding it as a QR code or by sending it in an SMS.

Distribution statuses

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

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

Distribution status	Description	Action to take
`WAITING`	The 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.
`DISTRIBUTED`	The payment link has been distributed.	Use the link from the distribution result endpoint and display the QR code to the customer.
`ACCESSED`	The customer has accessed the payment link.	No action.
`COMPLETED`	The customer has completed the payment and a new order has been automatically placed.	Get the order id from the distribution result endpoint or webhook.
`CANCELED`	The payment session has been canceled by either partner or consumer.	No action.
`FAILED`	There 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

When a session is created, and the QR it is not scanned by the customer and the session is not canceled by the merchant, then the session will be auto-cancelled after 3 hours.

JSON

1 2 3 4 5 6 7 8 9 10

{
  "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
  }
}

Error codes for status FAILED

Failure error code	Significance	Expected action
`CONSUMER_SESSION_NOT_FOUND`	A 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.
`UNKNOWN`	System error	The session failed due to an internal server error. You may retry by creating a new session. If errors persist, contact Klarna merchant support.

Placing an order automatically

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

1 2 3 4 5 6

  {
    "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.

Retry a failed session

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

JSON

1 2 3 4 5 6 7 8

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