FloPay SDK Changelog

v1.11.4 - SDK packages use newer Stripe and PayPal libraries #

The Flopay JavaScript, React and Node SDKs now require newer releases of the Stripe and PayPal libraries they install, all within the same major versions. No integration changes are needed.

The Flopay SDK packages now require newer releases of the Stripe and PayPal libraries they install with them, so new installs and upgrades use those releases. Every update stays within the library's current major version.

What changed

• @flopay/js requires @stripe/stripe-js ^9.17.0 (previously ^9.8.0).
• @flopay/react requires @stripe/stripe-js ^9.17.0 (previously ^9.8.0), @stripe/react-stripe-js ^6.12.0 (previously ^6.6.0) and @paypal/paypal-js ^10.1.0 (previously ^10.0.0).
• @flopay/node requires stripe ^22.6.2 (previously ^22.2.1).
• @flopay/react still supports React 18 and later.
• The tools used to build and test the SDK were also updated. They are not installed with the SDK packages.

Integration notes

No code changes are needed. The SDK's public exports, props and documented configuration are unchanged.

If your application also installs any of these libraries directly, keeping it at or above the version listed above lets your package manager install a single copy shared with the SDK.

v1.11.3 - Bounded cause for unusable wallet confirmation results #

When a wallet confirmation such as Apple Pay or Google Pay returns a result the SDK cannot use, the technical-error telemetry event now says what shape the result had.

When a wallet confirmation such as Apple Pay or Google Pay finishes with a result the SDK cannot use, the technical-error telemetry event now carries a bounded reason. Operators can tell a confirmation that returned nothing apart from one that returned an unexpected value, without collecting the provider's response or any payment details.

What changed

• Bounded cause for unusable wallet confirmation results. A wallet confirmation reported with errorCode CONFIGURATION_INVALID and failureCategory invalid_response now carries one reason, whether the result arrived on time or late:
  • confirmation_result_missing: the confirmation returned no result.
  • confirmation_result_not_object: the confirmation returned a value that is not a result object.
  • confirmation_result_unconfirmed: the confirmation returned an object with neither an error nor a confirmed payment or setup.
• Codes are unchanged. errorCode, failureCategory and the operation outcome stay the same. Rejected confirmations and provider error results never carry these three values, and any other reason value is still reported as unknown.

Developer notes

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

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.