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.
"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 |
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.
| 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. |
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 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.
{
"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 | 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. |
|
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. |
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.
{
"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.
"distribution": {
"method": "one_qr",
"short_code": "4212",
"callback_urls": {
"status_update": "https://example.com/callback"
}
}