FloPay SDK Changelog

v1.8.21 - Broader Stripe payment coverage #

Flopay SDK 1.8.21 expands release validation across Stripe alternative payment methods, test cards, AVS, and always-on 3D Secure flows.

Flopay SDK v1.8.21 is a maintenance release that broadens automated browser coverage for Stripe checkout journeys. Public SDK behavior and integration surfaces remain unchanged.

What changed

• Release validation now covers successful and declined Bancontact, EPS, Cash App Pay, and SEPA Debit journeys, including redirect and resume behavior.
• Additional checks cover enabled payment-method presentation, Stripe test-card outcomes, address verification, and always-on 3D Secure authentication.
• @flopay/js, @flopay/node, @flopay/react, and @flopay/shared are available together at version 1.8.21.

Why it matters

Broader coverage helps protect the payment-method availability, authentication, and result handling that merchants and buyers rely on during checkout.

Developer notes

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

v1.8.20 - Broader checkout release coverage #

Flopay SDK 1.8.20 strengthens release validation for core card checkout journeys while keeping public integration contracts unchanged.

Flopay SDK v1.8.20 is a maintenance release that expands automated browser coverage for core checkout journeys. Public SDK behavior and integration surfaces remain unchanged.

What changed

• Release validation now covers successful card payments, 3D Secure challenges, coupon application, subscription-only checkout, and checkout status updates.
• @flopay/js, @flopay/node, @flopay/react, and @flopay/shared are available together at version 1.8.20.

Why it matters

Broader validation helps protect the checkout journeys merchants and buyers rely on as the SDK evolves.

Developer notes

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

v1.8.17 - Wallets match deferred card intents #

Flopay SDK 1.8.17 aligns deferred Apple Pay and Google Pay Elements with the card intents created by the checkout API.

Flopay SDK v1.8.17 restores reliable Apple Pay and Google Pay confirmation for paid and free-trial checkouts that use deferred Stripe intents.

What changed

• Wallet Elements now declare card payments with off-session reuse for both payment and setup flows, matching the intent supplied during confirmation.
• Future-use settings are applied only to Stripe payment methods that currently support saving and reuse. Other payment methods remain available for the current payment without being marked for later reuse.

Why it matters

Stripe requires deferred Elements options to match the intent supplied during confirmation. Aligning the wallet configuration prevents contract mismatches from stopping Apple Pay or Google Pay before a payment method is attached.

Developer notes

• Upgrade all installed @flopay/* packages to 1.8.17 together.
• Existing checkout and callback APIs are unchanged; no merchant migration is required.
• Stripe-hosted PayPal item payments, free-trial confirmation with non-card payment methods, and later reuse of non-card payment methods are not enabled by this release.

v1.8.16 - Wallets match automatic async payment intents #

Flopay SDK 1.8.16 aligns Apple Pay and Google Pay Elements with Stripe automatic async PaymentIntents.

Flopay SDK v1.8.16 restores Apple Pay and Google Pay confirmation for automatic-capture checkouts.

What changed

• Automatic-capture Wallet Elements now declare Stripe's captureMethod: automatic_async, matching the PaymentIntent created by the checkout API.
• Explicit manual capture and zero-total setup checkouts keep their existing provider contracts.
• Synchronous Stripe confirmation failures now emit privacy-safe operational telemetry without exposing provider messages, identifiers, or buyer data.
• The Android browser gate rejects mismatched wallet contracts before a release can proceed and covers both Apple Pay and Google Pay.

Why it matters

Stripe requires deferred Elements options to match the Intent supplied during confirmation. The previous automatic versus automatic_async mismatch made Stripe.js reject locally before attaching a PaymentMethod, so checkout stayed pending and surfaced stripe_wallet_failed.

Developer notes

• Upgrade all installed @flopay/* packages to 1.8.16 together.
• Existing checkout, callback, and telemetry APIs are unchanged.
• Run pnpm test:wallet:android for the focused cross-wallet browser gate.

v1.8.15 - Apple Pay and Google Pay confirm against deferred intents #

Flopay SDK 1.8.15 aligns Stripe Wallet Elements options with the PaymentIntent created by the checkout API.

Flopay SDK v1.8.15 restores Apple Pay and Google Pay confirmation after the deferred-intent migration introduced in v1.8.12.

What changed

• Payment-mode Wallet Elements now use automatic capture unless the checkout session explicitly requests manual capture.
• Card-backed wallets declare off-session future usage, matching the PaymentIntent created by the checkout API.
• The browser wallet gate now fails when the deferred Elements configuration diverges from the server intent contract.

Why it matters

Stripe requires deferred Elements options to match the Intent supplied during confirmation. The previous mismatch caused Stripe to reject confirmation in the browser before Apple Pay or Google Pay could attach a PaymentMethod, leaving the checkout pending with stripe_wallet_failed.

Developer notes

• Upgrade all installed @flopay/* packages to 1.8.15 together.
• Existing checkout, callback, and telemetry APIs are unchanged.
• Run pnpm test:wallet:android for the focused cross-wallet browser gate.

v1.8.14 - Wallet sheets remain stable during buyer identification #

Flopay SDK 1.8.14 prevents checkout session hydration from changing Stripe identity options while Apple Pay or Google Pay is open.

Flopay SDK v1.8.14 keeps Stripe Express Checkout configuration stable while an Apple Pay or Google Pay sheet is open.

What changed

• Wallet identity requirements are fixed for the lifetime of the mounted Express Checkout surface, so asynchronous checkout session hydration cannot mutate a live payment sheet.
• The Playwright wallet contract now covers Apple Pay and Google Pay, payment and setup intents, late confirmation, callback timeout recovery, retry isolation, and identity hydration while the sheet is open.

Why it matters

Changing emailRequired or billingAddressRequired during a live wallet attempt makes Stripe abort the payment sheet. Buyers could then see stripe_wallet_failed, Google Pay manifest noise, or a second-sheet "merchant busy" error even though the wallet button initially opened.

Developer notes

• Upgrade all installed @flopay/* packages to 1.8.14 together.
• Existing checkout, callback, and telemetry APIs are unchanged.
• Run pnpm test:wallet:android for the focused cross-wallet browser gate.

v1.8.13 - Android Google Pay confirmation restored #

Flopay SDK 1.8.13 lets Stripe attach Google Pay wallet details during Express Checkout confirmation and settles the wallet before publishing retry UI.

Flopay SDK v1.8.13 restores Google Pay confirmation on Android after the v1.8.12 callback-deadline release left Express Checkout Elements configured for explicit PaymentMethod creation.

What changed

• Wallet Elements now let Stripe's supported confirmPayment and confirmSetup calls create and attach the Google Pay PaymentMethod.
• Failed wallet callbacks are settled before checkout error state is published or the Express Checkout surface is remounted.
• The callback browser gate now runs through Playwright's Pixel 7 Android profile and verifies payment and setup flows, timeout settlement ordering, late provider confirmation, retry isolation, and single processing.

Why it matters

Affected checkouts created a Stripe intent but never attached the wallet PaymentMethod, leaving the intent in requires_payment_method, the Flo session pending, and Google Pay waiting until it displayed CALLBACK_TIMED_OUT. Checkout error copy could also appear behind the still-open wallet sheet.

Developer notes

• Upgrade all installed @flopay/* packages to 1.8.13 together.
• Existing checkout, callback, and telemetry APIs are unchanged.
• Run pnpm test:wallet:android for the focused Android wallet browser gate.

v1.8.12 - Reliable Google Pay callback settlement #

Flopay SDK 1.8.12 settles wallet authorization before Google Pay's callback deadline, uses Stripe's supported Express Checkout confirmation contract, and safely resumes confirmed wallet handoffs.

Flopay SDK v1.8.12 prevents Google Pay from remaining open until it displays CALLBACK_TIMED_OUT. Wallet authorization now has one bounded lifecycle that settles the provider callback before Google's hard deadline and keeps late work from creating duplicate payment activity.

What changed

• Wallet authorization now has a 25-second SDK budget, leaving five seconds of headroom under Google Pay's 30-second callback deadline.
• Every validation, cancellation, decline, transport, provider, and timeout outcome fails the active wallet callback at most once with safe retry copy.
• Flo-owned session-intent requests receive the authorization cancellation signal. Pre-intent work that completes after cancellation cannot continue to provider confirmation or checkout processing.
• PaymentIntent and SetupIntent wallets now use Stripe's supported confirmPayment and confirmSetup calls with the active Express Checkout Elements instance. The confirmed provider intent supplies the PaymentMethod forwarded to checkout processing.
• Missing wallet identity is collected outside the active provider callback. The current attempt fails promptly and the buyer reopens the wallet after supplying the required email.
• A short-lived, single-consumer checkpoint resumes a confirmed wallet intent if the browser is interrupted between provider confirmation and /process, without creating another provider intent.
• Privacy-safe performance and timeout telemetry identifies the stalled wallet phase, elapsed callback time, and wallet category without buyer details, payment data, provider payloads, or session credentials.

Why it matters

An unresolved Google Pay callback could leave the provider sheet blocking the checkout until Google timed it out, while the checkout remained pending with no intent or transaction. The bounded callback contract now gives the buyer an immediate retry path, prevents canceled pre-intent work from continuing, and still completes an intent that Stripe had already confirmed.

Developer notes

• Upgrade the @flopay/* packages you use to 1.8.12 together.
• Existing checkout and callback APIs are unchanged.
• Version 1.8.11's single /process request and authenticated session-read reconciliation remain the recovery contract after processing begins.
• Google Pay wallet changes should follow the real-device release smoke checklist in docs/WALLET_DOMAIN_VERIFICATION.md.

v1.8.11 - Safe payment reconciliation and method-aware telemetry #

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.

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.

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.

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.