FloPay SDK Changelog

v1.11.2 - Clearer wallet confirmation failures and capture method in custom layouts #

Rejected Apple Pay and Google Pay confirmations now report a bounded cause in technical-error telemetry, and wallets in custom checkout layouts declare the session's capture method.

When Stripe rejects an Apple Pay or Google Pay confirmation as an invalid request, the technical-error telemetry event now says which kind of rejection it was. Operators can tell a mismatch between the wallet's payment form and the payment apart from a payment that changed state before the wallet returned, without collecting raw provider messages or payment details.

What changed

• Bounded cause for rejected wallet confirmations. A wallet confirmation reported with errorCode CONFIGURATION_INVALID now carries one reason:
  • deferred_contract_mismatch: the wallet's payment form did not match the payment or setup the billing API created.
  • intent_unexpected_state: the payment or setup was no longer in a state that could be confirmed when the wallet returned.
  • invalid_request: any other request Stripe rejected as invalid.
• Codes are unchanged. errorCode and failureCategory stay the same for every wallet confirmation failure, and provider runtime failures still carry no reason. Any other reason value is still reported as unknown.
• Capture method in custom layouts. When SplitCardForm is rendered inside the checkout provider without its session prop, Apple Pay and Google Pay now declare the capture method of the checkout session, as they already did for its future-use setting. Manual-capture sessions no longer present the wallet as an automatic-capture payment.

Developer notes

No change is required for standard checkout integrations. Telemetry consumers should accept the three new reason values on technical-error events.

v1.11.1 - A payment that went through is no longer reported as declined #

When a buyer pays again on a checkout session where an earlier attempt failed, the SDK now waits for the result of the new payment instead of reporting the earlier failure, and declines found while a payment is processing carry their decline code.

When a buyer paid again on a checkout session after an earlier attempt had failed, for example in the fallback checkout the automatic payment button opens after a declined saved card, the SDK could read the earlier failure as the result of the new payment. It called onDecline while the new payment went on to succeed, so a buyer who was told the payment had failed could pay a second time.

What changed

• Only the submitted payment's failure counts. While a payment is still processing, the SDK treats a failed attempt as the result only when it belongs to the payment just submitted. A failure left over from an earlier attempt on the same session is ignored, and the SDK keeps waiting within the existing processing time limit.
• Failures already reported are not reported again. When the SDK cannot tell which payment it submitted, it ignores a failure it has already reported for that session, including one reported by another part of the SDK on the same page, such as the automatic payment button before its fallback checkout.
• Checkout confirms the session before declining. Before SplitCardForm reports a decline that arrived while a card, wallet or PayPal payment was processing, including in the fallback checkout the automatic payment button opens, it reads the session again. If the session is already complete or authorized, it calls onComplete instead of onDecline. A saved payment method that the React checkout component charges itself, and the PayPal button of a PayPal-only session, skip this extra read; the two checks above still apply to them.
• Declines carry their detail. A decline found while the payment was processing now includes a code, and a declineCode when the billing API reports a decline reason, on onDecline and in the PaymentAPI.processPayment response body.
• Timeouts are unchanged. If the processing time limit runs out before the submitted payment has a result, the outcome is still checkout_processing_timeout.

Integration notes

No code changes are needed.

v1.11.0 - Payment method setup keeps provider scripts on demand #

New checks confirm that importing @flopay/react/payment-method-setup loads neither Stripe.js nor the PayPal SDK. SDK behavior and the published API are unchanged.

The @flopay/react/payment-method-setup entry point loads Stripe.js and the PayPal SDK only on demand, not when the entry point is imported. This release adds automated checks against the published build that keep it that way, so a setup session that offers only cards or only PayPal doesn't load a provider script it doesn't need. SDK code, exports and types are unchanged.

Integration notes

No code changes are needed.

v1.11.0 - Every Stripe payment method follows the platform's future-use policy #

Every Stripe payment form in the SDK now declares the future-use setting the billing API reports for the session, and the card-setup futureUse request field is deprecated.

Every payment taken through Stripe is now set up for future use as a platform rule. The billing API decides the setting for every payment and setup, and the SDK declares exactly what the billing API reports, so the payment form and the payment always agree. Previously each part of the SDK chose its own setting: checkout wallets and PayPal always declared off-session use, a few alternative methods did too, and the payment-method setup component declared nothing.

What changed

• One rule for every Stripe payment form. Checkout Apple Pay and Google Pay (for payments and for free trials), alternative methods such as iDEAL or SEPA Direct Debit, Stripe-rendered PayPal and the React payment-method setup component all take their future-use setting from the session read. When the billing API reports futureUse, every form declares exactly that value to Stripe.
• Methods that can't be saved for reuse are explicit. When the billing API lists a method in futureUseUnsupported, that method's form declares no future use and the method stays payable for a one-off payment.
• Older billing APIs behave exactly as before. When the session read has no futureUse, every form keeps its previous setting.
• Saved methods are not set up again. Paying with a saved method, auto-confirm methods such as Cash App Pay, and the SDK's payment-intent requests carry no future-use setting.
• @flopay/js session reads carry the policy. Purchase and setup reads now include futureUse (when it is 'on_session' or 'off_session') and futureUseUnsupported (entries without a string paymentMethodType and reason are dropped) exactly as the billing API returns them.

Deprecations

• CreateCardSetupSessionRequest.futureUse is deprecated. The billing API now always sets up 'off_session' and ignores this value. It is still accepted, so existing requests keep working; leave it out of new code.

Integration notes

No change is required. The setting comes from the billing API; your integration never chooses one.

@flopay/shared adds CheckoutSession.futureUse (CardSetupFutureUse, reported on purchase and setup sessions) and CheckoutSession.futureUseUnsupported (FutureUseUnsupportedMethod[]), the FutureUseUnsupportedMethod, FutureUseSessionFields and FutureUseSurface types, and resolveSetupFutureUsage, the helper every Stripe payment form in the SDK uses to read the setting. Existing code that reads CheckoutSession needs no change.

v1.10.6 - Saved payment method filters use the billing API's method types #

The saved payment method list filter in @flopay/shared now takes the method types the billing API accepts, and saved methods can carry their method type and display label.

The @flopay/shared types for saved payment methods now match the billing API's saved payment method list (GET /v1/payment-methods). The list filter takes a method type such as apple_pay, rather than a family such as wallet, and each saved method can report its own method type. An Apple Pay method and a Google Pay method can now be told apart.

What changed

• List filter. ListSavedPaymentMethodsQuery.type is now a SavedPaymentMethodListType: card, paypal, apple_pay, google_pay, sepa_debit or us_bank_account. SAVED_PAYMENT_METHOD_LIST_TYPES lists every value. Leaving type out still lists every saved method.
• Method type and display label. Both saved method display types gain optional methodType and displayLabel, as the billing API returns them. For a card, methodType is card and displayLabel is null.
• Family names. SavedPaymentMethodFamily and SAVED_PAYMENT_METHOD_FAMILIES are added for grouping saved methods (card, wallet, paypal, apm). The type on each saved method is still its family.
• Deprecations. SavedPaymentMethodType, SAVED_PAYMENT_METHOD_TYPES and the label on non-card saved methods are deprecated. They still work, with the same values.
• Documentation. The @flopay/react README Errors table now lists payment_method_setup_unavailable (retryable: false).

Integration notes

• A list filter of { type: 'wallet' } or { type: 'apm' } no longer compiles. The billing API has always rejected these values, so only the type changes. Filter by apple_pay, google_pay, sepa_debit or us_bank_account instead.
• To group saved methods by family, use SavedPaymentMethodFamily and SAVED_PAYMENT_METHOD_FAMILIES in place of the deprecated SavedPaymentMethodType and SAVED_PAYMENT_METHOD_TYPES.
• To label a wallet, PayPal or alternative method, read displayLabel and fall back to label. For a card, keep building the label from brand and lastFour.
• No other change is needed. Existing code that uses the deprecated names keeps compiling.

v1.10.5 - SDK READMEs explain how to choose and upgrade a release #

The @flopay/js and @flopay/react installation guides now explain how to pick one published version, keep @flopay/* packages aligned, and check the release notes before upgrading.

The Installation sections of the @flopay/js and @flopay/react READMEs now explain how to choose and upgrade an SDK release. This is a documentation change only: checkout behavior, exports and types are unaffected.

What changed

• The @flopay/js README has a new Choosing and upgrading a release section under Installation.
• The @flopay/react README adds the same upgrade guidance to its Installation section.
• Both point to the SDK changelog for each release's changes and integration guidance.

Integration notes

No code changes are needed. When you upgrade:

• Read the SDK changelog for the target release first.
• Use the same released version for every @flopay/* package you install directly, and commit the resulting lockfile. You don't need to add packages that are already installed as dependencies.
• Confirm that the version is available on npm for each package you are updating. A merged change is not installable until its release is published. If the exact version isn't available yet, wait for it rather than mixing versions or installing from a repository branch.

v1.10.5 - SDK README explains how releases are published #

The SDK repository README now describes how releases are versioned and published, and how to confirm a version is available before upgrading.

The SDK repository README has a new Releases section. It explains that each release publishes @flopay/js, @flopay/react, @flopay/node and @flopay/shared together at the same version, and that a merged change is not available to install until its release has been published. This change does not affect SDK behavior.

Integration notes

No code changes are needed. Before you upgrade, confirm that the exact version you want is published on npm, and check the SDK changelog for the changes in that release and any integration actions.

v1.10.4 - Payment-method setup is laid out like checkout #

The save-a-payment-method form now offers wallets and alternative methods the way checkout does, above the card form, and leaves out a method the provider cannot offer.

The React payment-method setup component now draws wallets and alternative payment methods with the same components as the checkout component, so a customer sees the same form whether paying or saving a method.

What changed

• Order. Wallets come first, then PayPal, then one tile per alternative method, then an or add a card rule and the hosted card form. Previously the card form came first.
• Apple Pay. Wallets are requested the way checkout requests them, so Apple Pay is offered wherever checkout offers it. Previously it appeared only in Safari with a card already in Wallet.
• Alternative methods are tiles. A method such as SEPA Direct Debit is a tile that opens its form and a Save … button. The tile appears once the provider confirms it can render the method.
• Unavailable methods are left out. A wallet the device does not have, or a method the provider does not support in the session currency (SEPA Direct Debit outside EUR, for example), is not drawn and onError is not called. Previously a save button could appear with no form above it.
• New error code. When no advertised method can be offered at all, onError receives payment_method_setup_unavailable with retryable: false.

Integration notes

No change is required. The props, callbacks and the methods offered are the same: the form still renders exactly what the setup session lists in advertisedPaymentMethods.

If your tests click [data-flopay-payment-method-save] for an alternative method, open that method's tile first ([data-testid="flopay-stripe-method-button-<method>"]).

To offer SEPA Direct Debit, send the customer's currency when you create the setup session.

v1.10.3 - SDK updates include matching release notes #

Published SDK changes carry their own version and public release notes.

SDK updates now arrive with matching package versions and release notes, helping integrators identify the changes included in an upgrade. Existing integrations require no changes.

v1.10.2 - FloPayPaymentMethodSetup renders real setup sessions #

FloPayPaymentMethodSetup now reads the methods a setup session advertises, so customers can add and replace saved cards and other payment methods again.

FloPayPaymentMethodSetup works with real setup sessions again. In 1.10.0 and 1.10.1 it looked for a setup session's methods in the purchase-checkout gateways block, which lists nothing on a setup session. Every real session was rejected with "this setup session advertises no payment method" (NoAdvertisedPaymentMethods) before the card form mounted, so customers could not add or replace a saved card or any other payment method.

What changed

• The component builds its method list from the session's advertisedPaymentMethods only, and never from gateways:
  • a card entry mounts the hosted card form;
  • a Stripe wallet or apm entry renders that method with that entry's own publishableKey;
  • a paypal entry (paypal_vaulted) renders the PayPal vault flow, using the entry's key as the client id and the entry's environment.
• A session without advertisedPaymentMethods (an older billing API) renders the card form only, exactly like FloPayCardSetup. An empty list still reports NoAdvertisedPaymentMethods.
• Unknown families and types, and wallets or alternative methods from a provider other than Stripe, are skipped without an error. When the same method is listed twice, the first entry wins.
• Stripe wallets and alternative methods use only the currency the setup-session read carries. The SDK no longer substitutes USD. When the read carries no currency they are not rendered, and the card form and PayPal are unaffected. A session that advertises only Stripe methods then has nothing to render: it reports NoAdvertisedPaymentMethods with a message that names those methods and the missing currency.
• A wallet, alternative method or PayPal that fails for good no longer ends the setup. That method is removed, the card form and the other methods stay mounted, and onError reports retryable: true while another method is still usable. It reports retryable: false only when the failed method was the last one left. A failure the method itself reports as retryable is passed through unchanged.
• @flopay/js session reads now carry advertisedPaymentMethods exactly as the billing API sends it.

Developer notes

• payment_method_setup_load_failed is now retryable: true while another advertised method is still usable. It used to be retryable: false every time. Keep the setup open on a retryable error, as you already do for the card form.
• @flopay/shared types each advertised entry as AdvertisedPaymentMethod, and CheckoutSession.advertisedPaymentMethods replaces CheckoutSession.savableMethods. savableMethods and AdvertisedSavableMethod are removed. The billing API never filled savableMethods, so no integration could rely on its value, but code that names either one must move to the new names.
• When a setup-session read carries no currency, the setup shows the card form and PayPal only.
• FloPayCardSetup and @flopay/react/card-setup are unchanged.