@flopay/react 1.13.5 → 1.14.0

package/README.md

@@ -139,6 +139,40 @@ Direct PayPal never hides its button behind a FloPay identity step: after approv
 
 **Initialization recovery.** A Direct PayPal startup failure hides PayPal, waits one second, and remounts once, without creating a session, intent, or charge; other payment methods stay usable throughout. If Stripe-rendered PayPal is also available, it takes over during recovery. If both attempts fail in a mixed checkout, PayPal stays hidden and neither `onError` nor `onDecline` fires. In a PayPal-only checkout the component shows an accessible retrying status, then a **Retry PayPal** button, and calls `onError` once with `paypal_init_timeout`.
 
+**Buyer cancel (`onCancel`).** `FloPayCheckout`, `SplitCardForm` and `DirectPayPalButton` accept an optional `onCancel?: (event: FloPayPaymentCancelEvent) => void`. It is called once per click when the buyer closes the PayPal pop-up, or returns from PayPal's app switch, without approving. The `FloPayPaymentCancelEvent` is `{ status: 'cancelled', sessionId, provider: 'paypal', paymentMethodType }`: `sessionId` is the attempt's session (the one your `onBeforeButtonClick` patch returned, otherwise the checkout's), and `paymentMethodType` is `paypal_vaulted` when the session advertises an `order` or `setup_token`, otherwise `paypal`.
+
+- It is never called for an approval, a decline (that stays `onDecline`), a blocked pop-up, a load, render or eligibility failure, the reconciliation timeout, or a click your `onBeforeButtonClick` stopped. A repeated or stale cancel for the same click is ignored.
+- It covers the direct PayPal button only (sessions with `gateways.paypal`). Stripe-rendered PayPal does not report it.
+- Nothing else changes: the PayPal button still remounts for the next click and `onDecline` is untouched. If you don't pass it, checkout behaves exactly as before, and a callback that throws does not break the button.
+
+A "Didn't work? Pay another way" prompt that moves the buyer to the card form:
+
+```tsx
+import { FloPayCheckout, type FloPayPaymentCancelEvent } from '@flopay/react';
+import { useRef, useState } from 'react';
+
+function Checkout({ sessionId, nonce }: { sessionId: string; nonce: string }) {
+  const [cancelled, setCancelled] = useState<FloPayPaymentCancelEvent | null>(null);
+  const cardFormRef = useRef<HTMLDivElement>(null);
+
+  return (
+    <>
+      {cancelled && (
+        <div role="status">
+          Didn't work? Pay another way.{' '}
+          <button type="button" onClick={() => cardFormRef.current?.focus()}>
+            Pay by card or Google Pay
+          </button>
+        </div>
+      )}
+      <div ref={cardFormRef} tabIndex={-1}>
+        <FloPayCheckout sessionId={sessionId} nonce={nonce} onCancel={setCancelled} />
+      </div>
+    </>
+  );
+}
+```
+
 #### Server-side card gateways (Worldpay)
 
 The billing API can route hosted and eligible saved cards to an approved Worldpay Corporate Gateway, processed entirely server-side. Your checkout code does not change:
@@ -568,6 +602,7 @@ export function ComposedCheckout({ session, nonce }: { session: CheckoutSession;
 | `telemetry` | `boolean?` | Set `false` to opt out of operational telemetry |
 | `onComplete` | `(result: PaymentResult) => void` | Payment succeeded or was authorized |
 | `onDecline` | `(decline: DeclineEvent) => void` | A payment was declined or authentication failed. The event carries `sessionId` when a session exists |
+| `onCancel` | `(event: FloPayPaymentCancelEvent) => void` | The buyer closed or left the direct PayPal button's PayPal window without approving. Once per click; never for an approval, decline or technical failure |
 | `onError` | `(error: FloPayError) => void` | A checkout error occurred |
 | `onSessionCompleted` | `(successUrl: string) => void` | The session was already completed |
 | `onButtonClick` | `(method: CheckoutButtonMethod) => void` | A payment method button was clicked |
@@ -664,6 +699,7 @@ Also accepts every standard `button` attribute, such as `onClick`, `disabled`, a
 | `onBuyerIdentityReady` | `(identity) => MaybePromise<void>` | Attach a buyer identity collected by the form; `FloPayCheckout` wires its late-buyer claim here |
 | `onTokenizedBody` | `(body: TokenizedBody) => void` | Take over non-card backend submission yourself |
 | `onComplete` / `onDecline` / `onError` | callbacks | Checkout outcomes |
+| `onCancel` | `(event: FloPayPaymentCancelEvent) => void` | The buyer left the direct PayPal button's PayPal window without approving; see the PayPal section above |
 | `directPaypal` | `object?` | Direct PayPal client configuration when wiring PayPal manually; `FloPayCheckout` resolves it from `gateways.paypal` |
 | `showApplePay` / `showGooglePay` | deprecated | Superseded by the session's `enabledPaymentMethods` |
 
@@ -680,6 +716,7 @@ Also accepts every standard `button` attribute, such as `onClick`, `disabled`, a
 | `approvalPresentation` | `PayPalApprovalPresentation?` | Billing-API-advertised approval mode |
 | `session` | `CheckoutSession \| null` | Backing session; its advertised values are authoritative |
 | `onComplete` / `onDecline` | callbacks | Payment outcomes |
+| `onCancel` | `(event: FloPayPaymentCancelEvent) => void` | The buyer closed or left PayPal without approving; once per click |
 | `onTechnicalFailure` | callback | Post-click technical failures, including `popupBlocked` |
 
 ### Types
@@ -703,6 +740,7 @@ Also accepts every standard `button` attribute, such as `onClick`, `disabled`, a
 | `VaultCardFieldsProps` | Props for `VaultCardFields` |
 | `CheckoutState` | `session`, `loading`, `error`, `claimPending?` |
 | `DeclineEvent` | `method`, `message`, `code?`, `declineCode?` |
+| `FloPayPaymentCancelEvent` | Buyer left the direct PayPal button without approving: `status: 'cancelled'`, `sessionId`, `provider: 'paypal'`, `paymentMethodType` (`paypal` or `paypal_vaulted`) |
 | `BeforeButtonClickEvent` | `method`, `sessionId?`, `createSession?` |
 | `CheckoutButtonMethod` | The payment method a button represents |
 | `InlineSessionDraft` | Draft accepted by `FloPayCheckoutProps.createSession` |