FloPay SDK Changelog

v1.11.6 - Vue 3 SDK #

The new @flopay/vue package lets a Vue 3 application embed Flopay checkout, card setup, saved payment methods, wallets and PayPal the way a React application does.

@flopay/vue is a new package for Vue 3.3 and later. A Vue application can now embed the same checkout surfaces as a React application: the provider, the all-in-one checkout, card setup, payment method setup, the one-click automatic payment button, the split card form, vault card fields, the PayPal button, wallets and local payment methods. The methods it offers are the ones the checkout session advertises. It ships on the same version line as the other Flopay packages.

What changed

• New package. @flopay/vue has a root entry plus @flopay/vue/card-setup and @flopay/vue/payment-method-setup entries, and a peer dependency on vue >=3.3.0.
• Same names as React. Every component keeps the name of its @flopay/react counterpart, and each React hook has a Vue composable with the same name, including useCheckout. The package README has a side-by-side React and Vue table.
• Vue conventions. Callback props that only notify, such as onComplete, onDecline and onError, are Vue events (@complete, @decline, @error). Custom layouts are slots. Composables return refs or reactive objects.
• Server rendering. Importing the package and rendering its components on the server does not touch window.
• Card security check. Like React since 1.11.5, every Vue card surface mounts the card form when the billing API asks for a security check before card details can be entered: the split card form, the checkout, card setup and payment method setup. VaultCardFields takes verificationRequired. The split card form also recovers its card form from /vault/capture when the session has no embedded form, as React does, including for Worldpay sessions.
• Shared helpers. @flopay/shared now exports the helpers both UI packages use: invokeMerchantCallback, projectFloInstrument, detectPayPalEnvironment, classifyExternalMethodFailure, buildExternalMethodRecoveryMessage, readSetupAdvertisement, hasServerSideCardGateway and canRecoverHostedCardForm. @flopay/js adds completeSavedCardNextAction for the saved-card verification step. React behaviour is unchanged.
• React bundle size. A React checkout bundle is about 2 KB larger before compression and less than 0.5 KB larger after Brotli compression. The checkout logic React now shares with Vue takes parameters, and that costs bytes. The bundle contains no Vue code. A reference React checkout measures 350,109 bytes raw and 83,428 bytes after Brotli compression. Its size limits move to 350,200 and 83,500 bytes. The gzip limit is unchanged.

Known differences from React

This first release of @flopay/vue takes every prop of its React counterpart, but some behaviour still differs from React. The remaining work is tracked in #451 and #452 and will ship in later releases.

• Stripe PayPal option (#451). Not yet in Vue: the buyer-identity fallback panel, the switch React makes when the PayPal pop-up is blocked, "Try PayPal again", the processing overlay and its telemetry, the PayPal sub-account group, and the fallback when Stripe's list leaves out PayPal.
• Split card form and checkout (#452). Apple Pay, Google Pay and local payment methods confirm without the form's own payment request. A "PayPal redirect required" answer shows "PayPal is not available." The inline session is not refreshed after onBeforeButtonClick changes it. The PayPal button gets no technical-failure recovery. A failed payment status is not re-read before it is reported. There are also smaller differences in the PayPal button, saved payments, debug panels, the wallet row and telemetry.
• onBeforeButtonClick after a Stripe PayPal redirect. When the buyer comes back from an approved PayPal redirect, Vue calls onBeforeButtonClick once more to recover the account details. React reuses the details from the original click instead.

Developer notes

Install @flopay/vue alongside vue 3.3 or later. No change is required for React, JavaScript or Node integrations.

v1.11.6 - An unavailable card-form security check is reported as a vault load failure #

When the secure card form reports that its security check is unavailable before the buyer submits, the SDK now records a vault load failure instead of a buyer-side state change, so outage monitoring can see it.

When the card-form security check is on, the secure card form can report an error before the buyer submits. Until now, the SDK recorded every such error as a lifecycle state change, whether the buyer's own check had failed or the check itself was unavailable. An unavailable check therefore never appeared as a vault load failure, so monitoring could not tell a buyer retrying from an outage. This release uses the cause the card form reports to tell the two apart.

What changed

• The card form's reported cause decides the classification. For an error the card form reports before the buyer submits, while the security check is on, the SDK reads the optional failureOutcome on the card form's error message and matches it exactly:
  • verification_failed or verification_expired: the buyer's own check failed or expired. It is still recorded as operation.state_transition at vault_mount.
  • No failureOutcome: recorded as operation.state_transition at vault_mount, exactly as before.
  • verification_unavailable, or any other value: recorded as a technical_error with code VAULT_LOAD_FAILED at vault_mount, so outage alerting counts it.
• Nothing changes for buyers. For every cause, the error still appears in the card form's error area and through onError, the buyer's other entries stay in place, and nothing reloads or submits on its own.
• Other errors are unchanged. Errors after the buyer submits keep VAULT_SUBMIT_FAILED, and card forms without the security check keep VAULT_LOAD_FAILED whatever the cause.
• No new telemetry field. The cause only selects the classification. It is never sent to telemetry or added to Sentry breadcrumbs, and VAULT_LOAD_FAILED still carries no reason.

Developer notes

No change is required for checkout integrations, and public types are unchanged.

v1.11.5 - Card entry keeps loading automatically when the card-form security check is on #

When the billing API asks for a security check before card details can be entered, the SDK now loads the secure card form automatically in every built-in card layout instead of failing to load it.

Flopay is adding an automatic security check that runs before the secure card form issues card-entry credentials in production. When the check applies, the billing API can send a vault block that describes the check instead of ready-made card form markup. Earlier SDK releases treat that block as having no card form to mount, so the card form does not load. This release loads the card form automatically in that case, in the same place and at the same moment as today, with no extra click or card-selection step.

What changed

• The card form loads with the check in place. When a vault block has verification.required set and no html, the SDK frames the billing API's secure card form for the checkout session. The check runs inside the card area, then the card form appears in the same frame. A block that carries html is used exactly as before.
• A refused card-form request is a state, not an error. When the billing API answers a card-form request with 403 and the code verification_required, PaymentAPI.getVaultCapture resolves a vault block with verification.required: true instead of rejecting. It makes one request and does not retry. Other refusals, including other 403 codes, 404, 429 and 503, behave as before.
• Every built-in card layout is covered, with no new step. This includes the checkout's default layout, where the card form opens on load, and its buttons layout, where it opens at the existing card option, as well as SplitCardForm, card setup, payment-method setup with card, and Worldpay-routed card checkout. Saved cards and wallets such as Apple Pay and Google Pay do not wait for the check.
• Failures stay in the card area. If the check fails, expires or is unavailable, the message appears in the card form's error area and through onError. The buyer's other entries stay in place, and nothing reloads or submits on its own. Going back and choosing card again loads the form once more.
• Theme, field order, submit label, resizing and 3D Secure keep working across the move from the check to the card form. Unless the vault block names another origin, the frame only accepts messages from the billing API's origin, and it still checks the vault block's message token when the block carries one.
• No check data in telemetry. The check's site key and challenge data, the session nonce and the card form address are never sent to telemetry or Sentry breadcrumbs. An error the card area reports before the buyer submits, while the check is on, is recorded as a lifecycle state change rather than a vault load failure.
• New shared helpers. @flopay/shared exports resolveVaultMountOptions(), which turns a vault block into card-capture mount options, and isMountableVaultBlock(). VaultCaptureBlock gains an optional verification field.

Developer notes

No change is needed for integrations that use the React components. An integration that mounts the card form itself with flopay.cardCapture() should pass the vault block, together with the billing API URL, checkout session ID and session nonce, to resolveVaultMountOptions() and mount the options it returns, rather than mounting vault.html directly. A block with html resolves to the same mount as before, and a block with verification.required and no html resolves to the secure card form for that session. Check a block with isMountableVaultBlock() rather than testing vault.html, including a block returned by PaymentAPI.getVaultCapture after a 403 verification_required.

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.