flintn-checkout 0.0.16 → 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**
 
@@ -331,7 +331,11 @@ function CheckoutForm() {
         </div>
         <div style={{ flex: 1 }}>
           <label>CVV</label>
-          <div ref={cvvRef} style={{ height: 40, marginBottom: 4 }} />
+          {/* position/zIndex let the CVV helper panel overlay content below */}
+          <div
+            ref={cvvRef}
+            style={{ height: 40, marginBottom: 4, position: 'relative', zIndex: 1 }}
+          />
           {fieldErrors['cvv'] && (
             <span style={{ color: 'red' }}>{fieldErrors['cvv']}</span>
           )}
@@ -379,7 +383,7 @@ const fields = createFlintNFields({
 
 const cardNumber = fields.createField('card-number', { placeholder: '4111 1111 1111 1111' });
 const expiry = fields.createField('expiry', { placeholder: 'MM/YY' });
-const cvv = fields.createField('cvv', { placeholder: 'CVC' });
+const cvv = fields.createField('cvv');
 
 cardNumber.mount('#card-number');
 expiry.mount('#expiry');
@@ -405,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 |
 
@@ -429,13 +435,13 @@ 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
 
 | Property | Type | Default | Description |
 |----------|------|---------|-------------|
-| `placeholder` | `string` | Field-specific default | Input placeholder text |
+| `placeholder` | `string` | `'1234 1234 1234 1234'` / `'MM/YY'` / `'***'` | Input placeholder text |
 | `disabled` | `boolean` | `false` | Disable the input |
 
 ### React Hook Return Values
@@ -453,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 |
@@ -469,6 +476,29 @@ Validation mirrors react-hook-form `mode: 'onSubmit'`:
 - After first submit: errors update on every field change (revalidation)
 - Card number changes trigger CVV revalidation (CVV length depends on card brand)
 - 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
 
@@ -476,7 +506,7 @@ Validation mirrors react-hook-form `mode: 'onSubmit'`:
 |-------|-------------|
 | `'card-number'` | Card number input with automatic formatting and brand detection |
 | `'expiry'` | Expiry date input (MM/YY format) |
-| `'cvv'` | CVV/CVC input (3 or 4 digits depending on card brand) |
+| `'cvv'` | CVV/CVC input (3 or 4 digits depending on card brand). Includes a built-in “where to find CVV” helper: tapping the card icon expands an explainer panel below the input |
 
 ### Individual Field Methods (Vanilla JS)
 
@@ -612,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:
@@ -632,8 +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`) |
-| `MISSING_FIELDS` / `NOT_INITIALIZED` / `SUBMIT_IN_PROGRESS` / `SUBMIT_TIMEOUT` | payment | Card `submit()` preconditions / duplicate call / no response in time (30s; 10 min during a 3DS challenge) |
-| `PAYMENT_DECLINED` / processor decline codes | payment | Declined; the processor's own code is passed through when present |
+| `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 |
+| `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
+      );
     }
   }
   /**
@@ -793,7 +811,7 @@ var injectAppleButtonStyle = () => {
   if (document.getElementById(APPLE_STYLE_ID)) return;
   const style = document.createElement("style");
   style.id = APPLE_STYLE_ID;
-  style.textContent = `.${APPLE_BUTTON_CLASS}{cursor:pointer;transition:opacity .15s ease-in-out,transform .1s ease-in-out;}.${APPLE_BUTTON_CLASS}:hover{opacity:.9;}.${APPLE_BUTTON_CLASS}:active{opacity:.8;transform:scale(.99);}.${APPLE_BUTTON_CLASS}:focus-visible{outline:2px solid #0071e3;outline-offset:2px;}`;
+  style.textContent = `.${APPLE_BUTTON_CLASS}{cursor:pointer;transition:opacity .15s ease-in-out;}.${APPLE_BUTTON_CLASS}:hover{opacity:.8;}.${APPLE_BUTTON_CLASS}:active{opacity:.7;}.${APPLE_BUTTON_CLASS}:focus-visible{outline:2px solid #0071e3;outline-offset:2px;}`;
   document.head.appendChild(style);
 };
 var mountApplePayButton = (container, config, api, borderRadius, callbacks) => {
@@ -818,17 +836,23 @@ var mountApplePayButton = (container, config, api, borderRadius, callbacks) => {
     if (processing || !applePayConfig || version === null) return;
     if (!callbacks.canStart()) return;
     callbacks.onStart();
-    const session = new window.ApplePaySession(version, {
-      countryCode: applePayConfig.country_code,
-      currencyCode: config.session.currency_code,
-      supportedNetworks: applePayConfig.supported_networks,
-      merchantCapabilities: applePayConfig.merchant_capabilities,
-      total: {
-        label: applePayConfig.display_name,
-        amount: (config.session.amount / 100).toFixed(2),
-        type: "final"
-      }
-    });
+    let session;
+    try {
+      session = new window.ApplePaySession(version, {
+        countryCode: applePayConfig.country_code,
+        currencyCode: config.session.currency_code,
+        supportedNetworks: applePayConfig.supported_networks,
+        merchantCapabilities: applePayConfig.merchant_capabilities,
+        total: {
+          label: applePayConfig.display_name,
+          amount: (config.session.amount / 100).toFixed(2),
+          type: "final"
+        }
+      });
+    } catch {
+      callbacks.onSdkError("Apple Pay is not available in this browser.");
+      return;
+    }
     processing = true;
     let abortedDueToError = false;
     session.onvalidatemerchant = async (event) => {
@@ -871,7 +895,13 @@ var mountApplePayButton = (container, config, api, borderRadius, callbacks) => {
       }
       callbacks.onCancel();
     };
-    session.begin();
+    try {
+      session.begin();
+    } catch {
+      processing = false;
+      callbacks.onSdkError("Apple Pay is not available in this browser.");
+      return;
+    }
     styleApplePayModalWhenReady();
   };
   button.addEventListener("click", handleClick);
@@ -962,13 +992,15 @@ var detectGooglePay = async (config) => {
 };
 var GPAY_WRAP_CLASS = "flintn-gpay";
 var GPAY_STYLE_ID = "flintn-gpay-style";
+var gpaySurfaceSelectors = [".gpay-button", ".gpay-card-info-container"].flatMap((s) => [s, `${s}:hover`, `${s}:active`, `${s}.hover`, `${s}.active`]).map((s) => `.${GPAY_WRAP_CLASS} ${s}`).join(",");
 var injectGpayStyle = () => {
   if (document.getElementById(GPAY_STYLE_ID)) return;
   const style = document.createElement("style");
   style.id = GPAY_STYLE_ID;
-  style.textContent = `.gpay-button:focus:not(:focus-visible){outline:none;box-shadow:none;}.gpay-button-fill:focus-within:not(:has(:focus-visible)){outline:none;box-shadow:none;}.${GPAY_WRAP_CLASS}{cursor:pointer;}.${GPAY_WRAP_CLASS} button{height:100%;cursor:pointer;}.${GPAY_WRAP_CLASS} > *{width:100%;height:100%;}`;
+  style.textContent = `.gpay-button:focus:not(:focus-visible){outline:none;box-shadow:none;}.gpay-button-fill:focus-within:not(:has(:focus-visible)){outline:none;box-shadow:none;}.${GPAY_WRAP_CLASS}{cursor:pointer;transition:opacity .15s ease-in-out;}.${GPAY_WRAP_CLASS}:hover{opacity:.8;}.${GPAY_WRAP_CLASS}:active{opacity:.7;}.${GPAY_WRAP_CLASS} button{height:100%;cursor:pointer;}${gpaySurfaceSelectors}{border:none!important;outline:none!important;box-shadow:none!important;background-color:#000!important;}.${GPAY_WRAP_CLASS} .gpay-card-info-container:focus-visible,.${GPAY_WRAP_CLASS} .gpay-button:focus-visible{outline:2px solid #0071e3!important;outline-offset:2px;}.${GPAY_WRAP_CLASS} .gpay-card-info-iframe{display:none!important;}.${GPAY_WRAP_CLASS} .gpay-button-fill,.${GPAY_WRAP_CLASS} .gpay-card-info-animation-container-fade-out{opacity:1!important;}.${GPAY_WRAP_CLASS} .gpay-button-static-content-container-loading::before,.${GPAY_WRAP_CLASS} .gpay-button-static-content-container-loading::after{display:none!important;}.${GPAY_WRAP_CLASS} .gpay-button.gpay-button-size-match-height{height:50%!important;}.${GPAY_WRAP_CLASS} > *{width:100%;height:100%;}`;
   document.head.appendChild(style);
 };
+var SHEET_SETTLE_GRACE_MS = 3e3;
 var mountGooglePayButton = (container, client, config, borderRadius, callbacks) => {
   let processing = false;
   const handleClick = () => {
@@ -977,7 +1009,31 @@ var mountGooglePayButton = (container, client, config, borderRadius, callbacks)
     if (!callbacks.canStart()) return;
     processing = true;
     callbacks.onStart();
+    let settled = false;
+    let graceTimer = null;
+    const disarmWatchdog = () => {
+      document.removeEventListener("visibilitychange", onVisibleAgain);
+      if (graceTimer !== null) clearTimeout(graceTimer);
+    };
+    const trySettle = () => {
+      if (settled) return false;
+      settled = true;
+      disarmWatchdog();
+      return true;
+    };
+    const onVisibleAgain = () => {
+      if (document.visibilityState !== "visible" || graceTimer !== null) {
+        return;
+      }
+      graceTimer = setTimeout(() => {
+        if (!trySettle()) return;
+        processing = false;
+        callbacks.onCancel();
+      }, SHEET_SETTLE_GRACE_MS);
+    };
+    document.addEventListener("visibilitychange", onVisibleAgain);
     client.loadPaymentData(request2).then((paymentData) => {
+      if (!trySettle()) return;
       const complete = (_success, errorMessage) => {
         processing = false;
         if (errorMessage) callbacks.onSdkError(errorMessage);
@@ -987,6 +1043,7 @@ var mountGooglePayButton = (container, client, config, borderRadius, callbacks)
         callbacks.handlers(complete)
       );
     }).catch((err) => {
+      if (!trySettle()) return;
       processing = false;
       if (err?.statusCode === "CANCELED") callbacks.onCancel();
       else callbacks.onSdkError("Google Pay payment failed");
@@ -1076,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;
   }
@@ -1090,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
@@ -1113,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) => {
@@ -1233,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
@@ -1267,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 () => {
@@ -1462,6 +1524,9 @@ var openThreeDsDialog = (options) => {
   overlay.id = OVERLAY_ID;
   overlay.style.cssText = "position: fixed; inset: 0; z-index: 2147483647; background: rgba(0, 0, 0, 0.5); display: flex; align-items: center; justify-content: center;";
   const panel = document.createElement("div");
+  panel.setAttribute("role", "dialog");
+  panel.setAttribute("aria-modal", "true");
+  panel.setAttribute("aria-label", "3DS verification");
   panel.style.cssText = `position: relative; background: #fff; border-radius: 8px; width: min(${PANEL_WIDTH}px, calc(100vw - 32px)); height: min(${PANEL_HEIGHT}px, calc(100vh - 32px)); box-shadow: 0 8px 40px rgba(0, 0, 0, 0.25); overflow: hidden;`;
   const closeButton = document.createElement("button");
   closeButton.type = "button";
@@ -1475,26 +1540,43 @@ var openThreeDsDialog = (options) => {
   iframe.style.cssText = "width: 100%; height: 100%; border: none; display: block;";
   panel.append(iframe, closeButton);
   overlay.appendChild(panel);
+  const previouslyFocused = document.activeElement instanceof HTMLElement ? document.activeElement : null;
+  const trapFocus = (event) => {
+    if (event.key !== "Tab") return;
+    const active = document.activeElement;
+    const inside = active !== null && overlay.contains(active);
+    if (event.shiftKey && (!inside || active === iframe)) {
+      event.preventDefault();
+      closeButton.focus();
+    } else if (!event.shiftKey && (!inside || active === closeButton)) {
+      event.preventDefault();
+      iframe.focus();
+    }
+  };
   let finished = false;
-  const finish = (status) => {
+  const finish = (status, declineCode) => {
     if (finished) return;
     finished = true;
     window.removeEventListener("message", handleMessage);
+    window.removeEventListener("keydown", trapFocus);
     overlay.remove();
     closeCurrent = null;
-    options.onFinish(status);
+    previouslyFocused?.focus();
+    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);
+  window.addEventListener("keydown", trapFocus);
   document.body.appendChild(overlay);
+  closeButton.focus();
   closeCurrent = () => finish("CANCELLED");
 };
 
@@ -1607,7 +1689,15 @@ function createFlintNFields(options) {
           const pending = pendingSubmit;
           pending.timer = setTimeout(() => {
             if (pendingSubmit === pending) {
-              pendingSubmit.reject(new Error("3DS challenge timed out"));
+              const timeoutResult = {
+                status: "PAYMENT_ERROR",
+                error: {
+                  code: "THREE_DS_TIMEOUT",
+                  message: "3DS challenge timed out"
+                }
+              };
+              pendingSubmit.resolve(timeoutResult);
+              options.onPayment?.(timeoutResult);
               pendingSubmit = null;
             }
           }, THREE_DS_TIMEOUT);
@@ -1616,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);
@@ -1643,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
         });
       }
     });