# Kustom 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 Kustom'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.kustom.co/v3/hosted-payment-page/before-you-start/tracking-session-status).

### Sequence Diagram of HPP Status Updates


```mermaid
sequenceDiagram
autonumber
participant A as Consumer
participant B as Browser
participant C as HPP
participant D as Merchant Backend

C -->> A: A link to the HPP is provided to the consumer.
B -->> C: Request URL.
note over A,D: Consumer arrives at HPP, Merchant backend notified.
C -->> D: Notification IN_PROGRESS.
alt Successful authorization
A -->> C: Presses pay button.
note over A,D: Consumer authorized, HPP status COMPLETED.
C -->> D: Notification COMPLETED.
note over A,D: Consumer receives confirmation page or redirect.
C -->> B: Result.
else Declined authorization
A -->> C: Presses pay button.
note over A,D: Consumer authorization declined, HPP status FAILED.
C -->> D: Notification FAILED.
note over A,D: Consumer receives confirmation page or redirect.
C -->> B: Result.
else Bank and error cases
note over A,D: Consumer cancels or leaves.
A -->> C: Presses back button or cancellation button.
C -->> D: Notification BACK or CANCELLED.
note over A,D: Consumer receives confirmation page or redirect.
C -->> B: Result.
else Timeout
note over A,D: Consumer leaves page, HPP status TIMEOUT.
C -->> D: Notification TIMEOUT.
end
```

## 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

| Description | POST the Status of the HPP Session to the integrator |
|  --- | --- |
| URL | HPP uses `merchant_urls.status_update` received in the create session call |
| Operation | POST |
| Example | `curl -X POST <merchant_urls.status_update> --data "<content>"` |


### Callback Body

| Field Key | Type | Description |
|  --- | --- | --- |
| `event_id` | String | Identifier of the event, for de-duplication. |
| `session` | JSON | Object 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:


```json
{
    "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


```json
{
  "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 (Kustom Payments)


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


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


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