FloPay SDK Changelog

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.

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.