@flopay/react 1.3.2 → 1.3.4

package/README.md

@@ -187,6 +187,17 @@ the entire integration change — no SDK redeploy or consumer code update is
 required. Wallets only render on supported devices regardless of dashboard
 state (Apple Pay on Safari/macOS/iOS, Google Pay on Chrome).
 
+In `layout="buttons"`, the **Credit / Debit Card** button always opens the
+inline card form. External wallets and PayPal keep their own lifecycle:
+buyer cancellation silently returns to the payment-method chooser with all
+eligible options available, while post-click technical failures, popup
+blocking, or a provider surface returning focus without a terminal callback
+restore the chooser, focus a visible retry control for the failed method, show safe method-specific copy such as
+`We couldn't open Google Pay. Try again or choose another payment method.`, and
+call `onError` with a structured `FloPayError`. Passive pre-click load or
+eligibility failures still collapse only the unavailable method and do not show
+a checkout error.
+
 Toggle the whole Stripe region or the PayPal region independently with the
 two gateway-level props:
 
@@ -329,6 +340,33 @@ Skip the backend API route — create the session directly in the component:
 
 The component POSTs to the billing API, gets the full session back, and renders the form — zero backend code needed.
 
+That create POST sends a stable `Idempotency-Key` header automatically whenever a
+secure RNG is available, so a timeout or lost response never mints a second
+session. `FloPayCheckout` already coalesces concurrent mounts (StrictMode
+double-mount, Suspense remount, navigation flicker) into a single create, and
+rerenders during an in-flight create do **not** replace the key. You normally
+don't need to think about it.
+
+To control the key yourself — for example to keep it stable across your own
+server retries — pass `idempotencyKey` on `createSession`:
+
+```tsx
+<FloPayCheckout
+  createSession={{
+    /* … */
+    idempotencyKey: `checkout:${orderId}`, // one logical checkout; never reuse for a new purchase
+  }}
+/>
+```
+
+The key must be non-empty and at most 255 characters; an invalid value throws a
+`FloPayError('validation_error')` before any request. Omit it and the SDK
+generates a fresh cryptographically random key per logical create when a secure
+RNG is available; without one it omits the header, and a merchant-supplied
+`idempotencyKey` stays the way to remain idempotent. See the
+[`@flopay/js` idempotency docs](../js/README.md#idempotent-checkout-creation)
+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.