Session Management

Monitor the session state

The checkout exposes a reactive sessionState store that reflects the current lifecycle of the client session. Subscribe to it to lock your UI while a payment is in flight, react to errors, and detect expiry.

checkout.sessionState.subscribe((state) => {
    switch (state) {
        case 'ready':
            // Session loaded — the user can interact
            break;
        case 'submitting':
            // Validation in progress — lock the UI
            break;
        case 'submitted':
            // Payment validated — the session is spent and cannot be reused
            break;
        case 'expired':
            handleExpiredSession();
            break;
        case 'error':
            // Transient, recoverable error
            break;
    }
});

The state is one of the following values:

State	Meaning
idle	No session loaded yet.
ready	Session loaded, methods available — the user can interact.
submitting	Validation in progress — the UI must be locked.
submitted	Payment validated. The session is now spent and cannot be reused.
error	A transient, recoverable error occurred.
expired	The session TTL was exceeded. Fatal — the user must be given a fresh session.
terminated	The session was explicitly terminated by code.

SDK reference

See sessionState on the PurseHeadlessCheckout class and the PurseHeadlessCheckoutSessionState type for the full definition.

Detecting expiry

sessionState is the supported way to detect an expired session — watch for the expired value. The store is set to expired both when the session TTL elapses and when an PurseHeadlessCheckoutExpiredSessionError is thrown during initialization. To recover, fetch a new client session from your backend and pass it to checkout.setSession() (see below).

Update the Client Session

When cart details change, update the client session with checkout.setSession().

async function updateSession(newSession) {
    return checkout.setSession(newSession);
}

When should you update the client session?

• When you handle payment methods outside of the checkout widget
• When you update the cart details like amount, delivery options, etc.
• When the session has expired

Set a Wallet Session

To manage saved payment methods, create a WalletSession using checkout.setWalletSession().

async function setWalletSession(walletSession) {
    return checkout.setWalletSession(walletSession);
}

For V2 API users

A WalletSession is automatically created when you initialize the checkout. No need to call setWalletSession.