FloPay SDK Changelog

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.

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.

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.

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.

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.