flintn-checkout 0.0.17 → 0.0.18

package/README.md

@@ -166,7 +166,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_...' }
@@ -270,7 +270,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 +409,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 +435,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 +459,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 +478,28 @@ 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. 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 +642,23 @@ interface PaymentError {
 }
 ```
 
+### SubmitOptions (Hosted Fields)
+
+```typescript
+interface SubmitOptions {
+  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 +679,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) |

package/dist/index.d.mts

@@ -173,6 +173,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 +222,7 @@ interface ExpressCapability {
     googlePay: boolean;
     paypal: boolean;
 }
-interface ExpressAttempt {
+interface AttemptEvent {
     event: TPaymentAttemptResult;
     method: TPaymentMethod;
     paymentId?: string;
@@ -240,6 +242,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 +304,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 +360,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 +391,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 +441,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

@@ -173,6 +173,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 +222,7 @@ interface ExpressCapability {
     googlePay: boolean;
     paypal: boolean;
 }
-interface ExpressAttempt {
+interface AttemptEvent {
     event: TPaymentAttemptResult;
     method: TPaymentMethod;
     paymentId?: string;
@@ -240,6 +242,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 +304,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 +360,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 +391,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 +441,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
@@ -584,14 +591,25 @@ var ExpressApi = class {
         handlers.onThreeDs(res.required_action.redirect_url, res.id);
       } else {
         const code = declineCodeOf(
-          res.status_reason?.decline_reason,
+          res.status_reason?.decline_code,
           res.status === AuthorizedStatus.DECLINED ? "PAYMENT_DECLINED" : "PAYMENT_FAILED"
         );
-        handlers.onFailed(code, res.status_reason?.message ?? code, res.id);
+        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 ?? code,
+          res.id,
+          res.status === AuthorizedStatus.DECLINED && !isHard ? PaymentAttemptResult.SOFT_DECLINE : PaymentAttemptResult.HARD_DECLINE
+        );
       }
     } 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 +1133,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 +1152,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 +1178,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,15 +1298,12 @@ 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");
+        fail(threeDsMethod, code, code, { paymentId });
+      }
     },
     onClose: () => fail(threeDsMethod, "THREE_DS_CANCELLED", "THREE_DS_CANCELLED", {
       event: PaymentAttemptResult.CANCELLED
@@ -1306,9 +1329,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 +1554,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 +1562,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 +1706,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 +1753,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
         });
       }
     });

package/dist/index.mjs

@@ -65,7 +65,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
@@ -536,14 +543,25 @@ var ExpressApi = class {
         handlers.onThreeDs(res.required_action.redirect_url, res.id);
       } else {
         const code = declineCodeOf(
-          res.status_reason?.decline_reason,
+          res.status_reason?.decline_code,
           res.status === AuthorizedStatus.DECLINED ? "PAYMENT_DECLINED" : "PAYMENT_FAILED"
         );
-        handlers.onFailed(code, res.status_reason?.message ?? code, res.id);
+        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 ?? code,
+          res.id,
+          res.status === AuthorizedStatus.DECLINED && !isHard ? PaymentAttemptResult.SOFT_DECLINE : PaymentAttemptResult.HARD_DECLINE
+        );
       }
     } 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
+      );
     }
   }
   /**
@@ -1067,7 +1085,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;
   }
@@ -1081,7 +1104,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
@@ -1104,16 +1130,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) => {
@@ -1224,15 +1250,12 @@ 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");
+        fail(threeDsMethod, code, code, { paymentId });
+      }
     },
     onClose: () => fail(threeDsMethod, "THREE_DS_CANCELLED", "THREE_DS_CANCELLED", {
       event: PaymentAttemptResult.CANCELLED
@@ -1258,9 +1281,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 () => {
@@ -1483,7 +1506,7 @@ var openThreeDsDialog = (options) => {
     }
   };
   let finished = false;
-  const finish = (status) => {
+  const finish = (status, declineCode) => {
     if (finished) return;
     finished = true;
     window.removeEventListener("message", handleMessage);
@@ -1491,15 +1514,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);
@@ -1635,6 +1658,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);
@@ -1662,11 +1705,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
         });
       }
     });

package/dist/react.d.mts

@@ -190,7 +190,7 @@ interface SubmitOptions {
     email?: string;
     billingAddress?: SubmitBillingAddress;
 }
-interface ExpressAttempt {
+interface AttemptEvent {
     event: TPaymentAttemptResult;
     method: TPaymentMethod;
     paymentId?: string;
@@ -210,6 +210,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;
 }
@@ -247,7 +256,7 @@ interface UseFlintNFieldsOptions extends Omit<FlintNFieldsOptions, OmittedKeys>
      * `expressCapability` return value (hide a ref's container when its method
      * is unavailable).
      */
-    onEvent?: (event: ExpressAttempt) => void;
+    onEvent?: (event: AttemptEvent) => void;
     onChange?: (event: FieldChangeEvent) => void;
     onFocus?: (fieldType: TFieldType) => void;
     onBlur?: (fieldType: TFieldType, state: FieldState) => void;
@@ -274,6 +283,11 @@ interface UseFlintNFieldsReturn {
     fieldErrors: FieldErrorsMap;
     fieldStates: FieldStatesMap;
     cardBrand: string | null;
+    /**
+     * The entered card BIN requires a postal code — show your postal field and
+     * pass its value via submit's `billingAddress.postalCode`.
+     */
+    postalCodeRequired: boolean;
     paymentResult: PaymentResult | null;
     validate: () => Promise<FieldsValidationResult>;
     submit: (options?: SubmitOptions) => Promise<PaymentResult>;

package/dist/react.d.ts

@@ -190,7 +190,7 @@ interface SubmitOptions {
     email?: string;
     billingAddress?: SubmitBillingAddress;
 }
-interface ExpressAttempt {
+interface AttemptEvent {
     event: TPaymentAttemptResult;
     method: TPaymentMethod;
     paymentId?: string;
@@ -210,6 +210,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;
 }
@@ -247,7 +256,7 @@ interface UseFlintNFieldsOptions extends Omit<FlintNFieldsOptions, OmittedKeys>
      * `expressCapability` return value (hide a ref's container when its method
      * is unavailable).
      */
-    onEvent?: (event: ExpressAttempt) => void;
+    onEvent?: (event: AttemptEvent) => void;
     onChange?: (event: FieldChangeEvent) => void;
     onFocus?: (fieldType: TFieldType) => void;
     onBlur?: (fieldType: TFieldType, state: FieldState) => void;
@@ -274,6 +283,11 @@ interface UseFlintNFieldsReturn {
     fieldErrors: FieldErrorsMap;
     fieldStates: FieldStatesMap;
     cardBrand: string | null;
+    /**
+     * The entered card BIN requires a postal code — show your postal field and
+     * pass its value via submit's `billingAddress.postalCode`.
+     */
+    postalCodeRequired: boolean;
     paymentResult: PaymentResult | null;
     validate: () => Promise<FieldsValidationResult>;
     submit: (options?: SubmitOptions) => Promise<PaymentResult>;

package/dist/react.js

@@ -41,6 +41,14 @@ var EventType = {
   REDIRECT: "REDIRECT",
   RESIZE: "RESIZE"
 };
+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",
@@ -72,7 +80,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
@@ -601,14 +616,25 @@ var ExpressApi = class {
         handlers.onThreeDs(res.required_action.redirect_url, res.id);
       } else {
         const code = declineCodeOf(
-          res.status_reason?.decline_reason,
+          res.status_reason?.decline_code,
           res.status === AuthorizedStatus.DECLINED ? "PAYMENT_DECLINED" : "PAYMENT_FAILED"
         );
-        handlers.onFailed(code, res.status_reason?.message ?? code, res.id);
+        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 ?? code,
+          res.id,
+          res.status === AuthorizedStatus.DECLINED && !isHard ? PaymentAttemptResult.SOFT_DECLINE : PaymentAttemptResult.HARD_DECLINE
+        );
       }
     } 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
+      );
     }
   }
   /**
@@ -1132,7 +1158,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;
   }
@@ -1146,7 +1177,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
@@ -1169,16 +1203,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) => {
@@ -1289,15 +1323,12 @@ 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");
+        fail(threeDsMethod, code, code, { paymentId });
+      }
     },
     onClose: () => fail(threeDsMethod, "THREE_DS_CANCELLED", "THREE_DS_CANCELLED", {
       event: PaymentAttemptResult.CANCELLED
@@ -1323,9 +1354,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 () => {
@@ -1548,7 +1579,7 @@ var openThreeDsDialog = (options) => {
     }
   };
   let finished = false;
-  const finish = (status) => {
+  const finish = (status, declineCode) => {
     if (finished) return;
     finished = true;
     window.removeEventListener("message", handleMessage);
@@ -1556,15 +1587,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);
@@ -1700,6 +1731,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);
@@ -1727,11 +1778,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
         });
       }
     });
@@ -1956,6 +2008,7 @@ function useFlintNFields(options) {
   const [fieldErrors, setFieldErrors] = (0, import_react2.useState)({});
   const [fieldStates, setFieldStates] = (0, import_react2.useState)({});
   const [cardBrand, setCardBrand] = (0, import_react2.useState)(null);
+  const [postalCodeRequired, setPostalCodeRequired] = (0, import_react2.useState)(false);
   const [expressCapability, setExpressCapability] = (0, import_react2.useState)(null);
   const isSubmittedRef = (0, import_react2.useRef)(false);
   const latestErrorsRef = (0, import_react2.useRef)({});
@@ -1979,6 +2032,7 @@ function useFlintNFields(options) {
     setFieldErrors({});
     setFieldStates({});
     setCardBrand(null);
+    setPostalCodeRequired(false);
     setExpressCapability(null);
     isSubmittedRef.current = false;
     latestErrorsRef.current = {};
@@ -1992,6 +2046,10 @@ function useFlintNFields(options) {
           setPaymentResult(result);
           onPaymentRef.current?.(result);
         },
+        // Card-flow attempt analytics; express buttons wire the same
+        // callback below, giving the merchant one event stream.
+        onEvent: (event) => onEventRef.current?.(event),
+        onPostalCodeRequirement: (required) => setPostalCodeRequired(required),
         onChange: (event) => {
           setFieldStates((prev) => ({
             ...prev,
@@ -2209,6 +2267,7 @@ function useFlintNFields(options) {
     fieldErrors,
     fieldStates,
     cardBrand,
+    postalCodeRequired,
     paymentResult,
     validate,
     submit,

package/dist/react.mjs

@@ -14,6 +14,14 @@ var EventType = {
   REDIRECT: "REDIRECT",
   RESIZE: "RESIZE"
 };
+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",
@@ -45,7 +53,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
@@ -574,14 +589,25 @@ var ExpressApi = class {
         handlers.onThreeDs(res.required_action.redirect_url, res.id);
       } else {
         const code = declineCodeOf(
-          res.status_reason?.decline_reason,
+          res.status_reason?.decline_code,
           res.status === AuthorizedStatus.DECLINED ? "PAYMENT_DECLINED" : "PAYMENT_FAILED"
         );
-        handlers.onFailed(code, res.status_reason?.message ?? code, res.id);
+        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 ?? code,
+          res.id,
+          res.status === AuthorizedStatus.DECLINED && !isHard ? PaymentAttemptResult.SOFT_DECLINE : PaymentAttemptResult.HARD_DECLINE
+        );
       }
     } 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
+      );
     }
   }
   /**
@@ -1105,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;
   }
@@ -1119,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
@@ -1142,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) => {
@@ -1262,15 +1296,12 @@ 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");
+        fail(threeDsMethod, code, code, { paymentId });
+      }
     },
     onClose: () => fail(threeDsMethod, "THREE_DS_CANCELLED", "THREE_DS_CANCELLED", {
       event: PaymentAttemptResult.CANCELLED
@@ -1296,9 +1327,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 () => {
@@ -1521,7 +1552,7 @@ var openThreeDsDialog = (options) => {
     }
   };
   let finished = false;
-  const finish = (status) => {
+  const finish = (status, declineCode) => {
     if (finished) return;
     finished = true;
     window.removeEventListener("message", handleMessage);
@@ -1529,15 +1560,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);
@@ -1673,6 +1704,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);
@@ -1700,11 +1751,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
         });
       }
     });
@@ -1929,6 +1981,7 @@ function useFlintNFields(options) {
   const [fieldErrors, setFieldErrors] = useState2({});
   const [fieldStates, setFieldStates] = useState2({});
   const [cardBrand, setCardBrand] = useState2(null);
+  const [postalCodeRequired, setPostalCodeRequired] = useState2(false);
   const [expressCapability, setExpressCapability] = useState2(null);
   const isSubmittedRef = useRef2(false);
   const latestErrorsRef = useRef2({});
@@ -1952,6 +2005,7 @@ function useFlintNFields(options) {
     setFieldErrors({});
     setFieldStates({});
     setCardBrand(null);
+    setPostalCodeRequired(false);
     setExpressCapability(null);
     isSubmittedRef.current = false;
     latestErrorsRef.current = {};
@@ -1965,6 +2019,10 @@ function useFlintNFields(options) {
           setPaymentResult(result);
           onPaymentRef.current?.(result);
         },
+        // Card-flow attempt analytics; express buttons wire the same
+        // callback below, giving the merchant one event stream.
+        onEvent: (event) => onEventRef.current?.(event),
+        onPostalCodeRequirement: (required) => setPostalCodeRequired(required),
         onChange: (event) => {
           setFieldStates((prev) => ({
             ...prev,
@@ -2182,6 +2240,7 @@ function useFlintNFields(options) {
     fieldErrors,
     fieldStates,
     cardBrand,
+    postalCodeRequired,
     paymentResult,
     validate,
     submit,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "flintn-checkout",
-  "version": "0.0.17",
+  "version": "0.0.18",
   "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",