Handling Purchase session

A purchase session is identified by a unique purchaseId and is associated with a "Purchase JWT token" that allows the Checkout form to communicate with the backend API. This article explains how to handle the purchase session, including its lifecycle, expiration, and user flows.

Purchase session

When purchase session is initialized (Initialize payment), you will receive the following response JSON:

{
  "purchaseId": "a902f3322a7c4c61980c3446809749ae",
  "jwt": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
  "expiredUtc": "2025-06-05T13:56:03.8427351+00:00"
}

purchaseId - unique identifier of purchase session.

jwt - "Purchase JWT token" - that is used to embed Checkout 3.0 form in your e-shop.

expiredUtc - UTC ISO 8601 Date and Time string - time when the purchase session will expire and will be switched to state "TimedOut" unless it was completed and reached one of the final states before the timeout was done.

Properties of "Purchase JWT token"

"Purchase JWT token" is a token generated by checkout 3 that contains following payload data:

{
  "sub": "Checkout",
  "jti": "b2969f7d-9921-4c27-9dcd-87e0556814e0",
  "PurchaseId": "a902f3322a7c4c61980c3446809749ae",
  "BranchSiteKey": "77229995-b5d9-4a16-b072-b6c027c63175",
  "exp": 1749133564
}

sub - subject (whom the token refers to)

jti - JWT ID (unique identifier for this token)

exp - Expiration time (seconds since Unix epoch)

PurchaseId - unique identifier of purchase session (will match the purchaseId returned from init payment call mentioned above).

BranchSiteKey - (internal) additional identifier for current partner that the purchase session belongs to.

User flows

1. Happy flow - user successfully completes purchase in timely manner

After the purchase session is initialized, user is presented with Checkout form and user completes the purchase in less than 30 minutes. Checkout backend API sends step "Completed" to Checkout form and in case the purchase was initialized with showThankYouPage true, user will see "Thank you for your payment" message and Checkout form will trigger completedPurchaseCallback(). In case checkout was initialized with showThankYouPage false, Checkout form will only trigger completedPurchaseCallback() without displaying any message to the user.

2. Purchase expires while user interaction is in progress

When user takes more than 30 minutes to complete the purchase while the Checkout form is opened, if the user attempts to do changes to the current purchase session that require sending data to backend API (such as, saving their address, selecting different shipping options, clicking "Complete Payment") when the request is sent to backend API, backend will respond with a new step "TimedOut", message about the session being timed out will appear and sessionTimedOutCallback() is triggered.

3. User is inactive more than one hour

When user takes more than one hour without interacting with the checkout in any way that requires sending data to backend API and after that the user attempts to do changes to the current purchase session that require sending data to backend API (such as, saving their address, selecting different shipping options, clicking "Complete Payment") when the request is sent to backend API, backend will respond with 401 HTTP status code - Unauthorized status code, as the "Purchase JWT token" is no longer valid to get data from backend API. This will be presented to the user as a regular generic error for 401 HTTP status code. In this scenario sessionTimedOutCallback() will not be triggered as the purchase session is in "unknown" state, due to not being able to get data from backend API.

Reclaiming "Purchase JWT token"

In the following section under article about "Showing the Checkout form" you can read about the ability to Reclaiming Purchase JWT. When you reclaim a token you will get the following response:

{ "jwt": "eyJ0eXAiOiJKV1QiLCJhbGciOiJSUzI1NiIsIng1dCI6InBpVmxsb1FEU01..." }

Reclaiming token will give you a new "Purchase JWT token" with exp of another 60 minutes. This does not extend the purchase session. Purchase session that is already in state "TimedOut", will still be in the state "TimedOut" but loading Checkout form with the new "Purchase JWT token" allows the Checkout form to get latest data about the purchase from the backend API. Backend will respond with a step "TimedOut", message about the session being timed out will appear and sessionTimedOutCallback() is triggered.

For purchases that were completed or reached any other final state, loading Checkout form for these purchases will re-show "Thank you for your payment" screen and re-trigger completedPurchaseCallback().

4. Waiting for external service or payment confirmation

In some extremely rare cases, user will complete the payment in the required time limit of 30 minutes but the external service takes longer to confirm payment, payment session will not be "TimedOut" after 30 minutes period but instead it will stay in one of the "Waiting" steps. As long as the "Purchase JWT token" is valid (not expired) user can still see the data, refresh the page. If this takes longer than one hour, backend API will no longer respond with data to the user but will return 401 HTTP status code - Unauthorized.

Summary

Checkout purchase session, identified with unique purchaseId, expires in 30 minutes.

Checkout Backend API will return step "TimedOut" to a user that attempts to do changes to purchase session in Checkout form after the purchase expired and has not reached any other final state.

Purchase JWT token, which allows a merchant to load Checkout form, expires in 60 minutes.

Checkout Backend API will return 401 HTTP status - Unauthorized to any request from Checkout Form after the "Purchase JWT token" has expired.

sessionTimedOutCallback() is only triggered when Checkout form is in step "TimedOut". completedPurchaseCallback() is only triggered when Checkout form is in step "Completed" *.

Reclaiming "Purchase JWT token" can be used to generate a new "Purchase JWT token" for a purchase session, giving a merchant an option to load Checkout form with the latest state of the purchase session.