FloPay SDK Changelog

Client-facing updates for FloPay SDK releases.

v1.0.1 - Session-level currency and catalog codes #

Checkout sessions now use a single session-level currency and a canonical catalog code for items and subscriptions, with backward-compatible fallbacks.

15 May 2026

Improvement
Checkout
Shared
React SDK

FloPay SDK v1.0.1 streamlines how checkout sessions describe pricing and catalog references. Sessions now carry a single top-level currency, and items and subscriptions are identified by a canonical code. Existing integrations continue to work while teams migrate.

What changed

  • Checkout session payloads now use a session-level currency field. Per-line-item currency remains supported as a fallback for older backends.
  • CheckoutItem and CheckoutSubscription accept a new code identifier. The previous providerItemId and providerPlanId fields still work but are now deprecated.
  • Request payloads built by @flopay/js, @flopay/node, and @flopay/react send both the new and legacy fields, so old and new backend versions accept the same body.
  • Display helpers prefer the session-level currency and fall back to code for item and plan names when backend-resolved names are not present.
  • A new client-side session display cache (with TTL and sessionStorage fallback) reduces redundant lookups when rendering checkout details.

Why it matters

  • Multi-item carts no longer need to repeat currency on every line, reducing the chance of mismatched currencies in a single session.
  • Catalogs can standardize on a single human-readable code per item or plan instead of provider-specific identifiers.
  • Merchants can upgrade the SDK without coordinating a simultaneous backend change, thanks to dual-field payloads and response fallbacks.

Developer notes

  • New exports from @flopay/shared: resolveSessionCurrency, buildItemPayload, buildSubscriptionPayload, and related payload helpers.
  • New exports from @flopay/js: session display cache utilities (cacheSessionDisplay, getCachedSessionDisplay, clearSessionDisplayCache) and their types.
  • providerItemId and providerPlanId are now deprecated in favor of code. Plan to migrate before a future major release removes the fallback.
  • Backend-resolved response fields (providerItemName, providerPlanName, totalAmount, overrideAmount, per-line currency, isUpdate) are now optional on response types. Code that reads these should handle their absence.
  • No action is required for merchants who continue to send per-line-item currency and provider identifiers; existing payloads remain valid.

v1.0.0 - Stripe SDK API version pinning #

FloPay SDK packages now use a pinned Stripe API version by default while preserving explicit overrides for Node integrations.

13 May 2026

Release
Stripe
Node SDK

FloPay SDK v1.0.0 updates the Stripe integration foundation across the JavaScript, Node, React, and shared packages. Node SDK requests now default to a known Stripe API version, giving merchants and operators more predictable payment behavior across deploys.

What changed

  • @flopay/node now defaults Stripe operations to API version 2026-04-22.dahlia.
  • Developers can still provide an explicit Stripe API version or secret key override when constructing the Node client.
  • SDK package metadata, documentation, and workspace tooling have been updated for the v1.0.0 release.

Why it matters

  • Payment integrations are less exposed to unplanned behavior changes from implicit Stripe API version selection.
  • Teams can standardize on the default API version while retaining control for staged Stripe upgrades.
  • Documentation now describes the default Stripe API version and available Node client options more clearly.

Developer notes

  • Action required: projects using FloPay SDK packages must run Node.js 20.19+, 22.13+, or 24+.
  • No public API removals are included in this release.