Skip to content
Last updated

Session lifecycle and recovery

The Checkout SDK guide shows how to create a session on your server, open it with Resolve.js and handle buyer verification. This page explains expiry, retries and credential handling for that integration.

Session lifecycle

  1. Your backend creates a session with the authoritative checkout snapshot and a merchant-scoped Idempotency-Key.
  2. Resolve returns a short-lived client_token. Your browser passes it to Resolve.js as session_token.
  3. Resolve.js redeems the reference into one checkout and handles the buyer handoff. A consumed reference continues to refer to that same checkout.
  4. An asserted buyer verifies their email before payment unless a valid fully authenticated session already belongs to that buyer. Without an assertion, ordinary sign-in applies.
  5. The buyer completes checkout and is logged out. Your success URL receives the authorization identifier for capture and fulfillment.

Session creation, redemption and buyer verification are separate from payment authorization and capture.

Email verification

Before verification, an asserted buyer's restricted context is bound to one merchant, checkout and buyer for a fixed 15 minutes. It cannot access the dashboard, switch accounts or submit a payment.

The buyer requests a code in Resolve checkout. A challenge expires after five minutes and allows at most ten verification attempts. Codes can be requested once per minute. Resending does not reset the attempt limit or extend the restricted session. Wrong codes do not grant access; expired or exhausted verification requires fresh authentication.

Successful verification rotates the session and revokes the restricted cookie, bearer and handoff authority. New or resumed merchant applications reuse the same buyer/email-bound verification. Other buyers or emails require their own verification.

Credential boundaries and safe recovery

CredentialPurposeHandling
Merchant OAuth access tokenServer-only API authenticationAuthorization header from your backend; never sent to a buyer
client_token / SDK session_tokenState-backed reference to one checkoutFive minutes from issuance; treat as opaque
Browser handoff proofEstablish the asserted buyer context in the winning browserTwo minutes, bounded by reference expiry; SDK manages POST bodies/messages
Buyer cookie or in-memory bearerRestricted buyer access before OTP, or normal access after verificationSeparate from the reference; restricted authority has a fixed 15-minute lifetime

Never put credentials, access tokens, references, proofs or assertions in URLs, local/session storage, analytics, logs or error reports. Do not decode or sign a reference in merchant code, reuse an embed key to sign one, or treat an SDK token as a dashboard bearer. Do not persist credential-bearing HTTP response bodies or forward them to monitoring tools.

Single use means one linked checkout, not “every retry fails.” A valid, unexpired redemption retry returns the same checkout, never a second one. Failed creation leaves the reference retryable. Retries never renew the five-minute expiry. Assertion timestamps and mode must remain identical on server retries. The SDK keeps the winning browser nonce in memory so that browser can recover its proof after a lost response; a different browser cannot use a consumed reference to obtain fresh login authority.

If handoff succeeded but its response was lost, retry is possible when the rotated cookie or bearer arrived. If both were lost, or the browser no longer has the SDK's nonce, start a fresh merchant-created session after checking the buyer/cart state. Do not loop a consumed reference to try to restore login. A different current Resolve account produces an explicit account conflict; do not overwrite it or automatically switch identities.

Errors and retry decisions

ResponseMeaningWhat to do
400 CHECKOUT_SESSION_INVALID_REQUEST / INVALID_REQUESTInvalid input, missing key or unsupported modeCorrect the payload; do not blindly retry
400 CHECKOUT_SESSION_INVALID_ASSERTIONEmail mismatch or stale/future assertionCorrect the verified server identity/authentication state
401 at issuanceMissing/invalid merchant-write OAuth or API/OAuth disabledCheck the server access key and merchant settings
409 CHECKOUT_SESSION_IDEMPOTENCY_CONFLICTSame merchant/key with changed dataRecover the original attempt, or deliberately start a new attempt for a changed checkout
409 CHECKOUT_SESSION_BUYER_CONFLICTAsserted identity cannot be safely resolvedResolve the identity conflict; do not invent a replacement subject to bypass it
410 CHECKOUT_SESSION_EXPIRED at issuanceKey's original session expiredCheck checkout/order status, then create a new session with a new key
429Issuance exceeded 60 requests/minute/merchantBack off, preserving the original payload/key
500 CHECKOUT_SESSION_CREATE_FAILEDCreation/signing failedRetry the same unchanged attempt with bounded backoff
401 during redemption/handoffInvalid, expired or unauthorized reference/proofUse a fresh authorized session when recovery is unavailable; expiry is not renewed
409 CHECKOUT_SESSION_ACCOUNT_CONFLICT during handoffAnother Resolve account is activeLet the buyer resolve their account context; do not force an identity switch

For a transport failure with an unknown outcome, retry the same request snapshot/key first. Item, amount and merchant restrictions continue after redemption; a buyer cannot lower the total or substitute same-total items. Authorized merchant/partner order adjustments retain their existing permissions and do not rewrite the session grant.