FloPay SDK Changelog

v1.3.1 - Client-side postcode validation before card capture #

Checkout now validates the billing postcode against the buyer's selected country before the card is captured, blocking a missing or malformed postcode with a clear, country-specific message. New public postcode helpers ship in @flopay/shared, and multi-message validation errors from the billing API now surface their real reason.

FloPay SDK v1.3.1 catches a missing or malformed billing postcode before the card is captured, on both the card checkout paths. When AVS collection is enabled, the split card form now checks the postcode format against the buyer's selected country and shows an inline, country-specific message with the expected shape, so shoppers fix the field up front instead of failing later in the charge. Countries with no postal system are never blocked.

What changed

• The split card form validates the postcode format against the live selected country before capturing the card. A supported country with a missing or malformed postcode blocks submit and shows an inline message with the expected format — for example "Enter a valid ZIP Code (e.g. 12345 or 12345-6789)", or "ZIP Code is required" when the field is left empty.
• Countries that have no postal system (or that aren't recognised for postcode validation) keep the field optional: empty and format checks are skipped, so those buyers are never blocked.
• The same country-aware rules the billing API applies are now used on the client, so a postcode accepted in the browser is accepted server-side.
• Error messages returned by the billing API as a list (one entry per failed rule) now surface their real, combined reason instead of collapsing to a generic failure message.

Why it matters

• Buyers get immediate, specific feedback on the postcode field and correct it before payment, rather than hitting a late decline after the card is entered.
• Client and server agree on what a valid postcode looks like for each country, reducing avoidable failed payments and mismatched validation.
• When an account-level validation error does occur, integrators and operators see the actual reason, making failures faster to diagnose.

Developer notes

• Upgrade @flopay/js, @flopay/react, @flopay/node, and @flopay/shared together to 1.3.1.
• @flopay/shared now exports three country-aware postcode helpers you can use in your own UI: isPostalCodeSupported(country), isValidPostalCode(country, postalCode) (fails open for countries with no postcode), and getPostalCodeExample(country) for a sample of the expected format.
• The new postcode validation is automatic in SplitCardForm when AVS collection is enabled — no configuration changes are required to adopt it.
• @flopay/shared now carries one small runtime dependency (validator), installed transitively when you depend on the package. No action is needed beyond upgrading.
• No public billing API request or response shapes have changed in this release.