flintn-checkout 0.0.10 → 0.0.12

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, attempts, error } = useFlintNPayment({
     config: {
       clientSessionId: 'your_client_session_id',
     },
@@ -29,6 +29,11 @@ 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).
+      console.log('Attempt:', event.result, event.method, event.code);
+    },
   });
 
   return (
@@ -55,6 +60,9 @@ const payment = createFlintNPayment({
       console.log('Payment failed:', result.error);
     }
   },
+  onEvent: (event) => {
+    console.log('Attempt:', event.result, event.method);
+  },
   onReady: () => {
     console.log('Widget ready');
   },
@@ -88,6 +96,9 @@ payment.mount('#payment-container');
       onPayment: (result) => {
         console.log('Payment result:', result);
       },
+      onEvent: (event) => {
+        console.log('Attempt:', event);
+      },
     });
 
     payment.mount('#payment-container');
@@ -96,6 +107,92 @@ 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: PaymentAttempt)
+```
+
+The `result` discriminator describes what happened at this step:
+
+| `result` | 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.
+
+**Example funnel — soft decline → retry success:**
+
+```
+onEvent   → { result: 'INITIATED',    method: 'PAYMENT_CARD' }
+onEvent   → { result: 'SOFT_DECLINE', method: 'PAYMENT_CARD', code: 'do_not_honor', message: 'Payment declined.' }
+// buyer retries with another card
+onEvent   → { result: 'INITIATED',    method: 'PAYMENT_CARD' }
+onEvent   → { result: 'AUTHORIZED',   method: 'PAYMENT_CARD', paymentId: 'pay_...' }
+onPayment → { status: 'PAYMENT_SUCCESS', data: 'pay_...' }
+```
+
+**Example — Apple Pay buyer cancel (DEFAULT variant):**
+
+```
+onEvent → { result: 'INITIATED', method: 'APPLE_PAY' }
+onEvent → { result: '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   → { result: 'INITIATED',          method: 'PAYPAL' }
+onEvent   → { result: 'THREE_DS_INITIATED', method: 'PAYPAL', paymentId: 'pay_...' }
+onEvent   → { result: 'AUTHORIZED',         method: 'PAYPAL', paymentId: 'pay_...' }
+onPayment → { status: 'PAYMENT_SUCCESS', data: 'pay_...' }
+```
+
+### `attempts` (React) — accumulated log
+
+The `useFlintNPayment` hook also exposes `attempts: PaymentAttempt[]` — every event since mount, useful for rendering a per-attempt UI without wiring `onEvent` manually:
+
+```tsx
+const { attempts } = useFlintNPayment({ ... });
+
+return (
+  <ul>
+    {attempts.map((a, i) => (
+      <li key={i}>[{a.method}] {a.result} {a.code && `— ${a.code}`}</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 +208,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 | — | Card payment result callback |
+| `onPayment` | `(result: PaymentResult) => void` | No | — | Terminal session result (success / error) |
+| `onEvent` | `(event: PaymentAttempt) => 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 +229,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 |
+| `attempts` | `PaymentAttempt[]` | Per-attempt event log (accumulated since mount) |
 | `error` | `PaymentError \| null` | SDK error if any |
 
 ---
@@ -142,6 +241,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 +479,43 @@ interface PaymentError {
 }
 ```
 
+### PaymentAttempt
+
+```typescript
+interface PaymentAttempt {
+  result:
+    | '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
+}
+```
+
+Const-object accessors are also exported if you prefer typed comparisons over string literals:
+
+```ts
+import { AttemptResult, PaymentMethod } from 'flintn-checkout';
+
+onEvent: (e) => {
+  if (e.result === AttemptResult.SOFT_DECLINE && e.method === PaymentMethod.PAYMENT_CARD) {
+    analytics.track('soft_decline_card', { code: e.code });
+  }
+}
+```
+
 ### FieldState
 ```typescript
 interface FieldState {
@@ -472,6 +610,20 @@ The iframe checkout supports three layout variants via `formFields.formVariant`:
 
 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.
 
+### 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 |
+
+Every cancellation still emits a `CANCELLED` `onEvent` regardless of variant, so analytics is unaffected.
+
 ## Supported Payment Methods
 
 ### Iframe Checkout
@@ -500,15 +652,6 @@ useFlintNFields({
 });
 ```
 
-## Test Cards
-
-| Card Number | Result |
-|-------------|--------|
-| `4111 1111 1111 1111` | Success |
-| `4000 0000 0000 0002` | Declined |
-
-Use any future expiry date and any 3-digit CVV.
-
 ## Browser Support
 
 - Chrome (latest)

package/dist/index.d.mts

@@ -1,8 +1,8 @@
 declare const EventType: {
     readonly WIDGET_READY: "WIDGET_READY";
     readonly WIDGET_CONFIG: "WIDGET_CONFIG";
+    readonly PAYMENT_ATTEMPT: "PAYMENT_ATTEMPT";
     readonly PAYMENT: "PAYMENT";
-    readonly EXPRESS_PAYMENT: "EXPRESS_PAYMENT";
     readonly PAYMENT_SUCCESS: "PAYMENT_SUCCESS";
     readonly PAYMENT_ERROR: "PAYMENT_ERROR";
     readonly PAYMENT_CANCELLED: "PAYMENT_CANCELLED";
@@ -46,6 +46,32 @@ 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 AttemptResult: {
+    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 TAttemptResult = (typeof AttemptResult)[keyof typeof AttemptResult];
+interface PaymentAttempt {
+    result: TAttemptResult;
+    method: TPaymentMethod;
+    paymentId?: string;
+    code?: string;
+    message?: string;
+}
 interface PaymentResult {
     status: 'PAYMENT_SUCCESS' | 'PAYMENT_ERROR' | 'PAYMENT_CANCELLED';
     data?: string;
@@ -62,7 +88,7 @@ interface FlintNPaymentOptions {
     origin?: string;
     config: FlintNConfig;
     onPayment?: (result: PaymentResult) => void;
-    onExpressPayment?: (result: PaymentResult) => void;
+    onEvent?: (event: PaymentAttempt) => void;
     onReady?: () => void;
     onError?: (error: PaymentError) => void;
     debug?: boolean;
@@ -147,6 +173,7 @@ interface FlintNFieldInternalCallbacks {
     onFocus: (fieldType: TFieldType) => void;
     onBlur: (fieldType: TFieldType, state: FieldState) => void;
     onHeight: (fieldType: TFieldType, height: number) => void;
+    onError?: (err: Error) => void;
 }
 interface FlintNField {
     mount(selector: string | HTMLElement): void;
@@ -179,4 +206,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 { AttemptResult, 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 PaymentAttempt, type PaymentError, PaymentMethod, type PaymentResult, type SubmitOptions, type TAttemptResult, type TCheckoutFormVariant, type TEventType, type TFieldEventType, type TFieldType, type TPaymentMethod, buildIframeSrc, createFlintNField, createFlintNFields, createFlintNPayment, createIframeElement, parseOrigin, sanitizeToken, validateConfig };

package/dist/index.d.ts

@@ -1,8 +1,8 @@
 declare const EventType: {
     readonly WIDGET_READY: "WIDGET_READY";
     readonly WIDGET_CONFIG: "WIDGET_CONFIG";
+    readonly PAYMENT_ATTEMPT: "PAYMENT_ATTEMPT";
     readonly PAYMENT: "PAYMENT";
-    readonly EXPRESS_PAYMENT: "EXPRESS_PAYMENT";
     readonly PAYMENT_SUCCESS: "PAYMENT_SUCCESS";
     readonly PAYMENT_ERROR: "PAYMENT_ERROR";
     readonly PAYMENT_CANCELLED: "PAYMENT_CANCELLED";
@@ -46,6 +46,32 @@ 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 AttemptResult: {
+    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 TAttemptResult = (typeof AttemptResult)[keyof typeof AttemptResult];
+interface PaymentAttempt {
+    result: TAttemptResult;
+    method: TPaymentMethod;
+    paymentId?: string;
+    code?: string;
+    message?: string;
+}
 interface PaymentResult {
     status: 'PAYMENT_SUCCESS' | 'PAYMENT_ERROR' | 'PAYMENT_CANCELLED';
     data?: string;
@@ -62,7 +88,7 @@ interface FlintNPaymentOptions {
     origin?: string;
     config: FlintNConfig;
     onPayment?: (result: PaymentResult) => void;
-    onExpressPayment?: (result: PaymentResult) => void;
+    onEvent?: (event: PaymentAttempt) => void;
     onReady?: () => void;
     onError?: (error: PaymentError) => void;
     debug?: boolean;
@@ -147,6 +173,7 @@ interface FlintNFieldInternalCallbacks {
     onFocus: (fieldType: TFieldType) => void;
     onBlur: (fieldType: TFieldType, state: FieldState) => void;
     onHeight: (fieldType: TFieldType, height: number) => void;
+    onError?: (err: Error) => void;
 }
 interface FlintNField {
     mount(selector: string | HTMLElement): void;
@@ -179,4 +206,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 { AttemptResult, 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 PaymentAttempt, type PaymentError, PaymentMethod, type PaymentResult, type SubmitOptions, type TAttemptResult, type TCheckoutFormVariant, type TEventType, type TFieldEventType, type TFieldType, type TPaymentMethod, buildIframeSrc, createFlintNField, createFlintNFields, createFlintNPayment, createIframeElement, parseOrigin, sanitizeToken, validateConfig };