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.
- Your backend creates a session with the authoritative checkout snapshot and a merchant-scoped
Idempotency-Key. - Resolve returns a short-lived
client_token. Your browser passes it to Resolve.js assession_token. - Resolve.js redeems the reference into one checkout and handles the buyer handoff. A consumed reference continues to refer to that same checkout.
- 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.
- 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.
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 | Purpose | Handling |
|---|---|---|
| Merchant OAuth access token | Server-only API authentication | Authorization header from your backend; never sent to a buyer |
client_token / SDK session_token | State-backed reference to one checkout | Five minutes from issuance; treat as opaque |
| Browser handoff proof | Establish the asserted buyer context in the winning browser | Two minutes, bounded by reference expiry; SDK manages POST bodies/messages |
| Buyer cookie or in-memory bearer | Restricted buyer access before OTP, or normal access after verification | Separate 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.
| Response | Meaning | What to do |
|---|---|---|
400 CHECKOUT_SESSION_INVALID_REQUEST / INVALID_REQUEST | Invalid input, missing key or unsupported mode | Correct the payload; do not blindly retry |
400 CHECKOUT_SESSION_INVALID_ASSERTION | Email mismatch or stale/future assertion | Correct the verified server identity/authentication state |
| 401 at issuance | Missing/invalid merchant-write OAuth or API/OAuth disabled | Check the server access key and merchant settings |
409 CHECKOUT_SESSION_IDEMPOTENCY_CONFLICT | Same merchant/key with changed data | Recover the original attempt, or deliberately start a new attempt for a changed checkout |
409 CHECKOUT_SESSION_BUYER_CONFLICT | Asserted identity cannot be safely resolved | Resolve the identity conflict; do not invent a replacement subject to bypass it |
410 CHECKOUT_SESSION_EXPIRED at issuance | Key's original session expired | Check checkout/order status, then create a new session with a new key |
| 429 | Issuance exceeded 60 requests/minute/merchant | Back off, preserving the original payload/key |
500 CHECKOUT_SESSION_CREATE_FAILED | Creation/signing failed | Retry the same unchanged attempt with bounded backoff |
| 401 during redemption/handoff | Invalid, expired or unauthorized reference/proof | Use a fresh authorized session when recovery is unavailable; expiry is not renewed |
409 CHECKOUT_SESSION_ACCOUNT_CONFLICT during handoff | Another Resolve account is active | Let 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.