flintn-checkout 0.0.15 → 0.0.17

package/README.md

@@ -265,7 +265,12 @@ Individual PCI-compliant input fields rendered as separate iframes. You control
 
 Each field (card number, expiry, CVV) is a separate iframe. Raw card data never touches your page.
 
-> **Note:** Hosted Fields emits only the terminal `onPayment` event — there is no `onEvent` per-attempt stream. Use Iframe Checkout if you need granular attempt analytics.
+When a card payment requires 3DS, the SDK shows the bank's challenge in a
+**modal dialog on your page**. The buyer can dismiss it, which surfaces as 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.
 
 **React**
 
@@ -326,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>
           )}
@@ -374,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');
@@ -424,12 +433,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") |
 
 ### 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
@@ -439,6 +449,10 @@ Additional React-only options:
 | `cardNumberRef` | `RefObject<HTMLDivElement>` | Ref for card number container |
 | `expiryRef` | `RefObject<HTMLDivElement>` | Ref for expiry container |
 | `cvvRef` | `RefObject<HTMLDivElement>` | Ref for CVV container |
+| `applePayRef` | `RefObject<HTMLDivElement>` | Ref for the Apple Pay button container (attaching it enables the wallet) |
+| `googlePayRef` | `RefObject<HTMLDivElement>` | Ref for the Google Pay button container (attaching it enables the wallet) |
+| `payPalRef` | `RefObject<HTMLDivElement>` | Ref for the PayPal button container (attaching it enables the wallet) |
+| `expressAvailable` | `boolean` | True once wallet detection settles and at least one express button is renderable |
 | `isReady` | `boolean` | All fields loaded and ready |
 | `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) |
@@ -459,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
 
@@ -466,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)
 
@@ -479,6 +494,105 @@ Validation mirrors react-hook-form `mode: 'onSubmit'`:
 | `field.getState()` | Get current field state |
 | `field.getFieldType()` | Get the field type |
 
+### Express buttons (Apple Pay / Google Pay / PayPal)
+
+Hosted Fields can also render **fast checkout buttons** so buyers can pay with a
+wallet instead of typing card details. The buttons render **directly into your
+DOM** — one element per wallet, no iframe. Your page's own layout sizes and
+positions each button; wallet UI (the Apple Pay sheet or desktop QR modal, the
+Google Pay sheet, the PayPal popup) overlays your page natively. Only encrypted
+wallet tokens pass through the page; they are authorized against the
+session-scoped payments API, so no API key ever reaches the browser. Terminal
+results arrive through the **same `onPayment`** callback as the card `submit()`.
+
+**React**
+
+```tsx
+import { useFlintNFields } from 'flintn-checkout/react';
+
+function CheckoutForm() {
+  const {
+    cardNumberRef, expiryRef, cvvRef,
+    applePayRef, googlePayRef, payPalRef, // one container per wallet
+    expressAvailable,    // true once ≥1 wallet button is renderable
+    submit,
+  } = useFlintNFields({
+    config: { clientSessionId: 'your_client_session_id' },
+    onPayment: (result) => {
+      if (result.status === 'PAYMENT_SUCCESS') console.log('Paid:', result.data);
+    },
+    onEvent: (e) => console.log('express attempt:', e.event, e.method),
+  });
+
+  return (
+    <form onSubmit={(e) => { e.preventDefault(); submit(); }}>
+      {/* attach a ref to enable that wallet; unavailable wallets render
+          nothing — collapse empty containers via CSS if they carry spacing */}
+      <div ref={applePayRef} />
+      <div ref={googlePayRef} />
+      <div ref={payPalRef} />
+      {expressAvailable && <div className="divider">or pay by card</div>}
+
+      <div ref={cardNumberRef} style={{ height: 40 }} />
+      <div ref={expiryRef} style={{ height: 40 }} />
+      <div ref={cvvRef} style={{ height: 40 }} />
+      <button type="submit">Pay</button>
+    </form>
+  );
+}
+```
+
+**Vanilla JavaScript**
+
+```javascript
+import { createFlintNFields } from 'flintn-checkout';
+
+const fields = createFlintNFields({
+  config: { clientSessionId: 'your_client_session_id' },
+  onPayment: (result) => console.log('Payment result:', result),
+});
+
+const express = fields.createExpressButtons({
+  onCapability: (cap) => console.log('available wallets:', cap),
+  onEvent: (attempt) => console.log('express attempt:', attempt),
+});
+
+await express.mountExpressButtons([
+  { method: 'APPLE_PAY', elementSelector: '#apple-pay' },
+  { method: 'GOOGLE_PAY', elementSelector: '#google-pay' },
+  { method: 'PAYPAL', elementSelector: '#paypal' },
+]);
+
+// unmount a single wallet, or all of them
+express.unmountExpressButton('APPLE_PAY');
+express.unmountAllExpressButtons();
+
+// card fields as usual
+fields.createField('card-number').mount('#card-number');
+fields.createField('expiry').mount('#expiry');
+fields.createField('cvv').mount('#cvv');
+```
+
+Notes:
+
+- **No `submit()` for express.** Wallet buttons self-trigger (the buyer taps Apple
+  Pay and the sheet opens). Success/error come through `onPayment`; per-attempt
+  analytics through the top-level `onEvent` (React) /
+  `createExpressButtons({ onEvent })` (vanilla).
+- **Availability.** Buttons for methods that are unavailable on this
+  device/session are silently skipped at mount — their containers just stay
+  empty. `expressAvailable` (React) / the `onCapability` callback (vanilla)
+  gate your "or pay by card" divider.
+- **Which wallets appear** is driven entirely by the merchant session config
+  (`payment_methods`) intersected with device support — there is no client-side
+  allow-list.
+- **3DS** for wallet payments is handled automatically via a popup (make sure the
+  buyer's click isn't intercepted by a popup blocker).
+- **Apple Pay domain registration.** Your live domain must be registered with
+  Apple (handled during merchant onboarding) — merchant validation runs against
+  the domain the buttons render on. On non-Safari browsers Apple's JS SDK shows
+  its QR-code modal over your page. Google Pay and PayPal have no such limits.
+
 ---
 
 ## Shared Types
@@ -503,6 +617,39 @@ interface PaymentError {
 }
 ```
 
+### Error handling
+
+Errors surface through three separate channels — don't conflate them:
+
+| Channel | What lands there | Show as |
+|---------|------------------|---------|
+| `error` / `onError` | Infrastructure: SDK failed to initialize, a container is missing, the session config couldn't load | Page-level banner ("checkout unavailable / session expired") |
+| `paymentResult` / `onPayment` with `PAYMENT_ERROR` | A payment attempt failed (card or wallet) | Inline payment error, offer retry |
+| `fieldErrors` | Per-field validation (populated after the first `submit()`/`validate()`) | Messages next to each field |
+
+Common `code` values:
+
+| Code | Channel | Meaning |
+|------|---------|---------|
+| `INIT_ERROR` | error | SDK could not initialize (missing `clientSessionId`, bad `origin`) |
+| `MOUNT_ERROR` | error | A field/button container was not found or failed to mount |
+| `SESSION_EXPIRED` (and other API codes) | error or payment | Passed through from the payments API as-is |
+| `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) |
+| `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 |
+| `PAYPAL_MISSING_PAYMENT_ID` | payment | PayPal approved but no payment id was captured (anomaly) |
+| `THREE_DS_FAILED` / `THREE_DS_CANCELLED` | payment | Challenge declined / dismissed by the buyer |
+| `THREE_DS_POPUP_BLOCKED` | payment | Express buttons only — the wallet 3DS window was blocked by the browser |
+
+Worth handling specifically: `SESSION_EXPIRED` (create a fresh session and remount),
+`THREE_DS_POPUP_BLOCKED` (ask the buyer to allow popups), `VALIDATION_ERROR`
+(highlight fields from `fieldErrors`). Everything else is safely generic.
+
 ### CheckoutEvent
 
 ```typescript
@@ -683,8 +830,8 @@ on `createField` (or the `fields` prop of `useFlintNFields`) instead.
 | `loaderColor` | ✅ | — | Loading spinner color |
 | `backgroundColor` | ✅ | — | Form background color |
 | `lightLogos` | ✅ | — | Use light logo variants in the safe-checkout row (for dark backgrounds) |
-| `expressButtonsSpacing` | ✅ | — | Spacing between express payment buttons |
-| `expressButtonsBorderRadius` | ✅ | — | Corner radius for express buttons — Apple Pay, Google Pay, PayPal, and the "Credit or debit card" button in the LIST variant (e.g. `8px`) |
+| `expressButtonsSpacing` | ✅ | — | Spacing between express payment buttons. Not applicable to Hosted Fields — the buttons render into your own containers, so spacing is your page's layout |
+| `expressButtonsBorderRadius` | ✅ | ✅ | Corner radius for express buttons — Apple Pay, Google Pay, PayPal, and the "Credit or debit card" button in the LIST variant (e.g. `8px`). In Hosted Fields it applies to all wallet buttons at once |
 | `inputBackgroundColor` | ✅ | ✅ | Input field background color |
 | `inputBorderRadius` | ✅ | ✅ | Input field border radius |
 | `inputBorderColor` | ✅ | ✅ | Default input border color |
@@ -754,6 +901,7 @@ Every cancellation still emits a `CANCELLED` `onEvent` regardless of variant, so
 
 ### Hosted Fields
 - Credit/Debit Cards (Visa, Mastercard, Amex, Discover)
+- Apple Pay, Google Pay, PayPal (via the express buttons — see "Express buttons" above)
 
 ## Debug Mode
 

package/dist/index.d.mts

@@ -171,6 +171,8 @@ declare const FieldEventType: {
     readonly FIELD_VALIDATION: "FIELD_VALIDATION";
     readonly FIELD_SUBMIT_RESULT: "FIELD_SUBMIT_RESULT";
     readonly FIELD_HEIGHT: "FIELD_HEIGHT";
+    readonly FIELD_THREE_DS_REQUIRED: "FIELD_THREE_DS_REQUIRED";
+    readonly FIELD_THREE_DS_RESULT: "FIELD_THREE_DS_RESULT";
 };
 type TFieldEventType = (typeof FieldEventType)[keyof typeof FieldEventType];
 interface FieldOptions {
@@ -200,8 +202,31 @@ interface FieldsValidationResult {
     isValid: boolean;
     errors: Partial<Record<TFieldType, string | null>>;
 }
+interface SubmitBillingAddress {
+    addressLine1?: string;
+    addressLine2?: string;
+    city?: string;
+    state?: string;
+    postalCode?: string;
+    country?: string;
+}
 interface SubmitOptions {
     cardholderName?: string;
+    email?: string;
+    billingAddress?: SubmitBillingAddress;
+}
+interface ExpressCapability {
+    applePay: boolean;
+    googlePay: boolean;
+    paypal: boolean;
+}
+interface ExpressAttempt {
+    event: TPaymentAttemptResult;
+    method: TPaymentMethod;
+    paymentId?: string;
+    code?: string;
+    message?: string;
+    timestamp: number;
 }
 interface FlintNFieldsConfig {
     clientSessionId: string;
@@ -247,9 +272,144 @@ interface FlintNField {
 }
 declare function createFlintNField(fieldType: TFieldType, origin: string, clientSessionId: string, options: FieldOptions, callbacks: FlintNFieldInternalCallbacks, debug?: boolean, formStyles?: FormStyles): FlintNField;
 
+declare const EXPRESS_BUTTON_HEIGHT = 40;
+declare const ExpressMethod: {
+    readonly APPLE_PAY: "APPLE_PAY";
+    readonly GOOGLE_PAY: "GOOGLE_PAY";
+    readonly PAYPAL: "PAYPAL";
+};
+type TExpressMethod = (typeof ExpressMethod)[keyof typeof ExpressMethod];
+/** One entry per wallet button: which method goes into which element. */
+interface ExpressButtonMount {
+    method: TExpressMethod;
+    /** CSS selector or the element itself. The button fills the element. */
+    elementSelector: string | HTMLElement;
+}
+interface FlintNExpressButtonsOptions {
+    config: {
+        clientSessionId: string;
+    };
+    origin?: string;
+    apiUrl?: string;
+    buttonBorderRadius?: number;
+    onPayment?: (result: PaymentResult) => void;
+    onEvent?: (event: ExpressAttempt) => void;
+    onCapability?: (capability: ExpressCapability) => void;
+    onError?: (error: PaymentError) => void;
+    debug?: boolean;
+}
+interface FlintNExpressButtons {
+    mountExpressButtons(buttons: ExpressButtonMount[]): Promise<void>;
+    unmountExpressButton(method: TExpressMethod): void;
+    unmountAllExpressButtons(): void;
+}
+interface ApplePayConfig {
+    country_code: string;
+    supported_networks: string[];
+    merchant_capabilities: string[];
+    display_name: string;
+    merchant_identifier?: string;
+}
+interface GooglePayConfig {
+    environment: string;
+    gateway: string;
+    gateway_merchant_id: string;
+    merchant_id?: string;
+    merchant_name?: string;
+    country_code?: string;
+}
+interface PayPalConfig {
+    client_id: string;
+    merchant_id?: string;
+}
+interface SessionConfig {
+    session: {
+        amount: number;
+        currency_code: string;
+    };
+    payment_methods: string[];
+    apple_pay_config?: ApplePayConfig;
+    google_pay_config?: GooglePayConfig;
+    paypal_config?: PayPalConfig;
+}
+declare const AuthorizedStatus: {
+    readonly PENDING: "PENDING";
+    readonly AUTHORIZED: "AUTHORIZED";
+    readonly FAILED: "FAILED";
+    readonly DECLINED: "DECLINED";
+    readonly THREE_DS_INITIATED: "THREE_DS_INITIATED";
+};
+type TAuthorizedStatus = (typeof AuthorizedStatus)[keyof typeof AuthorizedStatus];
+interface AuthorizeResponse {
+    id: string;
+    status: TAuthorizedStatus;
+    required_action?: {
+        type: string;
+        redirect_url: string;
+    };
+    status_reason?: {
+        decline_reason?: string;
+        message?: string;
+    };
+}
+interface ApplePayToken {
+    payment_data: {
+        data: string;
+        header: {
+            ephemeral_public_key: string;
+            public_key_hash: string;
+            transaction_id: string;
+        };
+        signature: string;
+        version: string;
+    };
+    payment_method: {
+        display_name: string;
+        network: string;
+        type: string;
+    };
+    transaction_identifier: string;
+}
+interface GooglePayToken {
+    token: string;
+}
+/** Terminal-ish callbacks the wallet flows report into (mirrors the iframe's ExpressAuthorizeHandlers). */
+interface WalletAuthorizeHandlers {
+    onAuthorized: (paymentId: string) => void;
+    onThreeDs: (redirectUrl: string, paymentId: string) => void;
+    onFailed: (code: string, message: string, paymentId?: string) => void;
+}
+
+/**
+ * Express fast-checkout buttons (Apple Pay / Google Pay / PayPal) rendered
+ * DIRECTLY into the merchant's DOM — one element per wallet, Yuno-style.
+ * There is no iframe: wallet SDKs load on the merchant page, wallet UI
+ * (Apple Pay QR modal, payment sheets) overlays the page natively, and the
+ * page's own layout sizes the buttons. Only encrypted wallet tokens pass
+ * through the page; they are authorized against the session-scoped payments
+ * API (no API key in the browser).
+ */
+declare function createFlintNExpressButtons(options: FlintNExpressButtonsOptions): FlintNExpressButtons;
+
+declare const deriveApiUrl: (payOrigin: string) => string;
+
+/**
+ * Per-instance express options; session/origin/onPayment come from the fields
+ * instance, and button styling comes from `config.styles`
+ * (expressButtonsBorderRadius).
+ */
+type ExpressButtonsOptions = Pick<FlintNExpressButtonsOptions, 'apiUrl' | 'onEvent' | 'onCapability'>;
 interface FlintNFields {
     createField(fieldType: TFieldType, options?: FieldOptions): FlintNField;
     getField(fieldType: TFieldType): FlintNField | undefined;
+    /**
+     * Create the express fast-checkout buttons (Apple Pay / Google Pay /
+     * PayPal), rendered directly into merchant-owned elements (one per wallet —
+     * see `mountExpressButtons`). Terminal results flow through the same
+     * `onPayment` callback as the card `submit()`; per-attempt analytics and
+     * capability flags are delivered via the options passed here.
+     */
+    createExpressButtons(options?: ExpressButtonsOptions): FlintNExpressButtons;
     validate(): Promise<FieldsValidationResult>;
     submit(options?: SubmitOptions, skipValidation?: boolean): Promise<PaymentResult>;
     unmount(): void;
@@ -265,4 +425,4 @@ declare const validateConfig: (config: {
 }) => void;
 declare const sanitizeToken: (token: string) => string;
 
-export { type CheckoutEvent, CheckoutFormVariant, CheckoutView, EventType, type FieldChangeEvent, FieldEventType, type FieldOptions, type FieldState, FieldType, type FieldValidationResult, type FieldsValidationResult, type FlintNConfig, type FlintNField, type FlintNFieldInternalCallbacks, type FlintNFields, type FlintNFieldsConfig, type FlintNFieldsOptions, type FlintNPayment, type FlintNPaymentOptions, type FormFields, type FormPlaceholders, type FormStyles, type PaymentAttempt, PaymentAttemptResult, type PaymentError, PaymentMethod, type PaymentResult, type PaymentUI, PaymentUIEvent, type SubmitOptions, type TCheckoutFormVariant, type TCheckoutView, type TEventType, type TFieldEventType, type TFieldType, type TPaymentAttemptResult, type TPaymentMethod, type TPaymentUIEvent, buildIframeSrc, createFlintNField, createFlintNFields, createFlintNPayment, createIframeElement, isAttemptEvent, isUIEvent, parseOrigin, sanitizeToken, validateConfig };
+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 };

package/dist/index.d.ts

@@ -171,6 +171,8 @@ declare const FieldEventType: {
     readonly FIELD_VALIDATION: "FIELD_VALIDATION";
     readonly FIELD_SUBMIT_RESULT: "FIELD_SUBMIT_RESULT";
     readonly FIELD_HEIGHT: "FIELD_HEIGHT";
+    readonly FIELD_THREE_DS_REQUIRED: "FIELD_THREE_DS_REQUIRED";
+    readonly FIELD_THREE_DS_RESULT: "FIELD_THREE_DS_RESULT";
 };
 type TFieldEventType = (typeof FieldEventType)[keyof typeof FieldEventType];
 interface FieldOptions {
@@ -200,8 +202,31 @@ interface FieldsValidationResult {
     isValid: boolean;
     errors: Partial<Record<TFieldType, string | null>>;
 }
+interface SubmitBillingAddress {
+    addressLine1?: string;
+    addressLine2?: string;
+    city?: string;
+    state?: string;
+    postalCode?: string;
+    country?: string;
+}
 interface SubmitOptions {
     cardholderName?: string;
+    email?: string;
+    billingAddress?: SubmitBillingAddress;
+}
+interface ExpressCapability {
+    applePay: boolean;
+    googlePay: boolean;
+    paypal: boolean;
+}
+interface ExpressAttempt {
+    event: TPaymentAttemptResult;
+    method: TPaymentMethod;
+    paymentId?: string;
+    code?: string;
+    message?: string;
+    timestamp: number;
 }
 interface FlintNFieldsConfig {
     clientSessionId: string;
@@ -247,9 +272,144 @@ interface FlintNField {
 }
 declare function createFlintNField(fieldType: TFieldType, origin: string, clientSessionId: string, options: FieldOptions, callbacks: FlintNFieldInternalCallbacks, debug?: boolean, formStyles?: FormStyles): FlintNField;
 
+declare const EXPRESS_BUTTON_HEIGHT = 40;
+declare const ExpressMethod: {
+    readonly APPLE_PAY: "APPLE_PAY";
+    readonly GOOGLE_PAY: "GOOGLE_PAY";
+    readonly PAYPAL: "PAYPAL";
+};
+type TExpressMethod = (typeof ExpressMethod)[keyof typeof ExpressMethod];
+/** One entry per wallet button: which method goes into which element. */
+interface ExpressButtonMount {
+    method: TExpressMethod;
+    /** CSS selector or the element itself. The button fills the element. */
+    elementSelector: string | HTMLElement;
+}
+interface FlintNExpressButtonsOptions {
+    config: {
+        clientSessionId: string;
+    };
+    origin?: string;
+    apiUrl?: string;
+    buttonBorderRadius?: number;
+    onPayment?: (result: PaymentResult) => void;
+    onEvent?: (event: ExpressAttempt) => void;
+    onCapability?: (capability: ExpressCapability) => void;
+    onError?: (error: PaymentError) => void;
+    debug?: boolean;
+}
+interface FlintNExpressButtons {
+    mountExpressButtons(buttons: ExpressButtonMount[]): Promise<void>;
+    unmountExpressButton(method: TExpressMethod): void;
+    unmountAllExpressButtons(): void;
+}
+interface ApplePayConfig {
+    country_code: string;
+    supported_networks: string[];
+    merchant_capabilities: string[];
+    display_name: string;
+    merchant_identifier?: string;
+}
+interface GooglePayConfig {
+    environment: string;
+    gateway: string;
+    gateway_merchant_id: string;
+    merchant_id?: string;
+    merchant_name?: string;
+    country_code?: string;
+}
+interface PayPalConfig {
+    client_id: string;
+    merchant_id?: string;
+}
+interface SessionConfig {
+    session: {
+        amount: number;
+        currency_code: string;
+    };
+    payment_methods: string[];
+    apple_pay_config?: ApplePayConfig;
+    google_pay_config?: GooglePayConfig;
+    paypal_config?: PayPalConfig;
+}
+declare const AuthorizedStatus: {
+    readonly PENDING: "PENDING";
+    readonly AUTHORIZED: "AUTHORIZED";
+    readonly FAILED: "FAILED";
+    readonly DECLINED: "DECLINED";
+    readonly THREE_DS_INITIATED: "THREE_DS_INITIATED";
+};
+type TAuthorizedStatus = (typeof AuthorizedStatus)[keyof typeof AuthorizedStatus];
+interface AuthorizeResponse {
+    id: string;
+    status: TAuthorizedStatus;
+    required_action?: {
+        type: string;
+        redirect_url: string;
+    };
+    status_reason?: {
+        decline_reason?: string;
+        message?: string;
+    };
+}
+interface ApplePayToken {
+    payment_data: {
+        data: string;
+        header: {
+            ephemeral_public_key: string;
+            public_key_hash: string;
+            transaction_id: string;
+        };
+        signature: string;
+        version: string;
+    };
+    payment_method: {
+        display_name: string;
+        network: string;
+        type: string;
+    };
+    transaction_identifier: string;
+}
+interface GooglePayToken {
+    token: string;
+}
+/** Terminal-ish callbacks the wallet flows report into (mirrors the iframe's ExpressAuthorizeHandlers). */
+interface WalletAuthorizeHandlers {
+    onAuthorized: (paymentId: string) => void;
+    onThreeDs: (redirectUrl: string, paymentId: string) => void;
+    onFailed: (code: string, message: string, paymentId?: string) => void;
+}
+
+/**
+ * Express fast-checkout buttons (Apple Pay / Google Pay / PayPal) rendered
+ * DIRECTLY into the merchant's DOM — one element per wallet, Yuno-style.
+ * There is no iframe: wallet SDKs load on the merchant page, wallet UI
+ * (Apple Pay QR modal, payment sheets) overlays the page natively, and the
+ * page's own layout sizes the buttons. Only encrypted wallet tokens pass
+ * through the page; they are authorized against the session-scoped payments
+ * API (no API key in the browser).
+ */
+declare function createFlintNExpressButtons(options: FlintNExpressButtonsOptions): FlintNExpressButtons;
+
+declare const deriveApiUrl: (payOrigin: string) => string;
+
+/**
+ * Per-instance express options; session/origin/onPayment come from the fields
+ * instance, and button styling comes from `config.styles`
+ * (expressButtonsBorderRadius).
+ */
+type ExpressButtonsOptions = Pick<FlintNExpressButtonsOptions, 'apiUrl' | 'onEvent' | 'onCapability'>;
 interface FlintNFields {
     createField(fieldType: TFieldType, options?: FieldOptions): FlintNField;
     getField(fieldType: TFieldType): FlintNField | undefined;
+    /**
+     * Create the express fast-checkout buttons (Apple Pay / Google Pay /
+     * PayPal), rendered directly into merchant-owned elements (one per wallet —
+     * see `mountExpressButtons`). Terminal results flow through the same
+     * `onPayment` callback as the card `submit()`; per-attempt analytics and
+     * capability flags are delivered via the options passed here.
+     */
+    createExpressButtons(options?: ExpressButtonsOptions): FlintNExpressButtons;
     validate(): Promise<FieldsValidationResult>;
     submit(options?: SubmitOptions, skipValidation?: boolean): Promise<PaymentResult>;
     unmount(): void;
@@ -265,4 +425,4 @@ declare const validateConfig: (config: {
 }) => void;
 declare const sanitizeToken: (token: string) => string;
 
-export { type CheckoutEvent, CheckoutFormVariant, CheckoutView, EventType, type FieldChangeEvent, FieldEventType, type FieldOptions, type FieldState, FieldType, type FieldValidationResult, type FieldsValidationResult, type FlintNConfig, type FlintNField, type FlintNFieldInternalCallbacks, type FlintNFields, type FlintNFieldsConfig, type FlintNFieldsOptions, type FlintNPayment, type FlintNPaymentOptions, type FormFields, type FormPlaceholders, type FormStyles, type PaymentAttempt, PaymentAttemptResult, type PaymentError, PaymentMethod, type PaymentResult, type PaymentUI, PaymentUIEvent, type SubmitOptions, type TCheckoutFormVariant, type TCheckoutView, type TEventType, type TFieldEventType, type TFieldType, type TPaymentAttemptResult, type TPaymentMethod, type TPaymentUIEvent, buildIframeSrc, createFlintNField, createFlintNFields, createFlintNPayment, createIframeElement, isAttemptEvent, isUIEvent, parseOrigin, sanitizeToken, validateConfig };
+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 };