HPP API: Status Callbacks

It is possible when integrating HPP to received status changes callbacks to a certain URL. This address that is unique to every session will be called by our systems whenever the status of the session is updated. This is really handy to create interaction whenever something happens and avoid to have a costly polling mechanism.

Sequence diagram of callbacksSequence diagram of callbacks

Activating Callbacks

When creating the HPP Session , you need to pass an URL in the status_update field of the merchant_urls. This URL will be called by HPP each time the status of the HPP Session is updated on Consumers actions, it contains the new status of the HPP Session the same way it would be gotten by reading the HPP Session from the read session endpoint of the API .

Definition of callbacks calls

DescriptionPOST the Status of the HPP Session to the integrator
Description
URL
POST the Status of the HPP Session to the integrator
HPP will use merchant_urls.status_update received in the create session call
Description
Operation
POST the Status of the HPP Session to the integrator
POST
Description
Example
POST the Status of the HPP Session to the integrator
curl -X POST <merchant_urls.status_update> --data “<content>”

Body of the callback

Field KeyTypeDescription
Field Key
event_id
Type
String
Description
Identifier of the event, allowing the integrator to de-duplicate operations if needed.
Field Key
session
Type
JSON
Description
And object representing the session status when the event occurred. Content is exactly the same as one could get from the read session endpoint .

Expected response and retry strategy

The calls made to the status_update URL will be made by HPP without waiting for any response from your server. It is expected from the the URL to send back a 2xx status code response.

In case no response is gotten in less than 3 seconds, there will be a retry after a few seconds. This mechanism will happen up to three times, with 4 calls being made for the same events. If of these calls are unanswered, the callback mechanism will end.

Securing the callbacks

The URL provided as status_update must be over HTTPS, but to be able to authenticate that the callback comes from Klarna, it is advised to generate a one time token that you will only use for this specific HPP Session.

This lets you validate that the call made to you on an update of status is only made by us.

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

The value passed here 7d1cbc3b-b30c-4be2-a8c4-dc76482d7bf6 could be something that is generated by the integrator for every new session.

Happy flow examples

These are the callbacks that an integration layer will get when an HPP Session is completed.

Consumer arrives on HPP

1
2
3
4
5
6
7
8
9
{
  "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

To learn more about place_order_mode, read our guide on how to integrate Klarna Payments with HPP .

Default value for place_order_mode
1
2
3
4
5
6
7
8
9
10
{
  "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"
  }
}
With place_order_mode as PLACE_ORDER or CAPTURE_ORDER
1
2
3
4
5
6
7
8
9
10
11
{
  "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": "55550X438HG0Q",
    "updated_at": "2019-05-13T14:54:04.675Z",
    "expires_at": "2019-05-15T13:51:43.507Z"
  }
}

Klarna Checkout

1
2
3
4
5
6
7
8
9
10
11
{
  "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": "55550X438HG0Q",
    "updated_at": "2019-05-13T14:54:04.675Z",
    "expires_at": "2019-05-15T13:51:43.507Z"
  }
}