flintn-checkout 0.0.18 → 0.0.19

package/README.md

@@ -10,7 +10,7 @@ npm install flintn-checkout
 
 ## Iframe Checkout
 
-Full checkout UI rendered inside a single iframe. Includes card form, express payments (Apple Pay, PayPal), and 3DS handling.
+Full checkout UI rendered inside a single iframe. Includes card form, express payments (Apple Pay, Google Pay, PayPal), and 3DS handling.
 
 **React**
 
@@ -108,6 +108,92 @@ payment.mount('#payment-container');
 </html>
 ```
 
+### External express buttons (`expressButtons: false`)
+
+By default the iframe renders express buttons (Apple Pay / Google Pay /
+PayPal) inside the checkout form. Set `config.expressButtons: false` to keep
+the iframe card-form only and render the wallet buttons directly in your own
+page — full control over placement and layout, and wallet payment sheets open
+from the top-level page instead of inside an iframe.
+
+**React** — the hook mounts the buttons for you and merges wallet results
+into the same `onPayment` / `onEvent` callbacks as the card form:
+
+```tsx
+import { useFlintNPayment } from 'flintn-checkout/react';
+
+function Checkout() {
+  const {
+    containerRef,
+    applePayRef,
+    googlePayRef,
+    payPalRef,
+    expressAvailable,
+    paymentResult,
+  } = useFlintNPayment({
+    config: {
+      clientSessionId: 'your_client_session_id',
+      expressButtons: false,
+    },
+    // Single callback for wallets AND the card form
+    onPayment: (result) => console.log('Payment:', result),
+    // Single per-attempt stream for wallets AND the card form
+    onEvent: (event) => console.log('Event:', event),
+  });
+
+  return (
+    <div style={{ maxWidth: 440 }}>
+      {/* Your layout, your styling. Hide with CSS while unavailable —
+          do not conditionally unmount the refs. */}
+      <div style={{ display: expressAvailable ? 'block' : 'none' }}>
+        <div ref={applePayRef} />
+        <div ref={googlePayRef} />
+        <div ref={payPalRef} />
+        <hr />
+      </div>
+
+      {/* Card form iframe — no express buttons inside */}
+      <div ref={containerRef} style={{ width: '100%' }} />
+    </div>
+  );
+}
+```
+
+**Vanilla JavaScript** — pair `createFlintNPayment` with the standalone
+express module:
+
+```javascript
+import { createFlintNPayment, createFlintNExpressButtons } from 'flintn-checkout';
+
+const payment = createFlintNPayment({
+  config: { clientSessionId: 'your_client_session_id', expressButtons: false },
+  onPayment: (result) => console.log('Card payment:', result),
+});
+payment.mount('#payment-container');
+
+const express = createFlintNExpressButtons({
+  config: { clientSessionId: 'your_client_session_id' },
+  onPayment: (result) => console.log('Wallet payment:', result),
+  onCapability: (cap) => {
+    // Show/hide your express section based on device availability
+    document.getElementById('express-row').hidden =
+      !(cap.applePay || cap.googlePay || cap.paypal);
+  },
+});
+express.mountExpressButtons([
+  { method: 'APPLE_PAY', elementSelector: '#apple-pay' },
+  { method: 'GOOGLE_PAY', elementSelector: '#google-pay' },
+  { method: 'PAYPAL', elementSelector: '#paypal' },
+]);
+```
+
+Notes:
+
+- `formFields.formVariant` `LIST`/`RADIO` are ignored with
+  `expressButtons: false` — the express/card switch lives in your page now.
+- After a successful wallet payment, disable or hide the card form — the
+  session is completed and further card submits will fail.
+
 ## Events — terminal vs per-attempt
 
 The SDK fires two streams of events. Use the one that fits your use case:
@@ -246,6 +332,7 @@ Do **not** set a fixed `height` on the container — it will leave empty space b
 | `styles` | `FormStyles` | No | Custom styles (colors, border radius, text) for the checkout form |
 | `placeholders` | `FormPlaceholders` | No | Per-field placeholder text overrides (see `FormPlaceholders`) |
 | `successRedirectUrl` | `string` | No | Redirect URL after successful payment |
+| `expressButtons` | `boolean` | No | Default `true` — express buttons (Apple Pay / Google Pay / PayPal) render inside the iframe form. Set `false` to render the card form only and mount express buttons in your own page via `createFlintNExpressButtons`; `formFields.formVariant` `LIST`/`RADIO` are ignored in that case |
 
 ### React Hook Return Values
 
@@ -253,9 +340,13 @@ Do **not** set a fixed `height` on the container — it will leave empty space b
 |-------|------|-------------|
 | `containerRef` | `RefObject<HTMLDivElement>` | Ref to attach to container element |
 | `isReady` | `boolean` | Widget is loaded and ready |
-| `paymentResult` | `PaymentResult \| null` | Result after terminal `onPayment` event |
+| `paymentResult` | `PaymentResult \| null` | Result after terminal `onPayment` event (card or wallet) |
 | `events` | `CheckoutEvent[]` | Per-attempt event log (accumulated since mount) |
 | `error` | `PaymentError \| null` | SDK error if any |
+| `applePayRef` | `RefObject<HTMLDivElement>` | Apple Pay mount point — used with `expressButtons: false` |
+| `googlePayRef` | `RefObject<HTMLDivElement>` | Google Pay mount point — used with `expressButtons: false` |
+| `payPalRef` | `RefObject<HTMLDivElement>` | PayPal mount point — used with `expressButtons: false` |
+| `expressAvailable` | `boolean` | At least one wallet is available on this device/session (`expressButtons: false` only) |
 
 ---
 
@@ -480,7 +571,8 @@ Validation mirrors react-hook-form `mode: 'onSubmit'`:
 
 ### Postal code (BIN-driven)
 
-Some issuers require a postal code for online payments. Once the buyer has
+Some issuers require a postal code for online payments (currently US-issued
+cards — the requirement is resolved server-side by BIN). Once the buyer has
 typed enough digits, the card-number field checks the BIN against the payments
 API and reports whether a postal code is required — `postalCodeRequired`
 (React) / `onPostalCodeRequirement` (vanilla). Show your own postal code input
@@ -646,6 +738,8 @@ interface PaymentError {
 
 ```typescript
 interface SubmitOptions {
+  // Required by default — the API rejects card payments without it unless the
+  // merchant disabled the cardholder name field in the client session request.
   cardholderName?: string;
   email?: string;
   billingAddress?: {
@@ -914,7 +1008,10 @@ on `createField` (or the `fields` prop of `useFlintNFields`) instead.
 
 ## Form Variants
 
-The iframe checkout supports three layout variants via `formFields.formVariant`:
+The iframe checkout supports three layout variants via `formFields.formVariant`.
+Variants only apply when express buttons render inside the iframe — with
+`expressButtons: false` the variant is ignored and the iframe always shows the
+plain card form.
 
 - **DEFAULT** — Express payment methods shown above the card form with dividers.
 - **LIST** — Express payment methods shown first; users tap a "Credit or Debit Card" button to navigate to the card form, with a back arrow to return to the express view. Toggling emits `FORM_ENTERED` / `FORM_EXITED` UI events.

package/dist/index.d.mts

@@ -81,6 +81,14 @@ interface FlintNConfig {
     styles?: FormStyles;
     placeholders?: FormPlaceholders;
     successRedirectUrl?: string;
+    /**
+     * Whether the iframe renders express buttons (Apple Pay / Google Pay /
+     * PayPal) inside the checkout form. Default true. Set false to render the
+     * card form only and mount express buttons in your own page via
+     * `createFlintNExpressButtons` — note `formFields.formVariant` LIST/RADIO
+     * are ignored in that case.
+     */
+    expressButtons?: boolean;
 }
 declare const PaymentMethod: {
     readonly PAYMENT_CARD: "PAYMENT_CARD";

package/dist/index.d.ts

@@ -81,6 +81,14 @@ interface FlintNConfig {
     styles?: FormStyles;
     placeholders?: FormPlaceholders;
     successRedirectUrl?: string;
+    /**
+     * Whether the iframe renders express buttons (Apple Pay / Google Pay /
+     * PayPal) inside the checkout form. Default true. Set false to render the
+     * card form only and mount express buttons in your own page via
+     * `createFlintNExpressButtons` — note `formFields.formVariant` LIST/RADIO
+     * are ignored in that case.
+     */
+    expressButtons?: boolean;
 }
 declare const PaymentMethod: {
     readonly PAYMENT_CARD: "PAYMENT_CARD";

package/dist/index.js

@@ -590,14 +590,12 @@ var ExpressApi = class {
       } else if (res.status === AuthorizedStatus.THREE_DS_INITIATED && res.required_action?.type === "REDIRECT_TO_URL") {
         handlers.onThreeDs(res.required_action.redirect_url, res.id);
       } else {
-        const code = declineCodeOf(
-          res.status_reason?.decline_code,
-          res.status === AuthorizedStatus.DECLINED ? "PAYMENT_DECLINED" : "PAYMENT_FAILED"
-        );
+        const fallback = res.status === AuthorizedStatus.DECLINED ? "PAYMENT_DECLINED" : "PAYMENT_FAILED";
+        const code = declineCodeOf(res.status_reason?.decline_code, fallback);
         const isHard = res.status_reason?.decline_type === "HARD_DECLINE" || res.status_reason?.decline_type == null && res.session_retryable === false;
         handlers.onFailed(
           code,
-          res.status_reason?.message ?? code,
+          res.status_reason?.message ?? (fallback === "PAYMENT_DECLINED" ? "Payment declined." : "Payment failed."),
           res.id,
           res.status === AuthorizedStatus.DECLINED && !isHard ? PaymentAttemptResult.SOFT_DECLINE : PaymentAttemptResult.HARD_DECLINE
         );
@@ -1302,17 +1300,24 @@ function createFlintNExpressButtons(options) {
       if (status === "AUTHORIZED") succeed(threeDsMethod, paymentId);
       else {
         const code = declineCode ?? (status === "DECLINED" ? "PAYMENT_DECLINED" : "PAYMENT_FAILED");
-        fail(threeDsMethod, code, code, { paymentId });
+        const message = status === "DECLINED" ? "Payment declined." : "Payment failed.";
+        fail(threeDsMethod, code, message, { paymentId });
       }
     },
-    onClose: () => fail(threeDsMethod, "THREE_DS_CANCELLED", "THREE_DS_CANCELLED", {
-      event: PaymentAttemptResult.CANCELLED
-    }),
+    onClose: () => fail(
+      threeDsMethod,
+      "THREE_DS_CANCELLED",
+      "3DS verification was cancelled by the buyer.",
+      { event: PaymentAttemptResult.CANCELLED }
+    ),
     // Routed through fail() so analytics get a terminal attempt event too
     // (NETWORK_ERROR — a client-side technical failure, not a decline).
-    onPopupBlocked: () => fail(threeDsMethod, "THREE_DS_POPUP_BLOCKED", "THREE_DS_POPUP_BLOCKED", {
-      event: PaymentAttemptResult.NETWORK_ERROR
-    })
+    onPopupBlocked: () => fail(
+      threeDsMethod,
+      "THREE_DS_POPUP_BLOCKED",
+      "The 3DS verification window was blocked by the browser.",
+      { event: PaymentAttemptResult.NETWORK_ERROR }
+    )
   });
   const walletHandlers = (method) => (complete) => ({
     onAuthorized: (paymentId) => {

package/dist/index.mjs

@@ -542,14 +542,12 @@ var ExpressApi = class {
       } else if (res.status === AuthorizedStatus.THREE_DS_INITIATED && res.required_action?.type === "REDIRECT_TO_URL") {
         handlers.onThreeDs(res.required_action.redirect_url, res.id);
       } else {
-        const code = declineCodeOf(
-          res.status_reason?.decline_code,
-          res.status === AuthorizedStatus.DECLINED ? "PAYMENT_DECLINED" : "PAYMENT_FAILED"
-        );
+        const fallback = res.status === AuthorizedStatus.DECLINED ? "PAYMENT_DECLINED" : "PAYMENT_FAILED";
+        const code = declineCodeOf(res.status_reason?.decline_code, fallback);
         const isHard = res.status_reason?.decline_type === "HARD_DECLINE" || res.status_reason?.decline_type == null && res.session_retryable === false;
         handlers.onFailed(
           code,
-          res.status_reason?.message ?? code,
+          res.status_reason?.message ?? (fallback === "PAYMENT_DECLINED" ? "Payment declined." : "Payment failed."),
           res.id,
           res.status === AuthorizedStatus.DECLINED && !isHard ? PaymentAttemptResult.SOFT_DECLINE : PaymentAttemptResult.HARD_DECLINE
         );
@@ -1254,17 +1252,24 @@ function createFlintNExpressButtons(options) {
       if (status === "AUTHORIZED") succeed(threeDsMethod, paymentId);
       else {
         const code = declineCode ?? (status === "DECLINED" ? "PAYMENT_DECLINED" : "PAYMENT_FAILED");
-        fail(threeDsMethod, code, code, { paymentId });
+        const message = status === "DECLINED" ? "Payment declined." : "Payment failed.";
+        fail(threeDsMethod, code, message, { paymentId });
       }
     },
-    onClose: () => fail(threeDsMethod, "THREE_DS_CANCELLED", "THREE_DS_CANCELLED", {
-      event: PaymentAttemptResult.CANCELLED
-    }),
+    onClose: () => fail(
+      threeDsMethod,
+      "THREE_DS_CANCELLED",
+      "3DS verification was cancelled by the buyer.",
+      { event: PaymentAttemptResult.CANCELLED }
+    ),
     // Routed through fail() so analytics get a terminal attempt event too
     // (NETWORK_ERROR — a client-side technical failure, not a decline).
-    onPopupBlocked: () => fail(threeDsMethod, "THREE_DS_POPUP_BLOCKED", "THREE_DS_POPUP_BLOCKED", {
-      event: PaymentAttemptResult.NETWORK_ERROR
-    })
+    onPopupBlocked: () => fail(
+      threeDsMethod,
+      "THREE_DS_POPUP_BLOCKED",
+      "The 3DS verification window was blocked by the browser.",
+      { event: PaymentAttemptResult.NETWORK_ERROR }
+    )
   });
   const walletHandlers = (method) => (complete) => ({
     onAuthorized: (paymentId) => {

package/dist/react.d.mts

@@ -80,6 +80,14 @@ interface FlintNConfig {
     styles?: FormStyles;
     placeholders?: FormPlaceholders;
     successRedirectUrl?: string;
+    /**
+     * Whether the iframe renders express buttons (Apple Pay / Google Pay /
+     * PayPal) inside the checkout form. Default true. Set false to render the
+     * card form only and mount express buttons in your own page via
+     * `createFlintNExpressButtons` — note `formFields.formVariant` LIST/RADIO
+     * are ignored in that case.
+     */
+    expressButtons?: boolean;
 }
 declare const PaymentMethod: {
     readonly PAYMENT_CARD: "PAYMENT_CARD";
@@ -231,6 +239,18 @@ interface UseFlintNPaymentReturn {
     paymentResult: PaymentResult | null;
     events: Array<CheckoutEvent>;
     error: PaymentError | null;
+    /**
+     * Express-button mount points — used only with
+     * `config.expressButtons: false`: the iframe renders the card form alone
+     * and the hook mounts wallet buttons into these refs on the merchant page.
+     * Wallet results and attempt events arrive through the same
+     * `onPayment` / `onEvent` as the card form.
+     */
+    applePayRef: React.RefObject<HTMLDivElement | null>;
+    googlePayRef: React.RefObject<HTMLDivElement | null>;
+    payPalRef: React.RefObject<HTMLDivElement | null>;
+    /** True once at least one wallet is available on this device/session. */
+    expressAvailable: boolean;
 }
 declare function useFlintNPayment(options: UseFlintNPaymentOptions): UseFlintNPaymentReturn;
 

package/dist/react.d.ts

@@ -80,6 +80,14 @@ interface FlintNConfig {
     styles?: FormStyles;
     placeholders?: FormPlaceholders;
     successRedirectUrl?: string;
+    /**
+     * Whether the iframe renders express buttons (Apple Pay / Google Pay /
+     * PayPal) inside the checkout form. Default true. Set false to render the
+     * card form only and mount express buttons in your own page via
+     * `createFlintNExpressButtons` — note `formFields.formVariant` LIST/RADIO
+     * are ignored in that case.
+     */
+    expressButtons?: boolean;
 }
 declare const PaymentMethod: {
     readonly PAYMENT_CARD: "PAYMENT_CARD";
@@ -231,6 +239,18 @@ interface UseFlintNPaymentReturn {
     paymentResult: PaymentResult | null;
     events: Array<CheckoutEvent>;
     error: PaymentError | null;
+    /**
+     * Express-button mount points — used only with
+     * `config.expressButtons: false`: the iframe renders the card form alone
+     * and the hook mounts wallet buttons into these refs on the merchant page.
+     * Wallet results and attempt events arrive through the same
+     * `onPayment` / `onEvent` as the card form.
+     */
+    applePayRef: React.RefObject<HTMLDivElement | null>;
+    googlePayRef: React.RefObject<HTMLDivElement | null>;
+    payPalRef: React.RefObject<HTMLDivElement | null>;
+    /** True once at least one wallet is available on this device/session. */
+    expressAvailable: boolean;
 }
 declare function useFlintNPayment(options: UseFlintNPaymentOptions): UseFlintNPaymentReturn;