Flopay SDK 1.8.11 reconciles a checkout before treating a lost process response as failure, never replays the charge, and attributes processing telemetry to the selected payment method.
27 Aug 2026
Bug Fix
Checkout
JavaScript SDK
React SDK
Observability
Flopay SDK v1.8.11 closes an ambiguity between a successful backend payment and
a browser that never receives its response. The SDK now checks the authoritative
checkout session before showing an error, while keeping the money-affecting
request strictly single-shot.
What changed
- When
POST /process rejects without an HTTP response, PaymentAPI polls the
checkout session through authenticated reads. A session that settled as
complete or authorized returns the same public result as the existing
processing-response path.
- Recovery never submits
/process a second time. The React saved-payment flow
no longer wraps payment processing in its former fetch-failure retry.
- Checkout and manual-authorization expiry keep their existing stable errors,
caller-initiated aborts still propagate immediately, and reconciliation stays
within the existing bounded polling budget.
- Processing and recovery telemetry now carries the selected privacy-safe
method category:
card, wallet, paypal, apm, or saved. Existing
direct callers that do not provide a category continue to report unknown.
- A recovered payment emits completion and recovery lifecycle/performance
signals without a false technical error. A failed reconciliation emits one
sanitized, method-attributed recovery error.
Why it matters
A dropped connection after a charge left the browser unable to distinguish a
failed payment from a successful payment whose acknowledgement was lost. That
could tell an already-charged buyer to try again. The session read makes the
decision from backend state without risking a duplicate charge, while the
method category makes wallet, PayPal, APM, saved-card, and card processing
health comparable in telemetry.
Developer notes
- Upgrade the
@flopay/* packages you use to 1.8.11 together.
ProcessPaymentParams.paymentMethodCategory is optional and accepts the
shared telemetry category union. Existing integrations require no migration.- The category is used only by Flo's bounded operational telemetry and is not
sent in the
/process request body.
- No payment details, buyer data, session nonce, provider payload, or other PII
is added to telemetry.
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.
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.
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.
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.
Flopay SDK 1.8.7 refreshes its development tooling while keeping public APIs and runtime behavior unchanged.
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.
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.
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.
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.
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.
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.