FloPay SDK Changelog

v1.2.4 - Session-bound checkout token across continuation calls #

Checkout session creation now returns a session-bound token (nonce) that the SDK forwards on every continuation call, hardening hosted checkout, payment, and saved-payment flows against cross-session reuse.

FloPay SDK v1.2.4 introduces a per-session checkout token (nonce) that scopes every continuation request to the session that created it. The token is returned alongside the new checkout session and forwarded automatically by the SDK on payment intent, process, completion polling, and saved-payment flows. A short-lived, same-domain cookie also makes the token available to hosted checkout pages without exposing it in URLs.

What changed

• createCheckoutSession now returns a nonce on the 201 result for @flopay/js and @flopay/node. The browser SDK additionally writes a same-domain flopay_checkout_token cookie (SameSite=Lax, Secure, 1 hour TTL) so hosted checkout pages can read the token without it appearing in the URL, browser history, or Referer header.
• PaymentAPI.processPayment now targets POST /v1/checkouts/sessions/{id}/process and sends the token on the x-checkout-session-token header. createPaymentIntent, createSetupIntent, and the checkout-completion poll forward the same header.
• React surfaces (CheckoutForm, SplitCardForm, DirectPayPalButton, PayPalButton) accept a new nonce prop and forward it on every inline continuation request. FloPayCheckout plumbs the session's token into each child surface automatically, including consumer-supplied form children.
• The saved-payment flow forwards the token on process, intent creation, and the 3DS recovery refetch.
• A clear FloPayError with code MissingCheckoutSessionToken is now thrown when a process call is attempted without a token, replacing the prior generic failure.

Why it matters

• Every continuation call is bound to the originating checkout session, reducing the surface area for cross-session reuse and accidental cross-tab interference.
• Hosted checkout pages can authenticate continuation calls without leaking the token through URLs or Referer headers, keeping the integration cookie-scoped and same-domain.
• Saved-payment and 3DS recovery flows are covered by the same token contract as primary checkout, so the security posture is consistent across all payment paths.
• Improved security hardening

Developer notes

• This release pairs with a backend update that requires the x-checkout-session-token header on every /v1/checkouts/* continuation route. Upgrade @flopay/js, @flopay/react, @flopay/node, and @flopay/shared together to 1.2.4 to stay in sync.
• If you call processPayment, createPaymentIntent, or createSetupIntent directly, read nonce from the createCheckoutSession result and pass it through to those calls. The SDK will throw FloPayError({ code: 'MissingCheckoutSessionToken' }) if a process call is made without it.
• If you use FloPayCheckout or the bundled React forms, no integration change is required beyond the version bump — the provider forwards the token to each child surface for you.
• If you render your own checkout UI on a hosted page, you can now read the flopay_checkout_token cookie on the same domain instead of carrying the token through the URL.
• The processPayment endpoint moved from a generic /v1/checkouts/sessions/process shape to POST /v1/checkouts/sessions/{id}/process. If you proxy this call, update your route accordingly.