flintn-checkout 0.0.11 → 0.0.13

package/README.md

@@ -18,7 +18,7 @@ Full checkout UI rendered inside a single iframe. Includes card form, express pa
 import { useFlintNPayment } from 'flintn-checkout/react';
 
 function Checkout() {
-  const { containerRef, isReady, paymentResult, error } = useFlintNPayment({
+  const { containerRef, isReady, paymentResult, events, error } = useFlintNPayment({
     config: {
       clientSessionId: 'your_client_session_id',
     },
@@ -29,6 +29,12 @@ function Checkout() {
         console.log('Payment failed:', result.error);
       }
     },
+    onEvent: (event) => {
+      // Per-attempt analytics — fires for every payment attempt outcome
+      // (initiated, soft/hard decline, 3DS, cancel, network error, success)
+      // and for UI navigation in the LIST and RADIO variants (form entered/exited).
+      console.log('Event:', event.type, event.event);
+    },
   });
 
   return (
@@ -55,6 +61,9 @@ const payment = createFlintNPayment({
       console.log('Payment failed:', result.error);
     }
   },
+  onEvent: (event) => {
+    console.log('Event:', event.type, event.event);
+  },
   onReady: () => {
     console.log('Widget ready');
   },
@@ -88,6 +97,9 @@ payment.mount('#payment-container');
       onPayment: (result) => {
         console.log('Payment result:', result);
       },
+      onEvent: (event) => {
+        console.log('Event:', event);
+      },
     });
 
     payment.mount('#payment-container');
@@ -96,6 +108,114 @@ payment.mount('#payment-container');
 </html>
 ```
 
+## Events — terminal vs per-attempt
+
+The SDK fires two streams of events. Use the one that fits your use case:
+
+### `onPayment` — terminal (session-final)
+
+Fires **once** when the checkout session reaches a final state. Use this for redirecting, marking the order done, sending receipts, and conversion-failure analytics.
+
+```ts
+onPayment(result: PaymentResult)
+```
+
+Fires when:
+- Payment succeeds → `status: 'PAYMENT_SUCCESS'`
+- Session cannot continue (non-retryable decline, network error, SDK error, missing payment id, 3DS failure) → `status: 'PAYMENT_ERROR'`
+
+**Does not fire** for soft declines, hard declines with a retryable session, or buyer cancellations — the buyer can still try another card or method.
+
+### `onEvent` — per-attempt analytics
+
+Fires for **every payment attempt outcome**, including ones where the session continues. Use for funnel analytics, retry tracking, A/B test instrumentation, fraud signals.
+
+```ts
+onEvent(event: CheckoutEvent)
+```
+
+`CheckoutEvent` is a union of two event kinds, discriminated by `type` (the `isAttemptEvent` / `isUIEvent` guards are also exported):
+
+- `PaymentAttempt` — `type: 'PAYMENT_ATTEMPT_EVENT'`, a payment attempt outcome
+- `PaymentUI` — `type: 'PAYMENT_UI_EVENT'`, card form entered/exited (LIST and RADIO variants)
+
+Every event carries a `timestamp` (epoch ms) and the `clientSessionId`.
+
+For attempt events, the `event` discriminator describes what happened at this step:
+
+| `event` | When | Terminal `onPayment` follows? |
+|---|---|---|
+| `'INITIATED'` | Buyer clicked Pay / Apple Pay / PayPal and validation passed | — |
+| `'THREE_DS_INITIATED'` | Authorize returned `THREE_DS_INITIATED`; 3DS challenge is opening | — |
+| `'AUTHORIZED'` | Authorize succeeded | ✅ `PAYMENT_SUCCESS` |
+| `'SOFT_DECLINE'` | Decline with `decline_type: SOFT_DECLINE` — buyer can retry | only if session is non-retryable |
+| `'HARD_DECLINE'` | Decline with `decline_type: HARD_DECLINE` — card permanently bad | only if session is non-retryable |
+| `'CANCELLED'` | Buyer dismissed Apple Pay sheet / closed PayPal popup / closed 3DS dialog | — |
+| `'NETWORK_ERROR'` | Authorize HTTP failure, SDK crashed, missing token, unknown status | ✅ `PAYMENT_ERROR` |
+
+A terminal `onPayment` event always fires *after* the corresponding `onEvent` for `AUTHORIZED` / `NETWORK_ERROR` / non-retryable declines / 3DS failures.
+
+For UI events (LIST and RADIO variants), `view` is the view that became active:
+
+| `event` | When | `view` |
+|---|---|---|
+| `'FORM_ENTERED'` | Buyer opened the card form ("Credit or Debit Card" button / "Card payment" radio) | `'CARD'` |
+| `'FORM_EXITED'` | Buyer returned to express (back arrow / "Fast checkout" radio) | `'EXPRESS'` |
+
+**Example funnel — soft decline → retry success:**
+
+```
+onEvent   → { event: 'INITIATED',    method: 'PAYMENT_CARD' }
+onEvent   → { event: 'SOFT_DECLINE', method: 'PAYMENT_CARD', code: 'do_not_honor', message: 'Payment declined.' }
+// buyer retries with another card
+onEvent   → { event: 'INITIATED',    method: 'PAYMENT_CARD' }
+onEvent   → { event: 'AUTHORIZED',   method: 'PAYMENT_CARD', paymentId: 'pay_...' }
+onPayment → { status: 'PAYMENT_SUCCESS', data: 'pay_...' }
+```
+
+**Example — Apple Pay buyer cancel (DEFAULT variant):**
+
+```
+onEvent → { event: 'INITIATED', method: 'APPLE_PAY' }
+onEvent → { event: 'CANCELLED', method: 'APPLE_PAY', message: 'Buyer dismissed Apple Pay' }
+// no onPayment — session stays alive, buyer can pick another method
+```
+
+**Example — PayPal popup → 3DS → success:**
+
+```
+onEvent   → { event: 'INITIATED',          method: 'PAYPAL' }
+onEvent   → { event: 'THREE_DS_INITIATED', method: 'PAYPAL', paymentId: 'pay_...' }
+onEvent   → { event: 'AUTHORIZED',         method: 'PAYPAL', paymentId: 'pay_...' }
+onPayment → { status: 'PAYMENT_SUCCESS', data: 'pay_...' }
+```
+
+(Every event also carries `type`, `timestamp`, and `clientSessionId` — omitted above for brevity.)
+
+### `events` (React) — accumulated log
+
+The `useFlintNPayment` hook also exposes `events: CheckoutEvent[]` — every event since mount, useful for rendering a per-attempt UI without wiring `onEvent` manually:
+
+```tsx
+import { isAttemptEvent } from 'flintn-checkout';
+
+const { events } = useFlintNPayment({ ... });
+
+return (
+  <ul>
+    {events.map((e, i) =>
+      isAttemptEvent(e) ? (
+        <li key={i}>[{e.method}] {e.event} {e.code && `— ${e.code}`}</li>
+      ) : (
+        <li key={i}>[UI] {e.event} → {e.view}</li>
+      ),
+    )}
+  </ul>
+);
+```
+
+The list resets when the checkout remounts (e.g. new `clientSessionId`).
+
 ## Container Sizing
 
 The widget auto-sizes to fit its content — you only need to set a width on the container. Height is managed by the SDK and updates automatically as the form changes state (loading, express view, card form, success).
@@ -111,7 +231,8 @@ Do **not** set a fixed `height` on the container — it will leave empty space b
 | Option | Type | Required | Default | Description |
 |--------|------|----------|---------|-------------|
 | `config` | `FlintNConfig` | Yes | — | Checkout configuration |
-| `onPayment` | `(result: PaymentResult) => void` | No | — | Payment result callback (success, error, cancelled) |
+| `onPayment` | `(result: PaymentResult) => void` | No | — | Terminal session result (success / error) |
+| `onEvent` | `(event: CheckoutEvent) => void` | No | — | Per-attempt analytics signal |
 | `onReady` | `() => void` | No | — | Widget loaded and ready |
 | `onError` | `(error: PaymentError) => void` | No | — | SDK initialization error |
 | `debug` | `boolean` | No | `false` | Enable console debug logs |
@@ -131,7 +252,8 @@ Do **not** set a fixed `height` on the container — it will leave empty space b
 |-------|------|-------------|
 | `containerRef` | `RefObject<HTMLDivElement>` | Ref to attach to container element |
 | `isReady` | `boolean` | Widget is loaded and ready |
-| `paymentResult` | `PaymentResult \| null` | Result after payment attempt |
+| `paymentResult` | `PaymentResult \| null` | Result after terminal `onPayment` event |
+| `events` | `CheckoutEvent[]` | Per-attempt event log (accumulated since mount) |
 | `error` | `PaymentError \| null` | SDK error if any |
 
 ---
@@ -142,6 +264,8 @@ Individual PCI-compliant input fields rendered as separate iframes. You control
 
 Each field (card number, expiry, CVV) is a separate iframe. Raw card data never touches your page.
 
+> **Note:** Hosted Fields emits only the terminal `onPayment` event — there is no `onEvent` per-attempt stream. Use Iframe Checkout if you need granular attempt analytics.
+
 **React**
 
 ```tsx
@@ -378,6 +502,68 @@ interface PaymentError {
 }
 ```
 
+### CheckoutEvent
+
+```typescript
+type CheckoutEvent = PaymentAttempt | PaymentUI;
+```
+
+### PaymentAttempt
+
+```typescript
+interface PaymentAttempt {
+  type: 'PAYMENT_ATTEMPT_EVENT';
+  event:
+    | 'INITIATED'
+    | 'THREE_DS_INITIATED'
+    | 'AUTHORIZED'
+    | 'SOFT_DECLINE'
+    | 'HARD_DECLINE'
+    | 'CANCELLED'
+    | 'NETWORK_ERROR';
+  method:
+    | 'PAYMENT_CARD'
+    | 'GOOGLE_PAY'
+    | 'APPLE_PAY'
+    | 'PAYPAL'
+    | 'BANK_ACCOUNT'
+    | 'OTHER';
+  paymentId?: string;       // Set when the backend has minted a payment id (auth response, 3DS, approve)
+  code?: string;            // Processor decline code or internal error code (FNT-EC-*, FORBIDDEN, PAYPAL_ERROR, THREE_DS_FAILED, …)
+  message?: string;         // Translated merchant-facing message for the code
+  timestamp: number;        // Epoch ms, stamped at emit time
+  clientSessionId?: string; // Session the event belongs to
+}
+```
+
+### PaymentUI
+
+```typescript
+interface PaymentUI {
+  type: 'PAYMENT_UI_EVENT';
+  event: 'FORM_ENTERED' | 'FORM_EXITED';
+  view: 'EXPRESS' | 'CARD'; // The view that became active
+  timestamp: number;
+  clientSessionId?: string;
+}
+```
+
+Const-object accessors are also exported if you prefer typed comparisons over string literals:
+
+```ts
+import { PaymentAttemptResult, PaymentMethod, isAttemptEvent } from 'flintn-checkout';
+
+onEvent: (e) => {
+  if (
+    isAttemptEvent(e) &&
+    e.event === PaymentAttemptResult.SOFT_DECLINE &&
+    e.method === PaymentMethod.PAYMENT_CARD
+  ) {
+    analytics.track('soft_decline_card', { code: e.code });
+  }
+}
+```
+
 ### FieldState
 ```typescript
 interface FieldState {
@@ -467,10 +653,24 @@ interface FormStyles {
 The iframe checkout supports three layout variants via `formFields.formVariant`:
 
 - **DEFAULT** — Express payment methods shown above the card form with dividers.
-- **LIST** — Express payment methods shown first; users tap a "Credit or Debit Card" button to navigate to the card form, with a back arrow to return to the express view.
-- **RADIO** — Express payments and the card form are presented as two radio options ("Fast checkout" and "Card payment"). Selecting a radio expands its section and collapses the other. The card payment radio shows accepted card brand logos inline with its label.
+- **LIST** — Express payment methods shown first; users tap a "Credit or Debit Card" button to navigate to the card form, with a back arrow to return to the express view. Toggling emits `FORM_ENTERED` / `FORM_EXITED` UI events.
+- **RADIO** — Express payments and the card form are presented as two radio options ("Fast checkout" and "Card payment"). Selecting a radio expands its section and collapses the other. The card payment radio shows accepted card brand logos inline with its label. Selecting a radio emits `FORM_ENTERED` / `FORM_EXITED` UI events.
+
+LIST and RADIO automatically fall back to the DEFAULT layout when no express payment methods are available, since there's nothing to toggle between (and no UI events fire). The `cardButtonColor`, `cardButtonHoverColor`, and `cardButtonText` style overrides apply only to the LIST variant's "Credit or Debit Card" button.
+
+### Cancel-message behavior across variants
+
+Express buttons (Apple Pay, PayPal) and the 3DS dialog can all be cancelled by the buyer. When that happens, an inline cancel message is shown in the card form **only when the card form is currently visible**:
+
+| Variant | Apple Pay / PayPal cancel | 3DS dialog close |
+|---|---|---|
+| `DEFAULT` | Inline message shown | Inline message shown |
+| `LIST` (EXPRESS view) | No inline message (form hidden) | No inline message |
+| `LIST` (CARD view, after toggle) | Not reachable — cancel originates from EXPRESS view | Inline message shown |
+| `RADIO` (EXPRESS active) | No inline message | No inline message |
+| `RADIO` (CARD active) | Not reachable — cancel originates from EXPRESS view | Inline message shown |
 
-LIST and RADIO automatically fall back to the DEFAULT layout when no express payment methods are available, since there's nothing to toggle between. The `cardButtonColor`, `cardButtonHoverColor`, and `cardButtonText` style overrides apply only to the LIST variant's "Credit or Debit Card" button.
+Every cancellation still emits a `CANCELLED` `onEvent` regardless of variant, so analytics is unaffected.
 
 ## Supported Payment Methods
 

package/dist/index.d.mts

@@ -1,6 +1,8 @@
 declare const EventType: {
     readonly WIDGET_READY: "WIDGET_READY";
     readonly WIDGET_CONFIG: "WIDGET_CONFIG";
+    readonly PAYMENT_ATTEMPT: "PAYMENT_ATTEMPT_EVENT";
+    readonly PAYMENT_UI: "PAYMENT_UI_EVENT";
     readonly PAYMENT: "PAYMENT";
     readonly PAYMENT_SUCCESS: "PAYMENT_SUCCESS";
     readonly PAYMENT_ERROR: "PAYMENT_ERROR";
@@ -45,6 +47,55 @@ interface FlintNConfig {
     styles?: FormStyles;
     successRedirectUrl?: string;
 }
+declare const PaymentMethod: {
+    readonly PAYMENT_CARD: "PAYMENT_CARD";
+    readonly GOOGLE_PAY: "GOOGLE_PAY";
+    readonly APPLE_PAY: "APPLE_PAY";
+    readonly PAYPAL: "PAYPAL";
+    readonly BANK_ACCOUNT: "BANK_ACCOUNT";
+    readonly OTHER: "OTHER";
+};
+type TPaymentMethod = (typeof PaymentMethod)[keyof typeof PaymentMethod];
+declare const PaymentAttemptResult: {
+    readonly INITIATED: "INITIATED";
+    readonly THREE_DS_INITIATED: "THREE_DS_INITIATED";
+    readonly AUTHORIZED: "AUTHORIZED";
+    readonly SOFT_DECLINE: "SOFT_DECLINE";
+    readonly HARD_DECLINE: "HARD_DECLINE";
+    readonly CANCELLED: "CANCELLED";
+    readonly NETWORK_ERROR: "NETWORK_ERROR";
+};
+type TPaymentAttemptResult = (typeof PaymentAttemptResult)[keyof typeof PaymentAttemptResult];
+declare const PaymentUIEvent: {
+    readonly FORM_ENTERED: "FORM_ENTERED";
+    readonly FORM_EXITED: "FORM_EXITED";
+};
+type TPaymentUIEvent = (typeof PaymentUIEvent)[keyof typeof PaymentUIEvent];
+declare const CheckoutView: {
+    readonly EXPRESS: "EXPRESS";
+    readonly CARD: "CARD";
+};
+type TCheckoutView = (typeof CheckoutView)[keyof typeof CheckoutView];
+interface PaymentAttempt {
+    type: typeof EventType.PAYMENT_ATTEMPT;
+    event: TPaymentAttemptResult;
+    method: TPaymentMethod;
+    paymentId?: string;
+    code?: string;
+    message?: string;
+    timestamp: number;
+    clientSessionId?: string;
+}
+interface PaymentUI {
+    type: typeof EventType.PAYMENT_UI;
+    event: TPaymentUIEvent;
+    view: TCheckoutView;
+    timestamp: number;
+    clientSessionId?: string;
+}
+type CheckoutEvent = PaymentAttempt | PaymentUI;
+declare const isAttemptEvent: (e: CheckoutEvent) => e is PaymentAttempt;
+declare const isUIEvent: (e: CheckoutEvent) => e is PaymentUI;
 interface PaymentResult {
     status: 'PAYMENT_SUCCESS' | 'PAYMENT_ERROR' | 'PAYMENT_CANCELLED';
     data?: string;
@@ -61,6 +112,7 @@ interface FlintNPaymentOptions {
     origin?: string;
     config: FlintNConfig;
     onPayment?: (result: PaymentResult) => void;
+    onEvent?: (event: CheckoutEvent) => void;
     onReady?: () => void;
     onError?: (error: PaymentError) => void;
     debug?: boolean;
@@ -178,4 +230,4 @@ declare const validateConfig: (config: {
 }) => void;
 declare const sanitizeToken: (token: string) => string;
 
-export { CheckoutFormVariant, EventType, type FieldChangeEvent, FieldEventType, type FieldOptions, type FieldState, FieldType, type FieldValidationResult, type FieldsValidationResult, type FlintNConfig, type FlintNField, type FlintNFieldInternalCallbacks, type FlintNFields, type FlintNFieldsConfig, type FlintNFieldsOptions, type FlintNPayment, type FlintNPaymentOptions, type FormFields, type FormStyles, type PaymentError, type PaymentResult, type SubmitOptions, type TCheckoutFormVariant, type TEventType, type TFieldEventType, type TFieldType, buildIframeSrc, createFlintNField, createFlintNFields, createFlintNPayment, createIframeElement, parseOrigin, sanitizeToken, validateConfig };
+export { type CheckoutEvent, CheckoutFormVariant, CheckoutView, EventType, type FieldChangeEvent, FieldEventType, type FieldOptions, type FieldState, FieldType, type FieldValidationResult, type FieldsValidationResult, type FlintNConfig, type FlintNField, type FlintNFieldInternalCallbacks, type FlintNFields, type FlintNFieldsConfig, type FlintNFieldsOptions, type FlintNPayment, type FlintNPaymentOptions, type FormFields, type FormStyles, type PaymentAttempt, PaymentAttemptResult, type PaymentError, PaymentMethod, type PaymentResult, type PaymentUI, PaymentUIEvent, type SubmitOptions, type TCheckoutFormVariant, type TCheckoutView, type TEventType, type TFieldEventType, type TFieldType, type TPaymentAttemptResult, type TPaymentMethod, type TPaymentUIEvent, buildIframeSrc, createFlintNField, createFlintNFields, createFlintNPayment, createIframeElement, isAttemptEvent, isUIEvent, parseOrigin, sanitizeToken, validateConfig };

package/dist/index.d.ts

@@ -1,6 +1,8 @@
 declare const EventType: {
     readonly WIDGET_READY: "WIDGET_READY";
     readonly WIDGET_CONFIG: "WIDGET_CONFIG";
+    readonly PAYMENT_ATTEMPT: "PAYMENT_ATTEMPT_EVENT";
+    readonly PAYMENT_UI: "PAYMENT_UI_EVENT";
     readonly PAYMENT: "PAYMENT";
     readonly PAYMENT_SUCCESS: "PAYMENT_SUCCESS";
     readonly PAYMENT_ERROR: "PAYMENT_ERROR";
@@ -45,6 +47,55 @@ interface FlintNConfig {
     styles?: FormStyles;
     successRedirectUrl?: string;
 }
+declare const PaymentMethod: {
+    readonly PAYMENT_CARD: "PAYMENT_CARD";
+    readonly GOOGLE_PAY: "GOOGLE_PAY";
+    readonly APPLE_PAY: "APPLE_PAY";
+    readonly PAYPAL: "PAYPAL";
+    readonly BANK_ACCOUNT: "BANK_ACCOUNT";
+    readonly OTHER: "OTHER";
+};
+type TPaymentMethod = (typeof PaymentMethod)[keyof typeof PaymentMethod];
+declare const PaymentAttemptResult: {
+    readonly INITIATED: "INITIATED";
+    readonly THREE_DS_INITIATED: "THREE_DS_INITIATED";
+    readonly AUTHORIZED: "AUTHORIZED";
+    readonly SOFT_DECLINE: "SOFT_DECLINE";
+    readonly HARD_DECLINE: "HARD_DECLINE";
+    readonly CANCELLED: "CANCELLED";
+    readonly NETWORK_ERROR: "NETWORK_ERROR";
+};
+type TPaymentAttemptResult = (typeof PaymentAttemptResult)[keyof typeof PaymentAttemptResult];
+declare const PaymentUIEvent: {
+    readonly FORM_ENTERED: "FORM_ENTERED";
+    readonly FORM_EXITED: "FORM_EXITED";
+};
+type TPaymentUIEvent = (typeof PaymentUIEvent)[keyof typeof PaymentUIEvent];
+declare const CheckoutView: {
+    readonly EXPRESS: "EXPRESS";
+    readonly CARD: "CARD";
+};
+type TCheckoutView = (typeof CheckoutView)[keyof typeof CheckoutView];
+interface PaymentAttempt {
+    type: typeof EventType.PAYMENT_ATTEMPT;
+    event: TPaymentAttemptResult;
+    method: TPaymentMethod;
+    paymentId?: string;
+    code?: string;
+    message?: string;
+    timestamp: number;
+    clientSessionId?: string;
+}
+interface PaymentUI {
+    type: typeof EventType.PAYMENT_UI;
+    event: TPaymentUIEvent;
+    view: TCheckoutView;
+    timestamp: number;
+    clientSessionId?: string;
+}
+type CheckoutEvent = PaymentAttempt | PaymentUI;
+declare const isAttemptEvent: (e: CheckoutEvent) => e is PaymentAttempt;
+declare const isUIEvent: (e: CheckoutEvent) => e is PaymentUI;
 interface PaymentResult {
     status: 'PAYMENT_SUCCESS' | 'PAYMENT_ERROR' | 'PAYMENT_CANCELLED';
     data?: string;
@@ -61,6 +112,7 @@ interface FlintNPaymentOptions {
     origin?: string;
     config: FlintNConfig;
     onPayment?: (result: PaymentResult) => void;
+    onEvent?: (event: CheckoutEvent) => void;
     onReady?: () => void;
     onError?: (error: PaymentError) => void;
     debug?: boolean;
@@ -178,4 +230,4 @@ declare const validateConfig: (config: {
 }) => void;
 declare const sanitizeToken: (token: string) => string;
 
-export { CheckoutFormVariant, EventType, type FieldChangeEvent, FieldEventType, type FieldOptions, type FieldState, FieldType, type FieldValidationResult, type FieldsValidationResult, type FlintNConfig, type FlintNField, type FlintNFieldInternalCallbacks, type FlintNFields, type FlintNFieldsConfig, type FlintNFieldsOptions, type FlintNPayment, type FlintNPaymentOptions, type FormFields, type FormStyles, type PaymentError, type PaymentResult, type SubmitOptions, type TCheckoutFormVariant, type TEventType, type TFieldEventType, type TFieldType, buildIframeSrc, createFlintNField, createFlintNFields, createFlintNPayment, createIframeElement, parseOrigin, sanitizeToken, validateConfig };
+export { type CheckoutEvent, CheckoutFormVariant, CheckoutView, EventType, type FieldChangeEvent, FieldEventType, type FieldOptions, type FieldState, FieldType, type FieldValidationResult, type FieldsValidationResult, type FlintNConfig, type FlintNField, type FlintNFieldInternalCallbacks, type FlintNFields, type FlintNFieldsConfig, type FlintNFieldsOptions, type FlintNPayment, type FlintNPaymentOptions, type FormFields, type FormStyles, type PaymentAttempt, PaymentAttemptResult, type PaymentError, PaymentMethod, type PaymentResult, type PaymentUI, PaymentUIEvent, type SubmitOptions, type TCheckoutFormVariant, type TCheckoutView, type TEventType, type TFieldEventType, type TFieldType, type TPaymentAttemptResult, type TPaymentMethod, type TPaymentUIEvent, buildIframeSrc, createFlintNField, createFlintNFields, createFlintNPayment, createIframeElement, isAttemptEvent, isUIEvent, parseOrigin, sanitizeToken, validateConfig };

package/dist/index.js

@@ -21,14 +21,20 @@ var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: tru
 var index_exports = {};
 __export(index_exports, {
   CheckoutFormVariant: () => CheckoutFormVariant,
+  CheckoutView: () => CheckoutView,
   EventType: () => EventType,
   FieldEventType: () => FieldEventType,
   FieldType: () => FieldType,
+  PaymentAttemptResult: () => PaymentAttemptResult,
+  PaymentMethod: () => PaymentMethod,
+  PaymentUIEvent: () => PaymentUIEvent,
   buildIframeSrc: () => buildIframeSrc,
   createFlintNField: () => createFlintNField,
   createFlintNFields: () => createFlintNFields,
   createFlintNPayment: () => createFlintNPayment,
   createIframeElement: () => createIframeElement,
+  isAttemptEvent: () => isAttemptEvent,
+  isUIEvent: () => isUIEvent,
   parseOrigin: () => parseOrigin,
   sanitizeToken: () => sanitizeToken,
   validateConfig: () => validateConfig
@@ -39,6 +45,8 @@ module.exports = __toCommonJS(index_exports);
 var EventType = {
   WIDGET_READY: "WIDGET_READY",
   WIDGET_CONFIG: "WIDGET_CONFIG",
+  PAYMENT_ATTEMPT: "PAYMENT_ATTEMPT_EVENT",
+  PAYMENT_UI: "PAYMENT_UI_EVENT",
   PAYMENT: "PAYMENT",
   PAYMENT_SUCCESS: "PAYMENT_SUCCESS",
   PAYMENT_ERROR: "PAYMENT_ERROR",
@@ -51,6 +59,33 @@ var CheckoutFormVariant = {
   LIST: "LIST",
   RADIO: "RADIO"
 };
+var PaymentMethod = {
+  PAYMENT_CARD: "PAYMENT_CARD",
+  GOOGLE_PAY: "GOOGLE_PAY",
+  APPLE_PAY: "APPLE_PAY",
+  PAYPAL: "PAYPAL",
+  BANK_ACCOUNT: "BANK_ACCOUNT",
+  OTHER: "OTHER"
+};
+var PaymentAttemptResult = {
+  INITIATED: "INITIATED",
+  THREE_DS_INITIATED: "THREE_DS_INITIATED",
+  AUTHORIZED: "AUTHORIZED",
+  SOFT_DECLINE: "SOFT_DECLINE",
+  HARD_DECLINE: "HARD_DECLINE",
+  CANCELLED: "CANCELLED",
+  NETWORK_ERROR: "NETWORK_ERROR"
+};
+var PaymentUIEvent = {
+  FORM_ENTERED: "FORM_ENTERED",
+  FORM_EXITED: "FORM_EXITED"
+};
+var CheckoutView = {
+  EXPRESS: "EXPRESS",
+  CARD: "CARD"
+};
+var isAttemptEvent = (e) => e.type === EventType.PAYMENT_ATTEMPT;
+var isUIEvent = (e) => e.type === EventType.PAYMENT_UI;
 var FieldType = {
   CARD_NUMBER: "card-number",
   EXPIRY: "expiry",
@@ -183,6 +218,18 @@ function createFlintNPayment(options) {
         sendConfig();
         options.onReady?.();
         break;
+      case EventType.PAYMENT_ATTEMPT:
+        options.onEvent?.({
+          type: EventType.PAYMENT_ATTEMPT,
+          ...payload
+        });
+        break;
+      case EventType.PAYMENT_UI:
+        options.onEvent?.({
+          type: EventType.PAYMENT_UI,
+          ...payload
+        });
+        break;
       case EventType.PAYMENT:
         options.onPayment?.(payload);
         break;
@@ -629,14 +676,20 @@ function createFlintNFields(options) {
 // Annotate the CommonJS export names for ESM import in node:
 0 && (module.exports = {
   CheckoutFormVariant,
+  CheckoutView,
   EventType,
   FieldEventType,
   FieldType,
+  PaymentAttemptResult,
+  PaymentMethod,
+  PaymentUIEvent,
   buildIframeSrc,
   createFlintNField,
   createFlintNFields,
   createFlintNPayment,
   createIframeElement,
+  isAttemptEvent,
+  isUIEvent,
   parseOrigin,
   sanitizeToken,
   validateConfig

package/dist/index.mjs

@@ -2,6 +2,8 @@
 var EventType = {
   WIDGET_READY: "WIDGET_READY",
   WIDGET_CONFIG: "WIDGET_CONFIG",
+  PAYMENT_ATTEMPT: "PAYMENT_ATTEMPT_EVENT",
+  PAYMENT_UI: "PAYMENT_UI_EVENT",
   PAYMENT: "PAYMENT",
   PAYMENT_SUCCESS: "PAYMENT_SUCCESS",
   PAYMENT_ERROR: "PAYMENT_ERROR",
@@ -14,6 +16,33 @@ var CheckoutFormVariant = {
   LIST: "LIST",
   RADIO: "RADIO"
 };
+var PaymentMethod = {
+  PAYMENT_CARD: "PAYMENT_CARD",
+  GOOGLE_PAY: "GOOGLE_PAY",
+  APPLE_PAY: "APPLE_PAY",
+  PAYPAL: "PAYPAL",
+  BANK_ACCOUNT: "BANK_ACCOUNT",
+  OTHER: "OTHER"
+};
+var PaymentAttemptResult = {
+  INITIATED: "INITIATED",
+  THREE_DS_INITIATED: "THREE_DS_INITIATED",
+  AUTHORIZED: "AUTHORIZED",
+  SOFT_DECLINE: "SOFT_DECLINE",
+  HARD_DECLINE: "HARD_DECLINE",
+  CANCELLED: "CANCELLED",
+  NETWORK_ERROR: "NETWORK_ERROR"
+};
+var PaymentUIEvent = {
+  FORM_ENTERED: "FORM_ENTERED",
+  FORM_EXITED: "FORM_EXITED"
+};
+var CheckoutView = {
+  EXPRESS: "EXPRESS",
+  CARD: "CARD"
+};
+var isAttemptEvent = (e) => e.type === EventType.PAYMENT_ATTEMPT;
+var isUIEvent = (e) => e.type === EventType.PAYMENT_UI;
 var FieldType = {
   CARD_NUMBER: "card-number",
   EXPIRY: "expiry",
@@ -146,6 +175,18 @@ function createFlintNPayment(options) {
         sendConfig();
         options.onReady?.();
         break;
+      case EventType.PAYMENT_ATTEMPT:
+        options.onEvent?.({
+          type: EventType.PAYMENT_ATTEMPT,
+          ...payload
+        });
+        break;
+      case EventType.PAYMENT_UI:
+        options.onEvent?.({
+          type: EventType.PAYMENT_UI,
+          ...payload
+        });
+        break;
       case EventType.PAYMENT:
         options.onPayment?.(payload);
         break;
@@ -591,14 +632,20 @@ function createFlintNFields(options) {
 }
 export {
   CheckoutFormVariant,
+  CheckoutView,
   EventType,
   FieldEventType,
   FieldType,
+  PaymentAttemptResult,
+  PaymentMethod,
+  PaymentUIEvent,
   buildIframeSrc,
   createFlintNField,
   createFlintNFields,
   createFlintNPayment,
   createIframeElement,
+  isAttemptEvent,
+  isUIEvent,
   parseOrigin,
   sanitizeToken,
   validateConfig

package/dist/react.d.mts

@@ -1,3 +1,15 @@
+declare const EventType: {
+    readonly WIDGET_READY: "WIDGET_READY";
+    readonly WIDGET_CONFIG: "WIDGET_CONFIG";
+    readonly PAYMENT_ATTEMPT: "PAYMENT_ATTEMPT_EVENT";
+    readonly PAYMENT_UI: "PAYMENT_UI_EVENT";
+    readonly PAYMENT: "PAYMENT";
+    readonly PAYMENT_SUCCESS: "PAYMENT_SUCCESS";
+    readonly PAYMENT_ERROR: "PAYMENT_ERROR";
+    readonly PAYMENT_CANCELLED: "PAYMENT_CANCELLED";
+    readonly REDIRECT: "REDIRECT";
+    readonly RESIZE: "RESIZE";
+};
 declare const CheckoutFormVariant: {
     readonly DEFAULT: "DEFAULT";
     readonly LIST: "LIST";
@@ -34,6 +46,53 @@ interface FlintNConfig {
     styles?: FormStyles;
     successRedirectUrl?: string;
 }
+declare const PaymentMethod: {
+    readonly PAYMENT_CARD: "PAYMENT_CARD";
+    readonly GOOGLE_PAY: "GOOGLE_PAY";
+    readonly APPLE_PAY: "APPLE_PAY";
+    readonly PAYPAL: "PAYPAL";
+    readonly BANK_ACCOUNT: "BANK_ACCOUNT";
+    readonly OTHER: "OTHER";
+};
+type TPaymentMethod = (typeof PaymentMethod)[keyof typeof PaymentMethod];
+declare const PaymentAttemptResult: {
+    readonly INITIATED: "INITIATED";
+    readonly THREE_DS_INITIATED: "THREE_DS_INITIATED";
+    readonly AUTHORIZED: "AUTHORIZED";
+    readonly SOFT_DECLINE: "SOFT_DECLINE";
+    readonly HARD_DECLINE: "HARD_DECLINE";
+    readonly CANCELLED: "CANCELLED";
+    readonly NETWORK_ERROR: "NETWORK_ERROR";
+};
+type TPaymentAttemptResult = (typeof PaymentAttemptResult)[keyof typeof PaymentAttemptResult];
+declare const PaymentUIEvent: {
+    readonly FORM_ENTERED: "FORM_ENTERED";
+    readonly FORM_EXITED: "FORM_EXITED";
+};
+type TPaymentUIEvent = (typeof PaymentUIEvent)[keyof typeof PaymentUIEvent];
+declare const CheckoutView: {
+    readonly EXPRESS: "EXPRESS";
+    readonly CARD: "CARD";
+};
+type TCheckoutView = (typeof CheckoutView)[keyof typeof CheckoutView];
+interface PaymentAttempt {
+    type: typeof EventType.PAYMENT_ATTEMPT;
+    event: TPaymentAttemptResult;
+    method: TPaymentMethod;
+    paymentId?: string;
+    code?: string;
+    message?: string;
+    timestamp: number;
+    clientSessionId?: string;
+}
+interface PaymentUI {
+    type: typeof EventType.PAYMENT_UI;
+    event: TPaymentUIEvent;
+    view: TCheckoutView;
+    timestamp: number;
+    clientSessionId?: string;
+}
+type CheckoutEvent = PaymentAttempt | PaymentUI;
 interface PaymentResult {
     status: 'PAYMENT_SUCCESS' | 'PAYMENT_ERROR' | 'PAYMENT_CANCELLED';
     data?: string;
@@ -50,6 +109,7 @@ interface FlintNPaymentOptions {
     origin?: string;
     config: FlintNConfig;
     onPayment?: (result: PaymentResult) => void;
+    onEvent?: (event: CheckoutEvent) => void;
     onReady?: () => void;
     onError?: (error: PaymentError) => void;
     debug?: boolean;
@@ -101,22 +161,13 @@ interface FlintNFieldsOptions {
     debug?: boolean;
 }
 
-/**
- * Options for the useFlintNPayment hook.
- *
- * Extends FlintNPaymentOptions but omits `onReady` and `onError` callbacks
- * as they are managed internally by the hook. Use the returned `isReady`
- * and `error` values instead.
- *
- * All other FlintNPaymentOptions fields (config, onPayment, debug)
- * can be passed directly.
- */
 interface UseFlintNPaymentOptions extends Omit<FlintNPaymentOptions, 'onReady' | 'onError'> {
 }
 interface UseFlintNPaymentReturn {
     containerRef: React.RefObject<HTMLDivElement | null>;
     isReady: boolean;
     paymentResult: PaymentResult | null;
+    events: Array<CheckoutEvent>;
     error: PaymentError | null;
 }
 declare function useFlintNPayment(options: UseFlintNPaymentOptions): UseFlintNPaymentReturn;

package/dist/react.d.ts

@@ -1,3 +1,15 @@
+declare const EventType: {
+    readonly WIDGET_READY: "WIDGET_READY";
+    readonly WIDGET_CONFIG: "WIDGET_CONFIG";
+    readonly PAYMENT_ATTEMPT: "PAYMENT_ATTEMPT_EVENT";
+    readonly PAYMENT_UI: "PAYMENT_UI_EVENT";
+    readonly PAYMENT: "PAYMENT";
+    readonly PAYMENT_SUCCESS: "PAYMENT_SUCCESS";
+    readonly PAYMENT_ERROR: "PAYMENT_ERROR";
+    readonly PAYMENT_CANCELLED: "PAYMENT_CANCELLED";
+    readonly REDIRECT: "REDIRECT";
+    readonly RESIZE: "RESIZE";
+};
 declare const CheckoutFormVariant: {
     readonly DEFAULT: "DEFAULT";
     readonly LIST: "LIST";
@@ -34,6 +46,53 @@ interface FlintNConfig {
     styles?: FormStyles;
     successRedirectUrl?: string;
 }
+declare const PaymentMethod: {
+    readonly PAYMENT_CARD: "PAYMENT_CARD";
+    readonly GOOGLE_PAY: "GOOGLE_PAY";
+    readonly APPLE_PAY: "APPLE_PAY";
+    readonly PAYPAL: "PAYPAL";
+    readonly BANK_ACCOUNT: "BANK_ACCOUNT";
+    readonly OTHER: "OTHER";
+};
+type TPaymentMethod = (typeof PaymentMethod)[keyof typeof PaymentMethod];
+declare const PaymentAttemptResult: {
+    readonly INITIATED: "INITIATED";
+    readonly THREE_DS_INITIATED: "THREE_DS_INITIATED";
+    readonly AUTHORIZED: "AUTHORIZED";
+    readonly SOFT_DECLINE: "SOFT_DECLINE";
+    readonly HARD_DECLINE: "HARD_DECLINE";
+    readonly CANCELLED: "CANCELLED";
+    readonly NETWORK_ERROR: "NETWORK_ERROR";
+};
+type TPaymentAttemptResult = (typeof PaymentAttemptResult)[keyof typeof PaymentAttemptResult];
+declare const PaymentUIEvent: {
+    readonly FORM_ENTERED: "FORM_ENTERED";
+    readonly FORM_EXITED: "FORM_EXITED";
+};
+type TPaymentUIEvent = (typeof PaymentUIEvent)[keyof typeof PaymentUIEvent];
+declare const CheckoutView: {
+    readonly EXPRESS: "EXPRESS";
+    readonly CARD: "CARD";
+};
+type TCheckoutView = (typeof CheckoutView)[keyof typeof CheckoutView];
+interface PaymentAttempt {
+    type: typeof EventType.PAYMENT_ATTEMPT;
+    event: TPaymentAttemptResult;
+    method: TPaymentMethod;
+    paymentId?: string;
+    code?: string;
+    message?: string;
+    timestamp: number;
+    clientSessionId?: string;
+}
+interface PaymentUI {
+    type: typeof EventType.PAYMENT_UI;
+    event: TPaymentUIEvent;
+    view: TCheckoutView;
+    timestamp: number;
+    clientSessionId?: string;
+}
+type CheckoutEvent = PaymentAttempt | PaymentUI;
 interface PaymentResult {
     status: 'PAYMENT_SUCCESS' | 'PAYMENT_ERROR' | 'PAYMENT_CANCELLED';
     data?: string;
@@ -50,6 +109,7 @@ interface FlintNPaymentOptions {
     origin?: string;
     config: FlintNConfig;
     onPayment?: (result: PaymentResult) => void;
+    onEvent?: (event: CheckoutEvent) => void;
     onReady?: () => void;
     onError?: (error: PaymentError) => void;
     debug?: boolean;
@@ -101,22 +161,13 @@ interface FlintNFieldsOptions {
     debug?: boolean;
 }
 
-/**
- * Options for the useFlintNPayment hook.
- *
- * Extends FlintNPaymentOptions but omits `onReady` and `onError` callbacks
- * as they are managed internally by the hook. Use the returned `isReady`
- * and `error` values instead.
- *
- * All other FlintNPaymentOptions fields (config, onPayment, debug)
- * can be passed directly.
- */
 interface UseFlintNPaymentOptions extends Omit<FlintNPaymentOptions, 'onReady' | 'onError'> {
 }
 interface UseFlintNPaymentReturn {
     containerRef: React.RefObject<HTMLDivElement | null>;
     isReady: boolean;
     paymentResult: PaymentResult | null;
+    events: Array<CheckoutEvent>;
     error: PaymentError | null;
 }
 declare function useFlintNPayment(options: UseFlintNPaymentOptions): UseFlintNPaymentReturn;

package/dist/react.js

@@ -32,6 +32,8 @@ var import_react = require("react");
 var EventType = {
   WIDGET_READY: "WIDGET_READY",
   WIDGET_CONFIG: "WIDGET_CONFIG",
+  PAYMENT_ATTEMPT: "PAYMENT_ATTEMPT_EVENT",
+  PAYMENT_UI: "PAYMENT_UI_EVENT",
   PAYMENT: "PAYMENT",
   PAYMENT_SUCCESS: "PAYMENT_SUCCESS",
   PAYMENT_ERROR: "PAYMENT_ERROR",
@@ -171,6 +173,18 @@ function createFlintNPayment(options) {
         sendConfig();
         options.onReady?.();
         break;
+      case EventType.PAYMENT_ATTEMPT:
+        options.onEvent?.({
+          type: EventType.PAYMENT_ATTEMPT,
+          ...payload
+        });
+        break;
+      case EventType.PAYMENT_UI:
+        options.onEvent?.({
+          type: EventType.PAYMENT_UI,
+          ...payload
+        });
+        break;
       case EventType.PAYMENT:
         options.onPayment?.(payload);
         break;
@@ -226,18 +240,20 @@ function useFlintNPayment(options) {
   const containerRef = (0, import_react.useRef)(null);
   const paymentRef = (0, import_react.useRef)(null);
   const onPaymentRef = (0, import_react.useRef)(options.onPayment);
+  const onEventRef = (0, import_react.useRef)(options.onEvent);
   const [isReady, setIsReady] = (0, import_react.useState)(false);
-  const [paymentResult, setPaymentResult] = (0, import_react.useState)(
-    null
-  );
+  const [paymentResult, setPaymentResult] = (0, import_react.useState)(null);
+  const [events, setEvents] = (0, import_react.useState)([]);
   const [error, setError] = (0, import_react.useState)(null);
   (0, import_react.useEffect)(() => {
     onPaymentRef.current = options.onPayment;
-  }, [options.onPayment]);
+    onEventRef.current = options.onEvent;
+  }, [options.onPayment, options.onEvent]);
   (0, import_react.useEffect)(() => {
     if (!containerRef.current) return;
     setIsReady(false);
     setPaymentResult(null);
+    setEvents([]);
     setError(null);
     paymentRef.current = createFlintNPayment({
       ...options,
@@ -246,6 +262,10 @@ function useFlintNPayment(options) {
         setPaymentResult(result);
         onPaymentRef.current?.(result);
       },
+      onEvent: (event) => {
+        setEvents((prev) => [...prev, event]);
+        onEventRef.current?.(event);
+      },
       onError: (err) => setError(err)
     });
     paymentRef.current.mount(containerRef.current);
@@ -265,6 +285,7 @@ function useFlintNPayment(options) {
     containerRef,
     isReady,
     paymentResult,
+    events,
     error
   };
 }

package/dist/react.mjs

@@ -5,6 +5,8 @@ import { useEffect, useRef, useState } from "react";
 var EventType = {
   WIDGET_READY: "WIDGET_READY",
   WIDGET_CONFIG: "WIDGET_CONFIG",
+  PAYMENT_ATTEMPT: "PAYMENT_ATTEMPT_EVENT",
+  PAYMENT_UI: "PAYMENT_UI_EVENT",
   PAYMENT: "PAYMENT",
   PAYMENT_SUCCESS: "PAYMENT_SUCCESS",
   PAYMENT_ERROR: "PAYMENT_ERROR",
@@ -144,6 +146,18 @@ function createFlintNPayment(options) {
         sendConfig();
         options.onReady?.();
         break;
+      case EventType.PAYMENT_ATTEMPT:
+        options.onEvent?.({
+          type: EventType.PAYMENT_ATTEMPT,
+          ...payload
+        });
+        break;
+      case EventType.PAYMENT_UI:
+        options.onEvent?.({
+          type: EventType.PAYMENT_UI,
+          ...payload
+        });
+        break;
       case EventType.PAYMENT:
         options.onPayment?.(payload);
         break;
@@ -199,18 +213,20 @@ function useFlintNPayment(options) {
   const containerRef = useRef(null);
   const paymentRef = useRef(null);
   const onPaymentRef = useRef(options.onPayment);
+  const onEventRef = useRef(options.onEvent);
   const [isReady, setIsReady] = useState(false);
-  const [paymentResult, setPaymentResult] = useState(
-    null
-  );
+  const [paymentResult, setPaymentResult] = useState(null);
+  const [events, setEvents] = useState([]);
   const [error, setError] = useState(null);
   useEffect(() => {
     onPaymentRef.current = options.onPayment;
-  }, [options.onPayment]);
+    onEventRef.current = options.onEvent;
+  }, [options.onPayment, options.onEvent]);
   useEffect(() => {
     if (!containerRef.current) return;
     setIsReady(false);
     setPaymentResult(null);
+    setEvents([]);
     setError(null);
     paymentRef.current = createFlintNPayment({
       ...options,
@@ -219,6 +235,10 @@ function useFlintNPayment(options) {
         setPaymentResult(result);
         onPaymentRef.current?.(result);
       },
+      onEvent: (event) => {
+        setEvents((prev) => [...prev, event]);
+        onEventRef.current?.(event);
+      },
       onError: (err) => setError(err)
     });
     paymentRef.current.mount(containerRef.current);
@@ -238,6 +258,7 @@ function useFlintNPayment(options) {
     containerRef,
     isReady,
     paymentResult,
+    events,
     error
   };
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "flintn-checkout",
-  "version": "0.0.11",
+  "version": "0.0.13",
   "description": "FlintN Payment SDK — drop-in iframe checkout for card payments and wallets with localization and theming.",
   "main": "./dist/index.js",
   "module": "./dist/index.mjs",