FloPay SDK Changelog

v1.8.9 - Checkout session metadata #

Flopay SDK 1.8.9 lets developers attach typed, non-sensitive metadata when creating a checkout and read the preserved snapshot from session responses.

Flopay SDK v1.8.9 lets developers attach non-sensitive string metadata to a checkout session through the supported TypeScript APIs. The metadata travels with the checkout from creation and is available as an immutable snapshot on session responses, without custom REST requests or type augmentation.

What changed

• @flopay/shared now exports CheckoutMetadata, a Record<string, string> type, and adds the optional nullable checkoutMetadata field to public checkout creation types.
• @flopay/js, @flopay/node, and @flopay/react forward supplied metadata unchanged through redirect, retrying, inline, and detached session creation. Detached checkout sends it once on the initial shell request, not on later catalog or buyer claims.
• Session responses expose the returned snapshot as checkoutMetadata, including on normalized results and their nested session.
• React treats metadata as part of the logical checkout identity, so a material change creates a new session while key-order-only changes do not. Raw keys and values are not written to the persistent session cache.
• Backend metadata validation failures retain their structured FloPayError code, message, and HTTP status in browser, React, and Node flows.

Why it matters

Merchants can associate their own order, campaign, or integration context with a checkout using the SDK's typed public contract. That context remains attached to the checkout lifecycle without being mixed into provider-specific metadata.

Developer notes

• Upgrade the @flopay/* packages you use to 1.8.9 together.
• Pass only non-sensitive string values in checkoutMetadata. The backend remains the sole runtime authority for key, value, count, and payload limits.
• Omitting checkoutMetadata or passing null leaves it absent from session reads; passing {} preserves and returns an empty map.
• checkoutMetadata is separate from the existing legacy session metadata field and cannot be edited after checkout creation.
• Existing integrations that omit the field require no migration.