@flopay/react 1.8.8 → 1.8.9

package/README.md

@@ -466,6 +466,7 @@ Skip the backend API route — create the session directly in the component:
     account: { userId: 'user_1' }, // email and name are collected in checkout
     successUrl: '/success',
     cancelUrl: '/cancel',
+    checkoutMetadata: { merchantOrderId: 'order-123', campaign: 'summer' },
   }}
   onComplete={(result) => window.location.href = '/success'}
 />
@@ -475,6 +476,14 @@ The component creates a lightweight shell, attaches the catalog immediately,
 renders every otherwise-eligible method, and identifies the buyer later from
 the selected method or its fallback — zero merchant backend code needed.
 
+`checkoutMetadata?: Record<string, string> | null` is sent unchanged on that
+initial shell request and never repeated in the catalog or late-buyer claim.
+Omission keeps the previous request shape; explicit `null` and `{}` remain
+distinct wire values. Returned metadata is available on the normalized result
+and its `data.session`. Backend validation errors retain their structured
+`FloPayError` code, message, and HTTP status; React does not duplicate backend
+size or length limits.
+
 #### Authorisation-only checkout
 
 Set `captureMethod: 'manual'` in the same `createSession` draft for an eligible
@@ -518,8 +527,11 @@ mounts (StrictMode double-mount, Suspense remount, or navigation flicker) share
 both the session create and the auto-mode payment attempt, so one purchase cannot
 fan out into multiple creates or charges.
 
-Logical checkout identity is based on the merchant, buyer, cart/pricing, and
-coupons. Checkout-mode changes, refreshed payment tokens, and analytics/UTM prop
+Logical checkout identity is based on the merchant, buyer, cart/pricing,
+coupons, and checkout metadata. Metadata keys are canonicalized for identity,
+so key-order-only changes reuse the current session while a material metadata
+change creates a new one. Raw metadata is not stored in the inline-session
+cache. Checkout-mode changes, refreshed payment tokens, and analytics/UTM prop
 churn do not rotate the key while that purchase is active. A different cart or
 buyer gets a different key; an email-less buyer is separated by `account.userId`.
 
@@ -545,7 +557,12 @@ for the full contract.
 
 Session-level `currency` is now **required**. The backend (#760) enforces `@IsNotEmpty` on the field; the SDK pre-validates and throws `FloPayError({ type: 'validation_error', code: 'CurrencyRequired' })` before issuing the request when neither the session nor any item/subscription/product carries a currency. Pass `currency` at the top of `createSession` (preferred), or rely on the legacy fallback to the first item/subscription/product `currency`.
 
-When you use `onBeforeButtonClick` with `createSession`, any returned `InlineSessionPatch` is merged into the draft session params before the selected buttons-layout flow continues. That lets you add tracking data or update account fields just in time without pre-creating a separate backend session.
+When you use `onBeforeButtonClick` with `createSession`, any returned
+`InlineSessionPatch` is merged into the draft session params before the selected
+buttons-layout flow continues. That lets you add tracking data or update account
+fields just in time without pre-creating a separate backend session. A returned
+`checkoutMetadata` map replaces the prior map as a whole; return `null` to clear
+it before creation.
 
 ### Detached session creation (default)