flintn-checkout 0.0.17 → 0.0.19

package/README.md

@@ -10,7 +10,7 @@ npm install flintn-checkout
 
 ## Iframe Checkout
 
-Full checkout UI rendered inside a single iframe. Includes card form, express payments (Apple Pay, PayPal), and 3DS handling.
+Full checkout UI rendered inside a single iframe. Includes card form, express payments (Apple Pay, Google Pay, PayPal), and 3DS handling.
 
 **React**
 
@@ -108,6 +108,92 @@ payment.mount('#payment-container');
 </html>
 ```
 
+### External express buttons (`expressButtons: false`)
+
+By default the iframe renders express buttons (Apple Pay / Google Pay /
+PayPal) inside the checkout form. Set `config.expressButtons: false` to keep
+the iframe card-form only and render the wallet buttons directly in your own
+page — full control over placement and layout, and wallet payment sheets open
+from the top-level page instead of inside an iframe.
+
+**React** — the hook mounts the buttons for you and merges wallet results
+into the same `onPayment` / `onEvent` callbacks as the card form:
+
+```tsx
+import { useFlintNPayment } from 'flintn-checkout/react';
+
+function Checkout() {
+  const {
+    containerRef,
+    applePayRef,
+    googlePayRef,
+    payPalRef,
+    expressAvailable,
+    paymentResult,
+  } = useFlintNPayment({
+    config: {
+      clientSessionId: 'your_client_session_id',
+      expressButtons: false,
+    },
+    // Single callback for wallets AND the card form
+    onPayment: (result) => console.log('Payment:', result),
+    // Single per-attempt stream for wallets AND the card form
+    onEvent: (event) => console.log('Event:', event),
+  });
+
+  return (
+    <div style={{ maxWidth: 440 }}>
+      {/* Your layout, your styling. Hide with CSS while unavailable —
+          do not conditionally unmount the refs. */}
+      <div style={{ display: expressAvailable ? 'block' : 'none' }}>
+        <div ref={applePayRef} />
+        <div ref={googlePayRef} />
+        <div ref={payPalRef} />
+        <hr />
+      </div>
+
+      {/* Card form iframe — no express buttons inside */}
+      <div ref={containerRef} style={{ width: '100%' }} />
+    </div>
+  );
+}
+```
+
+**Vanilla JavaScript** — pair `createFlintNPayment` with the standalone
+express module:
+
+```javascript
+import { createFlintNPayment, createFlintNExpressButtons } from 'flintn-checkout';
+
+const payment = createFlintNPayment({
+  config: { clientSessionId: 'your_client_session_id', expressButtons: false },
+  onPayment: (result) => console.log('Card payment:', result),
+});
+payment.mount('#payment-container');
+
+const express = createFlintNExpressButtons({
+  config: { clientSessionId: 'your_client_session_id' },
+  onPayment: (result) => console.log('Wallet payment:', result),
+  onCapability: (cap) => {
+    // Show/hide your express section based on device availability
+    document.getElementById('express-row').hidden =
+      !(cap.applePay || cap.googlePay || cap.paypal);
+  },
+});
+express.mountExpressButtons([
+  { method: 'APPLE_PAY', elementSelector: '#apple-pay' },
+  { method: 'GOOGLE_PAY', elementSelector: '#google-pay' },
+  { method: 'PAYPAL', elementSelector: '#paypal' },
+]);
+```
+
+Notes:
+
+- `formFields.formVariant` `LIST`/`RADIO` are ignored with
+  `expressButtons: false` — the express/card switch lives in your page now.
+- After a successful wallet payment, disable or hide the card form — the
+  session is completed and further card submits will fail.
+
 ## Events — terminal vs per-attempt
 
 The SDK fires two streams of events. Use the one that fits your use case:
@@ -166,7 +252,7 @@ For UI events (LIST and RADIO variants), `view` is the view that became active:
 
 ```
 onEvent   → { event: 'INITIATED',    method: 'PAYMENT_CARD' }
-onEvent   → { event: 'SOFT_DECLINE', method: 'PAYMENT_CARD', code: 'do_not_honor', message: 'Payment declined.' }
+onEvent   → { event: 'SOFT_DECLINE', method: 'PAYMENT_CARD', code: 'FNT-EC-2003', message: 'Insufficient funds.' }
 // buyer retries with another card
 onEvent   → { event: 'INITIATED',    method: 'PAYMENT_CARD' }
 onEvent   → { event: 'AUTHORIZED',   method: 'PAYMENT_CARD', paymentId: 'pay_...' }
@@ -246,6 +332,7 @@ Do **not** set a fixed `height` on the container — it will leave empty space b
 | `styles` | `FormStyles` | No | Custom styles (colors, border radius, text) for the checkout form |
 | `placeholders` | `FormPlaceholders` | No | Per-field placeholder text overrides (see `FormPlaceholders`) |
 | `successRedirectUrl` | `string` | No | Redirect URL after successful payment |
+| `expressButtons` | `boolean` | No | Default `true` — express buttons (Apple Pay / Google Pay / PayPal) render inside the iframe form. Set `false` to render the card form only and mount express buttons in your own page via `createFlintNExpressButtons`; `formFields.formVariant` `LIST`/`RADIO` are ignored in that case |
 
 ### React Hook Return Values
 
@@ -253,9 +340,13 @@ 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 terminal `onPayment` event |
+| `paymentResult` | `PaymentResult \| null` | Result after terminal `onPayment` event (card or wallet) |
 | `events` | `CheckoutEvent[]` | Per-attempt event log (accumulated since mount) |
 | `error` | `PaymentError \| null` | SDK error if any |
+| `applePayRef` | `RefObject<HTMLDivElement>` | Apple Pay mount point — used with `expressButtons: false` |
+| `googlePayRef` | `RefObject<HTMLDivElement>` | Google Pay mount point — used with `expressButtons: false` |
+| `payPalRef` | `RefObject<HTMLDivElement>` | PayPal mount point — used with `expressButtons: false` |
+| `expressAvailable` | `boolean` | At least one wallet is available on this device/session (`expressButtons: false` only) |
 
 ---
 
@@ -270,7 +361,7 @@ When a card payment requires 3DS, the SDK shows the bank's challenge in a
 `THREE_DS_CANCELLED` payment error. While the challenge is open, the
 `submit()` promise stays pending with a 10-minute timeout.
 
-> **Note:** For card fields, Hosted Fields emits only the terminal `onPayment` event. The express buttons additionally emit per-attempt wallet analytics via the top-level `onEvent` callback (same `onPayment` / `onEvent` split as Iframe Checkout) — see "Express buttons" below. For full per-attempt analytics across the card form too, use Iframe Checkout.
+> **Note:** Hosted Fields emit the same per-attempt analytics as Iframe Checkout — the card flow and the express buttons both report through the top-level `onEvent` callback (`method: 'PAYMENT_CARD'` for the card form), while terminal results arrive via `onPayment`. See "Events — terminal vs per-attempt" above; UI events (`FORM_ENTERED`/`FORM_EXITED`) do not apply since your page owns the layout.
 
 **React**
 
@@ -409,6 +500,8 @@ if (validation.isValid) {
 | `onChange` | `(event: FieldChangeEvent) => void` | No | — | Field value changed |
 | `onFocus` | `(fieldType: TFieldType) => void` | No | — | Field gained focus |
 | `onBlur` | `(fieldType: TFieldType, state: FieldState) => void` | No | — | Field lost focus |
+| `onEvent` | `(event: AttemptEvent) => void` | No | — | Per-attempt analytics for the card flow (`method: 'PAYMENT_CARD'`) |
+| `onPostalCodeRequirement` | `(required: boolean) => void` | No | — | Entered card BIN requires a postal code — see "Postal code (BIN-driven)" |
 | `onError` | `(error: PaymentError) => void` | No | — | SDK initialization error |
 | `debug` | `boolean` | No | `false` | Enable console debug logs |
 
@@ -433,7 +526,7 @@ Additional React-only options:
 | `onChange` | `(event: FieldChangeEvent) => void` | Optional additional callback |
 | `onFocus` | `(fieldType: TFieldType) => void` | Optional additional callback |
 | `onBlur` | `(fieldType: TFieldType, state: FieldState) => void` | Optional additional callback |
-| `onEvent` | `(event: ExpressAttempt) => void` | Per-attempt wallet analytics from the express buttons (see "Express buttons") |
+| `onEvent` | `(event: AttemptEvent) => void` | Per-attempt analytics — card flow (`method: 'PAYMENT_CARD'`) and express buttons share this stream |
 
 ### FieldOptions
 
@@ -457,6 +550,7 @@ Additional React-only options:
 | `fieldErrors` | `Partial<Record<TFieldType, string \| null>>` | Per-field validation errors (populated after first submit) |
 | `fieldStates` | `Partial<Record<TFieldType, FieldState>>` | Per-field state (always up to date) |
 | `cardBrand` | `string \| null` | Detected card brand (e.g. `"visa"`, `"mastercard"`) |
+| `postalCodeRequired` | `boolean` | The entered card BIN requires a postal code — see "Postal code (BIN-driven)" |
 | `paymentResult` | `PaymentResult \| null` | Result after payment attempt |
 | `error` | `PaymentError \| null` | SDK error if any |
 | `validate` | `() => Promise<FieldsValidationResult>` | Validate all fields |
@@ -475,6 +569,29 @@ Validation mirrors react-hook-form `mode: 'onSubmit'`:
 - All three fields (card number, expiry, CVV) are required — submitting with a missing field returns a `MISSING_FIELDS` error
 - The CVV field ships a built-in helper: tapping the card icon expands a “where to find CVV” panel below the input. The field iframe grows to fit it, so keep the CVV container at a fixed `height` with `position: relative; z-index: 1` — the open panel then overlays the content below (like a popover) instead of pushing your layout
 
+### Postal code (BIN-driven)
+
+Some issuers require a postal code for online payments (currently US-issued
+cards — the requirement is resolved server-side by BIN). Once the buyer has
+typed enough digits, the card-number field checks the BIN against the payments
+API and reports whether a postal code is required — `postalCodeRequired`
+(React) / `onPostalCodeRequirement` (vanilla). Show your own postal code input
+when it flips to `true` and pass the value at submit:
+
+```tsx
+const { postalCodeRequired, submit } = useFlintNFields({ ... });
+
+// render your postal input when postalCodeRequired === true, then:
+await submit({
+  cardholderName,
+  billingAddress: { postalCode },
+});
+```
+
+If the BIN requires a postal code and `billingAddress.postalCode` is missing,
+`submit()` resolves with `PAYMENT_ERROR` / `POSTAL_CODE_REQUIRED` without
+calling the payments API.
+
 ### Field Types
 
 | Value | Description |
@@ -617,6 +734,25 @@ interface PaymentError {
 }
 ```
 
+### SubmitOptions (Hosted Fields)
+
+```typescript
+interface SubmitOptions {
+  // Required by default — the API rejects card payments without it unless the
+  // merchant disabled the cardholder name field in the client session request.
+  cardholderName?: string;
+  email?: string;
+  billingAddress?: {
+    addressLine1?: string;
+    addressLine2?: string;
+    city?: string;
+    state?: string;
+    postalCode?: string; // required when the BIN demands it — see "Postal code (BIN-driven)"
+    country?: string;
+  };
+}
+```
+
 ### Error handling
 
 Errors surface through three separate channels — don't conflate them:
@@ -637,9 +773,11 @@ Common `code` values:
 | `CONFIG_ERROR` | error | Session config failed to load and the API gave no code |
 | `NETWORK_ERROR` / `HTTP_<status>` / `INVALID_RESPONSE` | error or payment | Network failure / HTTP error without an API code / malformed response |
 | `VALIDATION_ERROR` | payment | `submit()` blocked by field validation (details in `fieldErrors`) |
+| `POSTAL_CODE_REQUIRED` | payment | The card BIN requires a postal code and `billingAddress.postalCode` was not passed to `submit()` |
 | `MISSING_FIELDS` / `NOT_INITIALIZED` / `SUBMIT_IN_PROGRESS` / `SUBMIT_TIMEOUT` | payment | Card `submit()` preconditions / duplicate call / no response in time (30s) |
 | `THREE_DS_TIMEOUT` | payment | A 3DS challenge stayed unresolved for 10 minutes |
-| `PAYMENT_DECLINED` / processor decline codes | payment | Declined; the processor's own code is passed through when present |
+| `FNT-EC-*` decline codes | payment | Declined — the FNT-EC decline code identifies the reason (e.g. `FNT-EC-2003` insufficient funds). Sent for both immediate and post-3DS declines |
+| `PAYMENT_DECLINED` | payment | Declined without a specific decline code (fallback) |
 | `PAYMENT_FAILED` | payment | Non-declined failure (including unexpected 3DS outcomes) |
 | `APPLE_PAY_SDK_ERROR` / `GOOGLE_PAY_SDK_ERROR` / `PAYPAL_ERROR` | payment | The wallet SDK failed mid-flow |
 | `PAYPAL_MISSING_PAYMENT_ID` | payment | PayPal approved but no payment id was captured (anomaly) |
@@ -870,7 +1008,10 @@ on `createField` (or the `fields` prop of `useFlintNFields`) instead.
 
 ## Form Variants
 
-The iframe checkout supports three layout variants via `formFields.formVariant`:
+The iframe checkout supports three layout variants via `formFields.formVariant`.
+Variants only apply when express buttons render inside the iframe — with
+`expressButtons: false` the variant is ignored and the iframe always shows the
+plain card form.
 
 - **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. Toggling emits `FORM_ENTERED` / `FORM_EXITED` UI events.

package/dist/index.d.mts

@@ -81,6 +81,14 @@ interface FlintNConfig {
     styles?: FormStyles;
     placeholders?: FormPlaceholders;
     successRedirectUrl?: string;
+    /**
+     * Whether the iframe renders express buttons (Apple Pay / Google Pay /
+     * PayPal) inside the checkout form. Default true. Set false to render the
+     * card form only and mount express buttons in your own page via
+     * `createFlintNExpressButtons` — note `formFields.formVariant` LIST/RADIO
+     * are ignored in that case.
+     */
+    expressButtons?: boolean;
 }
 declare const PaymentMethod: {
     readonly PAYMENT_CARD: "PAYMENT_CARD";
@@ -173,6 +181,8 @@ declare const FieldEventType: {
     readonly FIELD_HEIGHT: "FIELD_HEIGHT";
     readonly FIELD_THREE_DS_REQUIRED: "FIELD_THREE_DS_REQUIRED";
     readonly FIELD_THREE_DS_RESULT: "FIELD_THREE_DS_RESULT";
+    readonly FIELD_PAYMENT_ATTEMPT: "FIELD_PAYMENT_ATTEMPT";
+    readonly FIELD_POSTAL_CODE_REQUIREMENT: "FIELD_POSTAL_CODE_REQUIREMENT";
 };
 type TFieldEventType = (typeof FieldEventType)[keyof typeof FieldEventType];
 interface FieldOptions {
@@ -220,7 +230,7 @@ interface ExpressCapability {
     googlePay: boolean;
     paypal: boolean;
 }
-interface ExpressAttempt {
+interface AttemptEvent {
     event: TPaymentAttemptResult;
     method: TPaymentMethod;
     paymentId?: string;
@@ -240,6 +250,15 @@ interface FlintNFieldsOptions {
     onChange?: (event: FieldChangeEvent) => void;
     onFocus?: (fieldType: TFieldType) => void;
     onBlur?: (fieldType: TFieldType, state: FieldState) => void;
+    /** Per-attempt analytics for the card flow (express buttons have their own). */
+    onEvent?: (event: AttemptEvent) => void;
+    /**
+     * The entered card BIN requires (or stops requiring) a postal code. Show
+     * your own postal field and pass its value via submit's
+     * `billingAddress.postalCode` — submit fails with POSTAL_CODE_REQUIRED
+     * otherwise.
+     */
+    onPostalCodeRequirement?: (required: boolean) => void;
     onError?: (error: PaymentError) => void;
     debug?: boolean;
 }
@@ -293,7 +312,7 @@ interface FlintNExpressButtonsOptions {
     apiUrl?: string;
     buttonBorderRadius?: number;
     onPayment?: (result: PaymentResult) => void;
-    onEvent?: (event: ExpressAttempt) => void;
+    onEvent?: (event: AttemptEvent) => void;
     onCapability?: (capability: ExpressCapability) => void;
     onError?: (error: PaymentError) => void;
     debug?: boolean;
@@ -349,8 +368,11 @@ interface AuthorizeResponse {
     };
     status_reason?: {
         decline_reason?: string;
+        decline_code?: string;
+        decline_type?: 'SOFT_DECLINE' | 'HARD_DECLINE';
         message?: string;
     };
+    session_retryable?: boolean;
 }
 interface ApplePayToken {
     payment_data: {
@@ -377,7 +399,9 @@ interface GooglePayToken {
 interface WalletAuthorizeHandlers {
     onAuthorized: (paymentId: string) => void;
     onThreeDs: (redirectUrl: string, paymentId: string) => void;
-    onFailed: (code: string, message: string, paymentId?: string) => void;
+    onFailed: (code: string, message: string, paymentId?: string, 
+    /** Attempt analytics classification; defaults to HARD_DECLINE. */
+    event?: TPaymentAttemptResult) => void;
 }
 
 /**
@@ -425,4 +449,4 @@ declare const validateConfig: (config: {
 }) => void;
 declare const sanitizeToken: (token: string) => string;
 
-export { type ApplePayConfig, type ApplePayToken, type AuthorizeResponse, AuthorizedStatus, type CheckoutEvent, CheckoutFormVariant, CheckoutView, EXPRESS_BUTTON_HEIGHT, EventType, type ExpressAttempt, type ExpressButtonMount, type ExpressButtonsOptions, type ExpressCapability, ExpressMethod, type FieldChangeEvent, FieldEventType, type FieldOptions, type FieldState, FieldType, type FieldValidationResult, type FieldsValidationResult, type FlintNConfig, type FlintNExpressButtons, type FlintNExpressButtonsOptions, type FlintNField, type FlintNFieldInternalCallbacks, type FlintNFields, type FlintNFieldsConfig, type FlintNFieldsOptions, type FlintNPayment, type FlintNPaymentOptions, type FormFields, type FormPlaceholders, type FormStyles, type GooglePayConfig, type GooglePayToken, type PayPalConfig, type PaymentAttempt, PaymentAttemptResult, type PaymentError, PaymentMethod, type PaymentResult, type PaymentUI, PaymentUIEvent, type SessionConfig, type SubmitBillingAddress, type SubmitOptions, type TAuthorizedStatus, type TCheckoutFormVariant, type TCheckoutView, type TEventType, type TExpressMethod, type TFieldEventType, type TFieldType, type TPaymentAttemptResult, type TPaymentMethod, type TPaymentUIEvent, type WalletAuthorizeHandlers, buildIframeSrc, createFlintNExpressButtons, createFlintNField, createFlintNFields, createFlintNPayment, createIframeElement, deriveApiUrl, isAttemptEvent, isUIEvent, parseOrigin, sanitizeToken, validateConfig };
+export { type ApplePayConfig, type ApplePayToken, type AttemptEvent, type AuthorizeResponse, AuthorizedStatus, type CheckoutEvent, CheckoutFormVariant, CheckoutView, EXPRESS_BUTTON_HEIGHT, EventType, type ExpressButtonMount, type ExpressButtonsOptions, type ExpressCapability, ExpressMethod, type FieldChangeEvent, FieldEventType, type FieldOptions, type FieldState, FieldType, type FieldValidationResult, type FieldsValidationResult, type FlintNConfig, type FlintNExpressButtons, type FlintNExpressButtonsOptions, type FlintNField, type FlintNFieldInternalCallbacks, type FlintNFields, type FlintNFieldsConfig, type FlintNFieldsOptions, type FlintNPayment, type FlintNPaymentOptions, type FormFields, type FormPlaceholders, type FormStyles, type GooglePayConfig, type GooglePayToken, type PayPalConfig, type PaymentAttempt, PaymentAttemptResult, type PaymentError, PaymentMethod, type PaymentResult, type PaymentUI, PaymentUIEvent, type SessionConfig, type SubmitBillingAddress, type SubmitOptions, type TAuthorizedStatus, type TCheckoutFormVariant, type TCheckoutView, type TEventType, type TExpressMethod, type TFieldEventType, type TFieldType, type TPaymentAttemptResult, type TPaymentMethod, type TPaymentUIEvent, type WalletAuthorizeHandlers, buildIframeSrc, createFlintNExpressButtons, createFlintNField, createFlintNFields, createFlintNPayment, createIframeElement, deriveApiUrl, isAttemptEvent, isUIEvent, parseOrigin, sanitizeToken, validateConfig };

package/dist/index.d.ts

@@ -81,6 +81,14 @@ interface FlintNConfig {
     styles?: FormStyles;
     placeholders?: FormPlaceholders;
     successRedirectUrl?: string;
+    /**
+     * Whether the iframe renders express buttons (Apple Pay / Google Pay /
+     * PayPal) inside the checkout form. Default true. Set false to render the
+     * card form only and mount express buttons in your own page via
+     * `createFlintNExpressButtons` — note `formFields.formVariant` LIST/RADIO
+     * are ignored in that case.
+     */
+    expressButtons?: boolean;
 }
 declare const PaymentMethod: {
     readonly PAYMENT_CARD: "PAYMENT_CARD";
@@ -173,6 +181,8 @@ declare const FieldEventType: {
     readonly FIELD_HEIGHT: "FIELD_HEIGHT";
     readonly FIELD_THREE_DS_REQUIRED: "FIELD_THREE_DS_REQUIRED";
     readonly FIELD_THREE_DS_RESULT: "FIELD_THREE_DS_RESULT";
+    readonly FIELD_PAYMENT_ATTEMPT: "FIELD_PAYMENT_ATTEMPT";
+    readonly FIELD_POSTAL_CODE_REQUIREMENT: "FIELD_POSTAL_CODE_REQUIREMENT";
 };
 type TFieldEventType = (typeof FieldEventType)[keyof typeof FieldEventType];
 interface FieldOptions {
@@ -220,7 +230,7 @@ interface ExpressCapability {
     googlePay: boolean;
     paypal: boolean;
 }
-interface ExpressAttempt {
+interface AttemptEvent {
     event: TPaymentAttemptResult;
     method: TPaymentMethod;
     paymentId?: string;
@@ -240,6 +250,15 @@ interface FlintNFieldsOptions {
     onChange?: (event: FieldChangeEvent) => void;
     onFocus?: (fieldType: TFieldType) => void;
     onBlur?: (fieldType: TFieldType, state: FieldState) => void;
+    /** Per-attempt analytics for the card flow (express buttons have their own). */
+    onEvent?: (event: AttemptEvent) => void;
+    /**
+     * The entered card BIN requires (or stops requiring) a postal code. Show
+     * your own postal field and pass its value via submit's
+     * `billingAddress.postalCode` — submit fails with POSTAL_CODE_REQUIRED
+     * otherwise.
+     */
+    onPostalCodeRequirement?: (required: boolean) => void;
     onError?: (error: PaymentError) => void;
     debug?: boolean;
 }
@@ -293,7 +312,7 @@ interface FlintNExpressButtonsOptions {
     apiUrl?: string;
     buttonBorderRadius?: number;
     onPayment?: (result: PaymentResult) => void;
-    onEvent?: (event: ExpressAttempt) => void;
+    onEvent?: (event: AttemptEvent) => void;
     onCapability?: (capability: ExpressCapability) => void;
     onError?: (error: PaymentError) => void;
     debug?: boolean;
@@ -349,8 +368,11 @@ interface AuthorizeResponse {
     };
     status_reason?: {
         decline_reason?: string;
+        decline_code?: string;
+        decline_type?: 'SOFT_DECLINE' | 'HARD_DECLINE';
         message?: string;
     };
+    session_retryable?: boolean;
 }
 interface ApplePayToken {
     payment_data: {
@@ -377,7 +399,9 @@ interface GooglePayToken {
 interface WalletAuthorizeHandlers {
     onAuthorized: (paymentId: string) => void;
     onThreeDs: (redirectUrl: string, paymentId: string) => void;
-    onFailed: (code: string, message: string, paymentId?: string) => void;
+    onFailed: (code: string, message: string, paymentId?: string, 
+    /** Attempt analytics classification; defaults to HARD_DECLINE. */
+    event?: TPaymentAttemptResult) => void;
 }
 
 /**
@@ -425,4 +449,4 @@ declare const validateConfig: (config: {
 }) => void;
 declare const sanitizeToken: (token: string) => string;
 
-export { type ApplePayConfig, type ApplePayToken, type AuthorizeResponse, AuthorizedStatus, type CheckoutEvent, CheckoutFormVariant, CheckoutView, EXPRESS_BUTTON_HEIGHT, EventType, type ExpressAttempt, type ExpressButtonMount, type ExpressButtonsOptions, type ExpressCapability, ExpressMethod, type FieldChangeEvent, FieldEventType, type FieldOptions, type FieldState, FieldType, type FieldValidationResult, type FieldsValidationResult, type FlintNConfig, type FlintNExpressButtons, type FlintNExpressButtonsOptions, type FlintNField, type FlintNFieldInternalCallbacks, type FlintNFields, type FlintNFieldsConfig, type FlintNFieldsOptions, type FlintNPayment, type FlintNPaymentOptions, type FormFields, type FormPlaceholders, type FormStyles, type GooglePayConfig, type GooglePayToken, type PayPalConfig, type PaymentAttempt, PaymentAttemptResult, type PaymentError, PaymentMethod, type PaymentResult, type PaymentUI, PaymentUIEvent, type SessionConfig, type SubmitBillingAddress, type SubmitOptions, type TAuthorizedStatus, type TCheckoutFormVariant, type TCheckoutView, type TEventType, type TExpressMethod, type TFieldEventType, type TFieldType, type TPaymentAttemptResult, type TPaymentMethod, type TPaymentUIEvent, type WalletAuthorizeHandlers, buildIframeSrc, createFlintNExpressButtons, createFlintNField, createFlintNFields, createFlintNPayment, createIframeElement, deriveApiUrl, isAttemptEvent, isUIEvent, parseOrigin, sanitizeToken, validateConfig };
+export { type ApplePayConfig, type ApplePayToken, type AttemptEvent, type AuthorizeResponse, AuthorizedStatus, type CheckoutEvent, CheckoutFormVariant, CheckoutView, EXPRESS_BUTTON_HEIGHT, EventType, type ExpressButtonMount, type ExpressButtonsOptions, type ExpressCapability, ExpressMethod, type FieldChangeEvent, FieldEventType, type FieldOptions, type FieldState, FieldType, type FieldValidationResult, type FieldsValidationResult, type FlintNConfig, type FlintNExpressButtons, type FlintNExpressButtonsOptions, type FlintNField, type FlintNFieldInternalCallbacks, type FlintNFields, type FlintNFieldsConfig, type FlintNFieldsOptions, type FlintNPayment, type FlintNPaymentOptions, type FormFields, type FormPlaceholders, type FormStyles, type GooglePayConfig, type GooglePayToken, type PayPalConfig, type PaymentAttempt, PaymentAttemptResult, type PaymentError, PaymentMethod, type PaymentResult, type PaymentUI, PaymentUIEvent, type SessionConfig, type SubmitBillingAddress, type SubmitOptions, type TAuthorizedStatus, type TCheckoutFormVariant, type TCheckoutView, type TEventType, type TExpressMethod, type TFieldEventType, type TFieldType, type TPaymentAttemptResult, type TPaymentMethod, type TPaymentUIEvent, type WalletAuthorizeHandlers, buildIframeSrc, createFlintNExpressButtons, createFlintNField, createFlintNFields, createFlintNPayment, createIframeElement, deriveApiUrl, isAttemptEvent, isUIEvent, parseOrigin, sanitizeToken, validateConfig };

package/dist/index.js

@@ -113,7 +113,14 @@ var FieldEventType = {
   // modal (the field iframe is too small, and popups get blocked).
   FIELD_THREE_DS_REQUIRED: "FIELD_THREE_DS_REQUIRED",
   // SDK reports the challenge outcome back into the card iframe.
-  FIELD_THREE_DS_RESULT: "FIELD_THREE_DS_RESULT"
+  FIELD_THREE_DS_RESULT: "FIELD_THREE_DS_RESULT",
+  // Card iframe reports attempt analytics (INITIATED / declines / …) which
+  // the SDK forwards to the merchant's onEvent — same stream the direct
+  // iframe checkout emits.
+  FIELD_PAYMENT_ATTEMPT: "FIELD_PAYMENT_ATTEMPT",
+  // Card iframe reports whether the entered BIN requires a postal code so
+  // the merchant can show/require their own postal field.
+  FIELD_POSTAL_CODE_REQUIREMENT: "FIELD_POSTAL_CODE_REQUIREMENT"
 };
 
 // src/utils.ts
@@ -583,15 +590,24 @@ var ExpressApi = class {
       } else if (res.status === AuthorizedStatus.THREE_DS_INITIATED && res.required_action?.type === "REDIRECT_TO_URL") {
         handlers.onThreeDs(res.required_action.redirect_url, res.id);
       } else {
-        const code = declineCodeOf(
-          res.status_reason?.decline_reason,
-          res.status === AuthorizedStatus.DECLINED ? "PAYMENT_DECLINED" : "PAYMENT_FAILED"
+        const fallback = res.status === AuthorizedStatus.DECLINED ? "PAYMENT_DECLINED" : "PAYMENT_FAILED";
+        const code = declineCodeOf(res.status_reason?.decline_code, fallback);
+        const isHard = res.status_reason?.decline_type === "HARD_DECLINE" || res.status_reason?.decline_type == null && res.session_retryable === false;
+        handlers.onFailed(
+          code,
+          res.status_reason?.message ?? (fallback === "PAYMENT_DECLINED" ? "Payment declined." : "Payment failed."),
+          res.id,
+          res.status === AuthorizedStatus.DECLINED && !isHard ? PaymentAttemptResult.SOFT_DECLINE : PaymentAttemptResult.HARD_DECLINE
         );
-        handlers.onFailed(code, res.status_reason?.message ?? code, res.id);
       }
     } catch (err) {
       const code = errorCodeOf(err, "UNKNOWN_ERROR");
-      handlers.onFailed(code, err instanceof Error ? err.message : code);
+      handlers.onFailed(
+        code,
+        err instanceof Error ? err.message : code,
+        void 0,
+        PaymentAttemptResult.NETWORK_ERROR
+      );
     }
   }
   /**
@@ -1115,7 +1131,12 @@ var extractThreeDsResult = (event, check) => {
   if (!check.expectedSource || event.source !== check.expectedSource) {
     return null;
   }
-  const { type, payment_id: paymentId, status } = event.data ?? {};
+  const {
+    type,
+    payment_id: paymentId,
+    status,
+    decline_code: declineCode
+  } = event.data ?? {};
   if (type !== "3ds-result" || !status || paymentId !== check.expectedPaymentId) {
     return null;
   }
@@ -1129,7 +1150,10 @@ var extractThreeDsResult = (event, check) => {
     );
     return null;
   }
-  return String(status);
+  return {
+    status: String(status),
+    declineCode: typeof declineCode === "string" && declineCode ? declineCode : void 0
+  };
 };
 
 // src/express/three-ds.ts
@@ -1152,16 +1176,16 @@ var createThreeDsPopup = (payOrigin, handlers) => {
     expectedPaymentId = null;
   };
   const handleMessage = (event) => {
-    const status = extractThreeDsResult(event, {
+    const result = extractThreeDsResult(event, {
       expectedSource: popup,
       allowedOrigins,
       expectedPaymentId
     });
-    if (status === null || handled) return;
+    if (result === null || handled) return;
     const paymentId = expectedPaymentId;
     handled = true;
     cleanup();
-    handlers.onComplete(paymentId, status);
+    handlers.onComplete(paymentId, result.status, result.declineCode);
   };
   window.addEventListener("message", handleMessage);
   const open = (redirectUrl, paymentId) => {
@@ -1272,24 +1296,28 @@ function createFlintNExpressButtons(options) {
   };
   let threeDsMethod = ExpressMethod.APPLE_PAY;
   const threeDs = createThreeDsPopup(payOrigin, {
-    onComplete: (paymentId, status) => {
+    onComplete: (paymentId, status, declineCode) => {
       if (status === "AUTHORIZED") succeed(threeDsMethod, paymentId);
-      else
-        fail(
-          threeDsMethod,
-          status === "DECLINED" ? "THREE_DS_FAILED" : "PAYMENT_FAILED",
-          status,
-          { paymentId }
-        );
+      else {
+        const code = declineCode ?? (status === "DECLINED" ? "PAYMENT_DECLINED" : "PAYMENT_FAILED");
+        const message = status === "DECLINED" ? "Payment declined." : "Payment failed.";
+        fail(threeDsMethod, code, message, { paymentId });
+      }
     },
-    onClose: () => fail(threeDsMethod, "THREE_DS_CANCELLED", "THREE_DS_CANCELLED", {
-      event: PaymentAttemptResult.CANCELLED
-    }),
+    onClose: () => fail(
+      threeDsMethod,
+      "THREE_DS_CANCELLED",
+      "3DS verification was cancelled by the buyer.",
+      { event: PaymentAttemptResult.CANCELLED }
+    ),
     // Routed through fail() so analytics get a terminal attempt event too
     // (NETWORK_ERROR — a client-side technical failure, not a decline).
-    onPopupBlocked: () => fail(threeDsMethod, "THREE_DS_POPUP_BLOCKED", "THREE_DS_POPUP_BLOCKED", {
-      event: PaymentAttemptResult.NETWORK_ERROR
-    })
+    onPopupBlocked: () => fail(
+      threeDsMethod,
+      "THREE_DS_POPUP_BLOCKED",
+      "The 3DS verification window was blocked by the browser.",
+      { event: PaymentAttemptResult.NETWORK_ERROR }
+    )
   });
   const walletHandlers = (method) => (complete) => ({
     onAuthorized: (paymentId) => {
@@ -1306,9 +1334,9 @@ function createFlintNExpressButtons(options) {
       threeDsMethod = method;
       threeDs.open(redirectUrl, paymentId);
     },
-    onFailed: (code, message, paymentId) => {
+    onFailed: (code, message, paymentId, event) => {
       complete(false, message);
-      fail(method, code, message, { paymentId });
+      fail(method, code, message, { paymentId, event });
     }
   });
   const detection = (async () => {
@@ -1531,7 +1559,7 @@ var openThreeDsDialog = (options) => {
     }
   };
   let finished = false;
-  const finish = (status) => {
+  const finish = (status, declineCode) => {
     if (finished) return;
     finished = true;
     window.removeEventListener("message", handleMessage);
@@ -1539,15 +1567,15 @@ var openThreeDsDialog = (options) => {
     overlay.remove();
     closeCurrent = null;
     previouslyFocused?.focus();
-    options.onFinish(status);
+    options.onFinish(status, declineCode);
   };
   const handleMessage = (event) => {
-    const status = extractThreeDsResult(event, {
+    const result = extractThreeDsResult(event, {
       expectedSource: iframe.contentWindow,
       allowedOrigins: options.allowedOrigins,
       expectedPaymentId: options.paymentId
     });
-    if (status !== null) finish(status);
+    if (result !== null) finish(result.status, result.declineCode);
   };
   closeButton.addEventListener("click", () => finish("CANCELLED"));
   window.addEventListener("message", handleMessage);
@@ -1683,6 +1711,26 @@ function createFlintNFields(options) {
       }
       return;
     }
+    if (type === FieldEventType.FIELD_PAYMENT_ATTEMPT) {
+      log("Attempt event:", payload);
+      const { event: attemptEvent, paymentId, code, message } = payload ?? {};
+      if (attemptEvent) {
+        options.onEvent?.({
+          event: attemptEvent,
+          method: PaymentMethod.PAYMENT_CARD,
+          paymentId,
+          code,
+          message,
+          timestamp: Date.now()
+        });
+      }
+      return;
+    }
+    if (type === FieldEventType.FIELD_POSTAL_CODE_REQUIREMENT) {
+      log("Postal code requirement:", payload);
+      options.onPostalCodeRequirement?.(!!payload?.required);
+      return;
+    }
     if (type === FieldEventType.FIELD_VALIDATION && fieldType) {
       log("FIELD_VALIDATION received:", fieldType, payload);
       const pending = pendingValidations.get(fieldType);
@@ -1710,11 +1758,12 @@ function createFlintNFields(options) {
       redirectUrl,
       paymentId,
       allowedOrigins: threeDsResultOrigins(origin, apiUrl),
-      onFinish: (status) => {
+      onFinish: (status, declineCode) => {
         log("3DS challenge finished:", status);
         fields.get(fieldType)?._sendMessage(FieldEventType.FIELD_THREE_DS_RESULT, {
           paymentId,
-          status
+          status,
+          declineCode
         });
       }
     });