API Documentation
/
Status Callbacks
Last updated

Klarna Docs - Status Callbacks

Status Callbacks

It is possible to receive status change callbacks to a certain URL when integrating HPP. This unique URL is called by Klarna's systems whenever the session status updates. This is useful for creating interactions based on changes and avoiding a costly polling mechanism.

Tracking Session Status Changes

It is recommended to review the dedicated guide on tracking HPP session status changes: https://docs.klarna.com/payments/other-products/hosted-payment-page/before-you-start/tracking-session-status/.

Sequence Diagram of HPP Status Updates

ConsumerBrowserHPPMerchant BackendConsumer arrives at HPP, Merchant backend notified.Consumer authorized, HPP status COMPLETED.Consumer receives confirmation page or redirect.Consumer authorization declined, HPP status FAILED.Consumer receives confirmation page or redirect.Consumer cancels or leaves.Consumer receives confirmation page or redirect.Consumer leaves page, HPP status TIMEOUT.alt[Successful authorization][Declined authorization][Bank and error cases][Timeout]A link to the HPP is provided to the consumer.1Request URL.2Notification IN_PROGRESS.3Presses pay button.4Notification COMPLETED.5Result.6Presses pay button.7Notification FAILED.8Result.9Presses back button or cancellation button.10Notification BACK or CANCELLED.11Result.12Notification TIMEOUT.13ConsumerBrowserHPPMerchant Backend

Activating Callbacks

When creating an HPP session, include a URL in the status_update field of merchant_urls. This URL will be called by HPP whenever the session status changes, containing the updated session status.

Callback Definitions

DescriptionPOST the Status of the HPP Session to the integrator
URLHPP uses merchant_urls.status_update received in the create session call
OperationPOST
Examplecurl -X POST <merchant_urls.status_update> --data "<content>"

Callback Body

Field KeyTypeDescription
event_idStringIdentifier of the event, for de-duplication.
sessionJSONObject representing the session status. Same structure as the read session endpoint.

Expected Response and Retry Strategy

HPP makes calls to the status_update URL without waiting for a response. A 2xx status code response is expected.

If no response is received within 3 seconds, retries occur after a delay, up to 3 times. If all 4 calls fail to receive a response, the callback mechanism ends.

Securing Callbacks

The status_update URL must use HTTPS. For authentication, a unique token for the session should be generated.

Example JSON for securing the callback:

{
    "merchant_urls": {
        "status_update": "https://example.com/statsCallbackEndpoint?hppSessionId={{session_id}}&secretToken=7d1cbc3b-b30c-4be2-a8c4-dc76482d7bf6"
    }
}

Happy Flow Examples

These examples demonstrate successful HPP session completion callbacks.

Consumer Arrives on HPP

{
  "event_id": "270b2adc-35a4-4524-800a-a5d2b8a96a2c",
  "session": {
    "session_id": "35bde117-ce5f-774f-9bcb-ec514a0963ad",
    "status": "IN_PROGRESS",
    "updated_at": "2019-05-13T14:51:46.288Z",
    "expires_at": "2019-05-15T13:51:43.507Z"
  }
}

Consumer Completes Payment (Klarna Payments)

{
  "event_id": "27ba32b0-644b-4b22-94a9-dac503bcae18",
  "session": {
    "session_id": "39a1c773-bafd-754d-af1f-b30c592f1267",
    "status": "COMPLETED",
    "authorization_token": "a1a8f727-2756-6058-bd3c-40069be0994b",
    "updated_at": "2019-05-13T14:54:04.675Z",
    "expires_at": "2019-05-15T13:51:43.507Z"
  }
}
{
  "event_id": "27ba32b0-644b-4b22-94a9-dac503bcae18",
  "session": {
    "session_id": "39a1c773-bafd-754d-af1f-b30c592f1267",
    "status": "COMPLETED",
    "order_id": "a1a8f727-2756-6058-bd3c-40069be0994b",
    "klarna_reference": "X438HG0Q",
    "updated_at": "2019-05-13T14:54:04.675Z",
    "expires_at": "2019-05-15T13:51:43.507Z"
  }
}
{
    "event_id": "cd7e1171-25b1-41ff-97d3-b0dd5e6f9a82",
    "session": {
        "session_id": "39a1c773-bafd-754d-af1f-b30c592f1267",
        "status": "COMPLETED",
        "order_id": "a1a8f727-2756-6058-bd3c-40069be0994b",
        "klarna_reference": "X438HG0Q",
        "updated_at": "2019-05-13T14:54:04.675Z",
        "expires_at": "2019-05-15T13:51:43.507Z"
    }
}
Previous page