flintn-checkout 0.0.16 → 0.0.17

package/README.md

@@ -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');
@@ -435,7 +439,7 @@ Additional React-only options:
 
 | 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
@@ -469,6 +473,7 @@ 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
 
 ### Field Types
 
@@ -476,7 +481,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)
 
@@ -632,7 +637,8 @@ 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) |
+| `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 |
 | `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 |

package/dist/index.js

@@ -793,7 +793,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 +818,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 +877,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 +974,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 +991,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 +1025,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");
@@ -1462,6 +1501,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,13 +1517,28 @@ 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) => {
     if (finished) return;
     finished = true;
     window.removeEventListener("message", handleMessage);
+    window.removeEventListener("keydown", trapFocus);
     overlay.remove();
     closeCurrent = null;
+    previouslyFocused?.focus();
     options.onFinish(status);
   };
   const handleMessage = (event) => {
@@ -1494,7 +1551,9 @@ var openThreeDsDialog = (options) => {
   };
   closeButton.addEventListener("click", () => finish("CANCELLED"));
   window.addEventListener("message", handleMessage);
+  window.addEventListener("keydown", trapFocus);
   document.body.appendChild(overlay);
+  closeButton.focus();
   closeCurrent = () => finish("CANCELLED");
 };
 
@@ -1607,7 +1666,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);

package/dist/index.mjs

@@ -745,7 +745,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) => {
@@ -770,17 +770,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) => {
@@ -823,7 +829,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);
@@ -914,13 +926,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 = () => {
@@ -929,7 +943,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);
@@ -939,6 +977,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");
@@ -1414,6 +1453,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";
@@ -1427,13 +1469,28 @@ 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) => {
     if (finished) return;
     finished = true;
     window.removeEventListener("message", handleMessage);
+    window.removeEventListener("keydown", trapFocus);
     overlay.remove();
     closeCurrent = null;
+    previouslyFocused?.focus();
     options.onFinish(status);
   };
   const handleMessage = (event) => {
@@ -1446,7 +1503,9 @@ var openThreeDsDialog = (options) => {
   };
   closeButton.addEventListener("click", () => finish("CANCELLED"));
   window.addEventListener("message", handleMessage);
+  window.addEventListener("keydown", trapFocus);
   document.body.appendChild(overlay);
+  closeButton.focus();
   closeCurrent = () => finish("CANCELLED");
 };
 
@@ -1559,7 +1618,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);

package/dist/react.js

@@ -810,7 +810,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) => {
@@ -835,17 +835,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) => {
@@ -888,7 +894,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);
@@ -979,13 +991,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 = () => {
@@ -994,7 +1008,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);
@@ -1004,6 +1042,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");
@@ -1479,6 +1518,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";
@@ -1492,13 +1534,28 @@ 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) => {
     if (finished) return;
     finished = true;
     window.removeEventListener("message", handleMessage);
+    window.removeEventListener("keydown", trapFocus);
     overlay.remove();
     closeCurrent = null;
+    previouslyFocused?.focus();
     options.onFinish(status);
   };
   const handleMessage = (event) => {
@@ -1511,7 +1568,9 @@ var openThreeDsDialog = (options) => {
   };
   closeButton.addEventListener("click", () => finish("CANCELLED"));
   window.addEventListener("message", handleMessage);
+  window.addEventListener("keydown", trapFocus);
   document.body.appendChild(overlay);
+  closeButton.focus();
   closeCurrent = () => finish("CANCELLED");
 };
 
@@ -1624,7 +1683,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);
@@ -1867,7 +1934,7 @@ var DEFAULT_CARD_OPTIONS = {
   placeholder: "1234 1234 1234 1234"
 };
 var DEFAULT_EXPIRY_OPTIONS = { placeholder: "MM/YY" };
-var DEFAULT_CVV_OPTIONS = { placeholder: "CVC" };
+var DEFAULT_CVV_OPTIONS = { placeholder: "***" };
 function useFlintNFields(options) {
   const cardNumberRef = (0, import_react2.useRef)(null);
   const expiryRef = (0, import_react2.useRef)(null);

package/dist/react.mjs

@@ -783,7 +783,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) => {
@@ -808,17 +808,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) => {
@@ -861,7 +867,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);
@@ -952,13 +964,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 = () => {
@@ -967,7 +981,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);
@@ -977,6 +1015,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");
@@ -1452,6 +1491,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";
@@ -1465,13 +1507,28 @@ 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) => {
     if (finished) return;
     finished = true;
     window.removeEventListener("message", handleMessage);
+    window.removeEventListener("keydown", trapFocus);
     overlay.remove();
     closeCurrent = null;
+    previouslyFocused?.focus();
     options.onFinish(status);
   };
   const handleMessage = (event) => {
@@ -1484,7 +1541,9 @@ var openThreeDsDialog = (options) => {
   };
   closeButton.addEventListener("click", () => finish("CANCELLED"));
   window.addEventListener("message", handleMessage);
+  window.addEventListener("keydown", trapFocus);
   document.body.appendChild(overlay);
+  closeButton.focus();
   closeCurrent = () => finish("CANCELLED");
 };
 
@@ -1597,7 +1656,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);
@@ -1840,7 +1907,7 @@ var DEFAULT_CARD_OPTIONS = {
   placeholder: "1234 1234 1234 1234"
 };
 var DEFAULT_EXPIRY_OPTIONS = { placeholder: "MM/YY" };
-var DEFAULT_CVV_OPTIONS = { placeholder: "CVC" };
+var DEFAULT_CVV_OPTIONS = { placeholder: "***" };
 function useFlintNFields(options) {
   const cardNumberRef = useRef2(null);
   const expiryRef = useRef2(null);

package/package.json

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