FloPay SDK Changelog

Client-facing updates for FloPay SDK releases.

v1.8.10 - Reliable automatic checkout success and PayPal routing #

Flopay SDK 1.8.10 keeps a completed automatic checkout reported as successful even when a merchant callback throws, and lets the session's own PayPal advertisement decide the direct PayPal channel.

26 Aug 2026

Bug Fix

Checkout

React SDK

PayPal

Flopay SDK v1.8.10 fixes two ways a checkout could take the wrong path after the backend had already decided the outcome. A wallet payment that succeeded no longer shows as a failure because merchant code threw while handling it, and direct PayPal now follows the channel the session itself advertises.

What changed

FloPayAutomaticPaymentButton runs the merchant onSuccess callback through the SDK's isolated invoker. A callback that throws — or returns a rejecting promise — is logged to the merchant's console and the checkout stays successful, instead of being reclassified as a payment failure.
The automatic button recognises the synchronous auto-completed sentinel structurally, by its code, rather than by instanceof FloPayError. A page that loads more than one copy of the SDK runtime no longer loses the already-completed session and reports it as an error.
DirectPayPalButton and SplitCardForm treat the session's gateways.paypal.providerObjectType as the authoritative source for the PayPal channel. An advertised order or setup_token now selects the Flo-owned paypal_vaulted requests even when the integration never forwarded the providerObjectType prop.
SplitCardForm custom layouts fall back to the session on the checkout context, so a merchant-composed layout that does not pass session directly still routes and retries against the advertised PayPal object.
Stripe-hosted PayPal is unchanged, and a legacy session that advertises nothing keeps sending the released paypal requests byte-identically.

Why it matters

Google Pay and the other automatic wallets could complete in the backend and still surface an error to the buyer, purely because the merchant's own success handler threw. Direct PayPal could meanwhile fall back to the legacy channel on a current session, despite the backend having routed the checkout to a Flo-owned Order or Setup Token.

Developer notes

Upgrade the @flopay/* packages you use to 1.8.10 together.
The providerObjectType prop on DirectPayPalButton and on SplitCardForm's directPaypal config is deprecated. Forward the session instead; the prop still works as a fallback for integrations that do not.
Merchant onSuccess failures now reach the browser console as [FloPay] Merchant callback failed; checkout continued. and are not sent as Flo telemetry. Handle your own errors inside the callback if you need them reported.
Existing integrations require no migration.

v1.8.9 - Checkout session metadata #

Flopay SDK 1.8.9 lets developers attach typed, non-sensitive metadata when creating a checkout and read the preserved snapshot from session responses.

25 Aug 2026

Feature

Checkout

JS SDK

Node SDK

React SDK

Shared SDK

Flopay SDK v1.8.9 lets developers attach non-sensitive string metadata to a checkout session through the supported TypeScript APIs. The metadata travels with the checkout from creation and is available as an immutable snapshot on session responses, without custom REST requests or type augmentation.

What changed

@flopay/shared now exports CheckoutMetadata, a Record<string, string> type, and adds the optional nullable checkoutMetadata field to public checkout creation types.
@flopay/js, @flopay/node, and @flopay/react forward supplied metadata unchanged through redirect, retrying, inline, and detached session creation. Detached checkout sends it once on the initial shell request, not on later catalog or buyer claims.
Session responses expose the returned snapshot as checkoutMetadata, including on normalized results and their nested session.
React treats metadata as part of the logical checkout identity, so a material change creates a new session while key-order-only changes do not. Raw keys and values are not written to the persistent session cache.
Backend metadata validation failures retain their structured FloPayError code, message, and HTTP status in browser, React, and Node flows.

Why it matters

Merchants can associate their own order, campaign, or integration context with a checkout using the SDK's typed public contract. That context remains attached to the checkout lifecycle without being mixed into provider-specific metadata.

Developer notes

Upgrade the @flopay/* packages you use to 1.8.9 together.
Pass only non-sensitive string values in checkoutMetadata. The backend remains the sole runtime authority for key, value, count, and payload limits.
Omitting checkoutMetadata or passing null leaves it absent from session reads; passing {} preserves and returns an empty map.
checkoutMetadata is separate from the existing legacy session metadata field and cannot be edited after checkout creation.
Existing integrations that omit the field require no migration.

v1.8.8 - Inline validation for checkout fields #

Flopay SDK 1.8.8 shows an inline error against the email and billing address fields as soon as a buyer leaves one incomplete, matching the postcode field.

25 Aug 2026

Checkout

Accessibility

Flopay SDK v1.8.8 gives every required checkout field the feedback the postcode field already had. When a buyer leaves the email, street address, city or state field empty — or types an email the form cannot accept — the field is outlined in the theme's danger colour and an inline message appears beneath it, and the hosted card form's submit stays closed until it is fixed.

What changed

The collected email and the AVS street, city and state fields now reveal an inline role="alert" message once the buyer leaves them, wired to the input through aria-invalid and aria-describedby.
Inline messages render in the theme's danger colour. Previously the postcode message inherited the regular input text colour, so it appeared in the body colour rather than red.
An invalid city no longer draws a box that is open on its right-hand edge, where it meets the state field.
Fields are only flagged once the buyer has actually been in them. Focus moves the page makes itself — including the card form's own load-time autofocus — no longer mark a field as visited.
The cursor is no longer pulled back to the top of the form when the buyer tabs from the last billing field into the card fields.
The card form renders in the order it is painted, so tab moves through it from top-left to bottom-right.

Why it matters

A buyer who left a required field blank previously saw a submit button that would not proceed, with nothing indicating which field was at fault. Each field now explains itself at the moment the buyer leaves it.

Developer notes

Upgrade the @flopay/* packages you use to 1.8.8 together.
No public exports, props, or API payloads have changed; the new messages use the existing appearance.variables.colorDanger token and fall back to the default red when it is not set.
Existing integrations require no migration.

v1.8.7 - SDK maintenance update #

Flopay SDK 1.8.7 refreshes its development tooling while keeping public APIs and runtime behavior unchanged.

24 Aug 2026

Maintenance

Flopay SDK v1.8.7 is a maintenance release that refreshes the tooling used to build, test, and validate the published SDK packages. Public SDK behavior and integration surfaces remain unchanged.

What changed

Development tooling and related dependency resolutions have been refreshed.
@flopay/js, @flopay/node, @flopay/react, and @flopay/shared are available together at version 1.8.7.

Why it matters

This update keeps SDK maintenance and release validation current without changing merchant checkout behavior or developer integration contracts.

Developer notes

Upgrade the @flopay/* packages you use to 1.8.7 together.
No public exports, API payloads, documented configuration, or runtime dependencies have changed.
Existing integrations require no migration or operational action.

v1.8.6 - Email-less checkout restored #

Buyers can check out without providing an email up front while retaining eligible Stripe methods and Direct PayPal.

23 Aug 2026

Bug Fix

Checkout

Stripe

PayPal

Flopay SDK v1.8.6 restores email-less checkout across card, eligible wallets and alternative payment methods, and Direct PayPal. Checkout can load the catalog, totals, and available payment methods before buyer identity is known, while flows that already supply buyer details continue unchanged.

What changed

Email-less sessions now retain card, Apple Pay, Google Pay, and configured Stripe payment methods across the default, buttons, and custom-child layouts when those methods pass their normal eligibility checks.
Direct PayPal starts without an upfront Flo identity form, uses payer details returned after approval, and asks for missing details only when needed.
Inline, detached, and existing anonymous sessions now attach identity collected later in the checkout before payment continues.
PaymentAPI.createAndFetchSession now accepts email-less detached drafts and returns a catalog-attached session with buyerIdentified: false until the buyer is identified.

Why it matters

Merchants can let buyers choose from their eligible payment methods before asking for an email. Buyers are prompted only when their selected provider cannot supply the identity required to complete payment.

Developer notes

Upgrade the @flopay/* packages you use to 1.8.6 together.
Email-less checkout requires billing API v1.7.12 or newer.
No migration is required for FlopayCheckout. Integrations that inspect anonymous sessions directly should use buyerIdentified and allow buyer identity fields to remain unresolved until the late identity step completes.

v1.8.5 - Provider-first anonymous checkout #

Email-less checkout keeps every eligible Stripe method and starts Direct PayPal before asking Flo for buyer details.

22 Aug 2026

Bug Fix

Checkout

Stripe

PayPal

FloPay SDK v1.8.5 restores the provider-first anonymous checkout contract. A checkout can start without buyer email/name while retaining the catalog totals, country gates, and every payment method the session is otherwise eligible to show.

What changed

Detached email-less creation now claims the known catalog immediately without sending blank accountData. The attached session remains anonymous with buyerIdentified: false and carries the backend's complete Stripe method list.
createAndFetchSession accepts email-less detached drafts and returns that catalog-attached anonymous session.
Late buyer identification is an independent, idempotent buyer-only claim.
Direct PayPal no longer renders a Flo email/name preflight. It starts the Smart Button, consumes payer identity after approval, and shows one manual fallback only when the anonymous provider result is incomplete.
Default, buttons, custom-child, and PayPal-only checkout surfaces share the same provider-first orchestration. Existing supplied-buyer request bodies and callbacks are unchanged.

Why it matters

Anonymous buyers keep card, Apple Pay, Google Pay, configured APMs, and PayPal when those methods pass their normal device, merchant, cart, currency, country, and subscription eligibility checks. Flo asks for identity only when the selected method cannot return the required values.

Developer notes

Upgrade all @flopay/* packages to 1.8.5 together.
Anonymous checkout requires billing API v1.7.12 or newer (backend #1314), where catalog and buyer attachment are independent and provider-authorized identity can be resolved during payment.
The released regression began with the optional-email architecture in SDK 1.8.3; 1.8.4 widened Direct PayPal's redundant preflight. The confirmed live reproduction for #249 was 1.8.4, embedded/buttons, staging. Production reproduction and deployed backend versions still require environment-level release validation.

v1.8.4 - PayPal Direct collects anonymous buyer identity #

PayPal-only checkout and the default-layout Direct PayPal button now collect missing buyer email before the Smart Button is usable.

21 Aug 2026

Bug Fix

Checkout

React SDK

PayPal

FloPay SDK v1.8.4 restores late buyer identification on PayPal Direct for sessions that start without an email. 1.8.3 already collected identity on the card, wallet, and buttons-layout PayPal surfaces; the PayPal-only checkout path and the default-layout Direct PayPal button omitted that callback, so an anonymous shell rendered a Smart Button with no way to attach the buyer.

What changed

PayPal-only FloPayCheckout now forwards onBuyerIdentityReady and the draft billing name into DirectPayPalButton, so the preflight identity pane appears before the Smart Button is interactive.
The default-layout Direct PayPal button in SplitCardForm receives the same identity callback and billing name the buttons layout already had.
The shared identity pane exposes flopay-email and flopay-name test ids, matching the vault card fields.

Why it matters

Merchants can start a PayPal Direct checkout without a buyer email. The SDK collects it in-flow, claims the detached session, and then shows the Smart Button. Without this, anonymous PayPal-only checkouts could never finish.

Developer notes

Upgrade the @flopay/* packages you use to 1.8.4 together; this repository publishes the workspace at one shared version.
No public API change. Existing sessions that already carry a valid email keep their current PayPal Direct behaviour.

v1.8.3 - Optional checkout buyer identity #

Merchants can now start a checkout before the buyer's email is known, and the SDK collects identity during checkout only when the chosen payment method does not provide it.

19 Aug 2026

Improvement

Checkout

React SDK

JS SDK

Shared SDK

Flopay SDK v1.8.3 makes the buyer's email optional when a checkout session is created. Checkout can begin before identity is known and gathers it in-flow only when the selected payment method does not already supply it. Existing sessions that carry complete buyer data keep their current behavior.

What changed

FlopayCheckout can be rendered with a userId but no email. The session is created and the payment surface mounts before buyer identity exists.
Buyer identity is captured automatically when the buyer pays with a wallet or PayPal flow that returns it. When the provider does not supply identity — for example on alternative payment methods — checkout shows a required panel that collects the buyer's email and name before payment is submitted.
Card checkout collects the required email and name on the payment surface, validates them before submit, and attaches only complete, non-blank values.
@flopay/shared now exports the isValidEmail helper for reusing the same email validation the SDK applies internally.

Why it matters

Merchants no longer need the buyer's email up front to start a checkout. This supports flows where identity is collected during, rather than before, payment, while sessions that already include full buyer details continue to work unchanged.

Developer notes

Upgrade the @flopay/* packages you use to 1.8.3 together; this repository publishes the workspace at one shared version.
When rendering FlopayCheckout, userId remains required; you may now omit the buyer email and let checkout collect it when needed.
Use the exported isValidEmail from @flopay/shared if you want to pre-check buyer email with the same rules the SDK enforces.

v1.8.2 - Reliable session retries and Vite-ready payment logos #

Node session creation now honors caller-managed idempotency keys, while React payment logos load reliably in default Vite integrations.

18 Aug 2026

Reliability

Checkout

Node SDK

React SDK

FloPay SDK v1.8.2 makes checkout-session retries safer for server integrations and removes the bundler-specific asset resolution that broke alternative-payment method logos in Vite.

What changed

@flopay/node sends a valid caller-supplied idempotencyKey unchanged as the Idempotency-Key header when creating a checkout session. Omitting the option keeps the request unkeyed, and empty or overlong values are safely ignored.
@flopay/react loads its ten payment-brand SVGs from the versioned FloPay CDN instead of resolving package-relative assets with import.meta.url.
A failed or CSP-blocked logo request now falls back to the existing inline method monogram instead of leaving the payment tile without a brand mark.
The SVG sources remain in the repository for controlled CDN publishing, but no SVG files or bytes are emitted in the published React package.

Why it matters

Server callers can reuse one stable key after a lost response without risking a second logical checkout session. React consumers can render payment logos under Vite's default dependency optimizer without middleware or optimizeDeps changes, while other supported bundlers keep the same rendered behavior.

Developer notes

Upgrade the @flopay/* packages you use to 1.8.2 together; this repository publishes the workspace at one shared version.
Merchants with a strict Content Security Policy must allow https://cdn.flopay.com in img-src.
The ten files under https://cdn.flopay.com/sdk-logos/v1/ must be live before publishing this release.

v1.8.1 - Leaner checkout SDK #

Checkout integrations load less unused JavaScript after the retired Flopay Elements and legacy PayPalButton APIs were removed.

18 Aug 2026

Maintenance

Checkout

Performance

React SDK

JS SDK

Shared SDK

Flopay SDK v1.8.1 reduces the merchant checkout bundle by removing public APIs from earlier Elements-based integrations. Supported checkout experiences remain available through FlopayCheckout and SplitCardForm, with standalone direct PayPal available through DirectPayPalButton.

This is an intentional breaking change for integrations that import the removed APIs. Integrations already using the maintained checkout components do not need to change their checkout flow.

What changed

@flopay/react no longer exports PayPalButton, PaymentElement, AddressElement, useElements, or their associated prop types. FlopayProvider also no longer exposes a Flopay Elements group.
@flopay/js no longer exports FlopayElements. The Flopay class no longer provides elements(), submitElements(), confirmPayment(), confirmPayPalPayment(), or resumePayPalPayment().
@flopay/shared no longer exports the matching Elements constants, types, or legacy payment-provider adapter methods.
Hosted card capture, wallet and alternative payment methods, and supported direct PayPal checkout flows remain available through the maintained SDK surfaces.

Why it matters

In a like-for-like comparison with v1.7.0, the merchant checkout bundle is 18,137 bytes smaller raw, 3,747 bytes smaller when gzip-compressed, and 2,562 bytes smaller when Brotli-compressed.

Developer notes

Upgrade the @flopay/js, @flopay/node, @flopay/react, and @flopay/shared packages you use to 1.8.1 together.
Replace legacy Elements usage with FlopayCheckout or SplitCardForm. Replace the removed PayPalButton with DirectPayPalButton when you need a standalone PayPal control.
There is no deprecation bridge for the removed exports. Update direct imports and any affected TypeScript types before upgrading.

SDK Changelog

On this page