FloPay SDK Changelog

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.