@zippypay/checkout 1.0.0 → 1.1.10

package/dist/index.d.cts

@@ -9,12 +9,39 @@ declare function parseZippyEnvironment(value: string): ZippyEnvironment;
 type PaymentSessionStatus = 'CREATED' | 'AWAITING_PAYMENT' | 'COMPLETED' | 'EXPIRED' | 'CANCELLED' | 'FAILED';
 type PaymentSessionPhase = 'IDLE' | 'PAYING';
 /** Server checkout method — locks after checkout start. */
-type ApiCheckoutMethod = 'QR' | 'MANUAL';
+type ApiCheckoutMethod = 'QR' | 'MANUAL' | 'MOBILE_APP';
+/** SDK init — omit to allow both QR and Manual. */
+type CheckoutPolicy = 'QR' | 'MANUAL';
+/** SDK init — phone-only app handoff preference. */
+type MobileAppPolicy = 'off' | 'option' | 'enforce';
+/** Explicit checkout restriction returned by the API. */
+type ApiCheckoutPolicy = 'QR' | 'MANUAL';
+/** Bound checkout policy — `null` means full chooser (QR + manual). */
+type BoundCheckoutPolicy = ApiCheckoutPolicy | null;
+/** Bound mobile app policy returned by the API. */
+type ApiMobileAppPolicy = 'OFF' | 'OPTION' | 'ENFORCE';
+type BindCheckoutPolicyRequest = {
+    checkoutPolicy?: ApiCheckoutPolicy;
+    mobileAppPolicy?: ApiMobileAppPolicy;
+};
+type CheckoutSurface = 'phone' | 'desktop';
+type StartCheckoutRequest = {
+    method: ApiCheckoutMethod;
+    surface: CheckoutSurface;
+};
+type ZippyMobileAppConfig = {
+    policy?: MobileAppPolicy;
+};
 type PaymentSessionPayer = {
     paymentId: string;
     displayName: string;
     profileImage: string | null;
 };
+/** Payer preview returned from verify — same fields as session payer. */
+type PayerPreview = PaymentSessionPayer;
+type VerifyPayerResponse = {
+    items: PayerPreview[];
+};
 type PaymentSession = {
     sessionId: string;
     amount: string;
@@ -32,12 +59,15 @@ type PaymentSession = {
     absoluteExpiresAt: string;
     phase: PaymentSessionPhase;
     checkoutMethod: ApiCheckoutMethod | null;
+    /** Set after bind-policy — `null` = full chooser when `mobileAppPolicy` is set. */
+    checkoutPolicy: BoundCheckoutPolicy;
+    /** Set after bind-policy succeeds; null until then. */
+    mobileAppPolicy: ApiMobileAppPolicy | null;
     paymentStartAt: string | null;
     /** Pay window countdown — only meaningful when phase is PAYING. */
     paymentExpiryAt: string | null;
     createdAt: string;
 };
-type VerifyPayerResponse = PaymentSessionPayer;
 type ProblemJson = {
     type?: string;
     title?: string;
@@ -71,6 +101,10 @@ type ZippyPayConfig = {
     mode?: EmbedMode;
     container?: HTMLElement | string;
     theme?: ZippyTheme;
+    /** When omitted, customer can choose QR or Manual. */
+    checkoutPolicy?: CheckoutPolicy;
+    /** Phone-only app handoff. Ignored on non-phone devices. */
+    mobileApp?: ZippyMobileAppConfig;
     locale?: 'en';
     redirectOnComplete?: boolean;
     redirectOnFailure?: boolean;
@@ -83,8 +117,8 @@ type ZippyPayConfig = {
     onError?: (error: ZippyPayError) => void;
     onClose?: () => void;
 };
-type CheckoutMethod = 'qr' | 'manual';
-type CheckoutPhase = 'loading' | 'choose-method' | 'qr-active' | 'manual-entry' | 'manual-confirm' | 'awaiting' | 'success' | 'expired' | 'cancelled' | 'declined' | 'failed' | 'error' | 'invalid-session';
+type CheckoutMethod = 'qr' | 'manual' | 'mobileApp';
+type CheckoutPhase = 'loading' | 'choose-method' | 'qr-active' | 'mobile-app-active' | 'manual-entry' | 'manual-picker' | 'manual-confirm' | 'awaiting' | 'success' | 'expired' | 'cancelled' | 'declined' | 'failed' | 'error' | 'invalid-session';
 declare const TERMINAL_STATUSES: readonly PaymentSessionStatus[];
 declare const POLLABLE_STATUSES: readonly PaymentSessionStatus[];
 declare class ZippyPayError extends Error {
@@ -111,11 +145,13 @@ declare class PaymentSessionClient {
     private readonly clientToken;
     constructor(config: ApiClientConfig);
     getSession(): Promise<PaymentSession>;
-    verifyPayer(paymentId: string): Promise<VerifyPayerResponse>;
+    bindCheckoutPolicy(body: BindCheckoutPolicyRequest): Promise<PaymentSession>;
+    verifyPayer(query: string): Promise<VerifyPayerResponse>;
     attachPayer(paymentId: string): Promise<PaymentSession>;
-    startCheckout(method: ApiCheckoutMethod): Promise<PaymentSession>;
-    startQrCheckout(): Promise<PaymentSession>;
-    startManualCheckout(): Promise<PaymentSession>;
+    startCheckout(method: StartCheckoutRequest['method'], surface: CheckoutSurface): Promise<PaymentSession>;
+    startQrCheckout(surface: CheckoutSurface): Promise<PaymentSession>;
+    startMobileAppCheckout(surface: CheckoutSurface): Promise<PaymentSession>;
+    startManualCheckout(surface: CheckoutSurface): Promise<PaymentSession>;
     private sessionPath;
     private headers;
     private request;
@@ -166,6 +202,8 @@ declare class CheckoutController implements ZippyPayCheckoutInstance {
     private session;
     private paymentId;
     private verifiedPayer;
+    private verifyMatches;
+    private lastVerifiedQuery;
     private committedMethod;
     private phase;
     private errorMessage;
@@ -174,6 +212,14 @@ declare class CheckoutController implements ZippyPayCheckoutInstance {
     private modalOpen;
     private exitMode;
     private terminalFailureReason;
+    private uiOptions;
+    private appHandoffStatus;
+    private clearAppHandoffWatch;
+    private methodSwitchInProgress;
+    private entryRoutingDone;
+    private payWindowExpiryTimer;
+    private unsubscribeSurface;
+    private static readonly PAY_WINDOW_PHASES;
     constructor(config: ZippyPayConfig);
     open(): void;
     close(): void;
@@ -181,7 +227,13 @@ declare class CheckoutController implements ZippyPayCheckoutInstance {
     private snapshotUiState;
     private syncUi;
     private bootstrap;
+    private bindPolicy;
+    private applyBoundUiOptions;
+    private handleSurfaceChange;
     private applySession;
+    private schedulePayWindowExpiryWatch;
+    private clearPayWindowExpiryWatch;
+    private handlePayWindowExpired;
     private resolveActivePhase;
     private handleSessionUpdate;
     private handleFailure;
@@ -191,8 +243,21 @@ declare class CheckoutController implements ZippyPayCheckoutInstance {
     private failurePhaseFromReason;
     private teardownView;
     private handleBootstrapError;
+    private handlePollError;
     private handleError;
+    private routeIdleEntry;
+    private openMobileApp;
+    private beginMobileAppHandoff;
+    private installZippy;
+    private startMobileAppFlow;
+    private canStartAppClaim;
     private chooseMethod;
+    private chooseFallbackMethod;
+    private backToChooseMethod;
+    private backToManualEntry;
+    private backToMobileAppFallback;
+    private isMobileAppManualFallbackActive;
+    private selectPayer;
     private verify;
     private attach;
     private handleFlowError;
@@ -227,11 +292,74 @@ declare global {
 
 /** Personal Zippy handles: 3–20 chars, optional single dot, no leading/trailing dot. */
 declare const PAYMENT_ID_PATTERN: RegExp;
+declare const E164_PHONE_PATTERN: RegExp;
+declare const EMAIL_PATTERN: RegExp;
 declare function normalizePaymentId(value: string): string;
+/** Normalize a payer verify query before sending to the API. */
+declare function normalizePayerQuery(value: string): string;
 declare function isValidPaymentId(value: string): boolean;
+/** Client-side pre-validation for payer verify `query` (server is authoritative). */
+declare function isValidPayerQuery(value: string): boolean;
 declare function paymentIdValidationMessage(): string;
+declare function payerQueryValidationMessage(): string;
 declare function formatAmount(amount: string, currency: string): string;
 
+type MobileStorePlatform = 'ios' | 'android';
+/** True when checkout runs on a phone-sized touch device. */
+declare function isPhoneDevice(): boolean;
+/** True when the browser reports an Android user agent. */
+declare function isAndroidDevice(): boolean;
+declare function detectCheckoutSurface(): CheckoutSurface;
+declare function subscribeCheckoutSurface(onChange: (surface: CheckoutSurface) => void): () => void;
+
+/** Fixed App Store / Google Play URLs for Zippy Pay (managed server-side; not merchant-configurable). */
+type AppStoreLinks = {
+    ios: string;
+    android: string;
+};
+declare const ANDROID_APP_PACKAGE = "com.zippy.pay";
+/** HTTPS store URLs — used for QR codes and desktop fallback links. */
+declare const APP_STORE_LINKS: AppStoreLinks;
+/** Opens the native App Store app on iOS (no specific listing until app id is available). */
+declare const IOS_APP_STORE_NATIVE_URL = "itms-apps://apps.apple.com/";
+/** Opens the native Play Store app on Android. */
+declare const ANDROID_PLAY_STORE_NATIVE_URL = "market://details?id=com.zippy.pay";
+declare function resolveAppStoreUrl(platform: MobileStorePlatform): string;
+/**
+ * URL used when the customer taps Install Zippy.
+ * iOS and Android both use native store schemes from a user gesture.
+ */
+declare function resolveAppStoreOpenUrl(platform: MobileStorePlatform): string;
+
+type EntryRoutingAction = 'chooser' | 'auto-qr' | 'auto-manual' | 'enforce-mobile-app';
+type MethodAvailability = {
+    qr: boolean;
+    manual: boolean;
+    mobileApp: boolean;
+};
+type ResolvedCheckoutUiOptions = {
+    checkoutPolicy: BoundCheckoutPolicy;
+    mobileAppPolicy: ApiMobileAppPolicy;
+    surface: CheckoutSurface;
+    methodAvailability: MethodAvailability;
+    allowManualBack: boolean;
+};
+type AppClaimCheckoutMethod = Extract<ApiCheckoutMethod, 'QR' | 'MOBILE_APP'>;
+declare function isCheckoutPolicyBound(session: PaymentSession): boolean;
+declare function isFullChooserPolicy(checkoutPolicy: BoundCheckoutPolicy): boolean;
+declare function resolveMobileAppPolicy(mobileApp?: ZippyMobileAppConfig): ApiMobileAppPolicy;
+declare function buildBindPolicyRequest(config: {
+    checkoutPolicy?: CheckoutPolicy;
+    mobileApp?: ZippyMobileAppConfig;
+}): BindCheckoutPolicyRequest;
+declare function resolveMethodAvailability(checkoutPolicy: BoundCheckoutPolicy, mobileAppPolicy: ApiMobileAppPolicy, surface: CheckoutSurface): MethodAvailability;
+declare function resolveEntryRouting(checkoutPolicy: BoundCheckoutPolicy, mobileAppPolicy: ApiMobileAppPolicy, surface: CheckoutSurface): EntryRoutingAction;
+declare function isCheckoutStartAllowed(checkoutPolicy: BoundCheckoutPolicy, mobileAppPolicy: ApiMobileAppPolicy, surface: CheckoutSurface, method: AppClaimCheckoutMethod): boolean;
+declare function resolveAutoStartMethod(checkoutPolicy: BoundCheckoutPolicy, mobileAppPolicy: ApiMobileAppPolicy, surface: CheckoutSurface): AppClaimCheckoutMethod | null;
+declare function resolveCheckoutUiOptionsFromBound(checkoutPolicy: BoundCheckoutPolicy, mobileAppPolicy: ApiMobileAppPolicy, surface?: CheckoutSurface): ResolvedCheckoutUiOptions;
+declare function resolveCheckoutUiOptionsFromSession(session: PaymentSession, surface?: CheckoutSurface): ResolvedCheckoutUiOptions;
+declare function resolveCheckoutUiOptions(checkoutPolicy?: CheckoutPolicy, mobileApp?: ZippyMobileAppConfig, surface?: CheckoutSurface): ResolvedCheckoutUiOptions;
+
 /** Deep link scanned by the Zippy app — sessionId only, never clientToken. */
 declare function buildPaymentQrPayload(sessionId: string): string;
 type QrErrorCorrection = 'L' | 'M' | 'Q' | 'H';
@@ -242,6 +370,20 @@ declare function renderPaymentQrSvg(sessionId: string, cellSize?: number, errorC
 declare function renderBrandedPaymentQrSvg(sessionId: string, cellSize?: number): string;
 /** QR markup wrapper for the checkout UI. */
 declare function renderPaymentQrMarkup(sessionId: string, cellSize?: number): string;
+/** Plain QR markup for arbitrary URLs (e.g. app store links). */
+declare function renderUrlQrMarkup(url: string, cellSize?: number): string;
+
+/** Android intent URL — more reliable than raw `zippy://` in Chrome. */
+declare function buildAndroidPaymentIntentUrl(sessionId: string): string;
+/** Platform-aware deep link used when the customer taps Pay with Zippy / Try again. */
+declare function buildPaymentDeepLinkOpenUrl(sessionId: string, platform?: MobileStorePlatform): string;
+/** Sends the current tab to the App Store or Google Play for this device. */
+declare function openAppStore(platform?: MobileStorePlatform): void;
+/**
+ * Opens the Zippy app from a user gesture (Pay with Zippy / Try again).
+ * Keeps the checkout page visible so failed-handoff UI can appear afterward.
+ */
+declare function openPaymentDeepLink(sessionId: string): void;
 
 /** Aligned with zippy-kyc-web-sdk `src/styles/tokens.css` */
 declare const DEFAULT_THEME: Required<Omit<ZippyTheme, 'mode'>> & {
@@ -262,4 +404,4 @@ declare const ZippyPay: {
     create(config: ZippyPayConfig): ZippyPayCheckoutInstance;
 };
 
-export { type ApiCheckoutMethod, CheckoutController, type CheckoutMethod, type CheckoutPhase, DEFAULT_THEME, ELEMENT_TAG, type EmbedMode, PAYMENT_ID_PATTERN, POLLABLE_STATUSES, type PaymentSession, PaymentSessionClient, type PaymentSessionPayer, type PaymentSessionPhase, type PaymentSessionStatus, type ProblemJson, SessionPoller, TERMINAL_STATUSES, type VerifyPayerResponse, ZIPPY_API_BASE_URLS, ZIPPY_API_PATH_PREFIX, type ZippyEnvironment, ZippyPay, ZippyPayCheckoutElement, type ZippyPayCheckoutInstance, type ZippyPayConfig, ZippyPayError, type ZippyTheme, applyThemeToHost, attachPayerWithRetry, buildPaymentQrPayload, createCheckout, ZippyPay as default, defineZippyPayCheckoutElement, formatAmount, getCountdownTarget, getPayWindowRemainingRatio, getSoftIdleHint, isTerminalStatus, isValidPaymentId, isZippyEnvironment, msUntil, normalizePaymentId, parseZippyEnvironment, paymentIdValidationMessage, phaseFromSession, renderBrandedPaymentQrSvg, renderPaymentQrMarkup, renderPaymentQrSvg, renderQrSvg, resolveApiBaseUrl, resolveTheme, shouldShowPayProgress };
+export { ANDROID_APP_PACKAGE, ANDROID_PLAY_STORE_NATIVE_URL, APP_STORE_LINKS, type ApiCheckoutMethod, type ApiCheckoutPolicy, type ApiMobileAppPolicy, type AppStoreLinks, type BindCheckoutPolicyRequest, type BoundCheckoutPolicy, CheckoutController, type CheckoutMethod, type CheckoutPhase, type CheckoutPolicy, type CheckoutSurface, DEFAULT_THEME, E164_PHONE_PATTERN, ELEMENT_TAG, EMAIL_PATTERN, type EmbedMode, IOS_APP_STORE_NATIVE_URL, type MobileAppPolicy, PAYMENT_ID_PATTERN, POLLABLE_STATUSES, type PayerPreview, type PaymentSession, PaymentSessionClient, type PaymentSessionPayer, type PaymentSessionPhase, type PaymentSessionStatus, type ProblemJson, SessionPoller, type StartCheckoutRequest, TERMINAL_STATUSES, type VerifyPayerResponse, ZIPPY_API_BASE_URLS, ZIPPY_API_PATH_PREFIX, type ZippyEnvironment, type ZippyMobileAppConfig, ZippyPay, ZippyPayCheckoutElement, type ZippyPayCheckoutInstance, type ZippyPayConfig, ZippyPayError, type ZippyTheme, applyThemeToHost, attachPayerWithRetry, buildAndroidPaymentIntentUrl, buildBindPolicyRequest, buildPaymentDeepLinkOpenUrl, buildPaymentQrPayload, createCheckout, ZippyPay as default, defineZippyPayCheckoutElement, detectCheckoutSurface, formatAmount, getCountdownTarget, getPayWindowRemainingRatio, getSoftIdleHint, isAndroidDevice, isCheckoutPolicyBound, isCheckoutStartAllowed, isFullChooserPolicy, isPhoneDevice, isTerminalStatus, isValidPayerQuery, isValidPaymentId, isZippyEnvironment, msUntil, normalizePayerQuery, normalizePaymentId, openAppStore, openPaymentDeepLink, parseZippyEnvironment, payerQueryValidationMessage, paymentIdValidationMessage, phaseFromSession, renderBrandedPaymentQrSvg, renderPaymentQrMarkup, renderPaymentQrSvg, renderQrSvg, renderUrlQrMarkup, resolveApiBaseUrl, resolveAppStoreOpenUrl, resolveAppStoreUrl, resolveAutoStartMethod, resolveCheckoutUiOptions, resolveCheckoutUiOptionsFromBound, resolveCheckoutUiOptionsFromSession, resolveEntryRouting, resolveMethodAvailability, resolveMobileAppPolicy, resolveTheme, shouldShowPayProgress, subscribeCheckoutSurface };

package/dist/index.d.ts

@@ -9,12 +9,39 @@ declare function parseZippyEnvironment(value: string): ZippyEnvironment;
 type PaymentSessionStatus = 'CREATED' | 'AWAITING_PAYMENT' | 'COMPLETED' | 'EXPIRED' | 'CANCELLED' | 'FAILED';
 type PaymentSessionPhase = 'IDLE' | 'PAYING';
 /** Server checkout method — locks after checkout start. */
-type ApiCheckoutMethod = 'QR' | 'MANUAL';
+type ApiCheckoutMethod = 'QR' | 'MANUAL' | 'MOBILE_APP';
+/** SDK init — omit to allow both QR and Manual. */
+type CheckoutPolicy = 'QR' | 'MANUAL';
+/** SDK init — phone-only app handoff preference. */
+type MobileAppPolicy = 'off' | 'option' | 'enforce';
+/** Explicit checkout restriction returned by the API. */
+type ApiCheckoutPolicy = 'QR' | 'MANUAL';
+/** Bound checkout policy — `null` means full chooser (QR + manual). */
+type BoundCheckoutPolicy = ApiCheckoutPolicy | null;
+/** Bound mobile app policy returned by the API. */
+type ApiMobileAppPolicy = 'OFF' | 'OPTION' | 'ENFORCE';
+type BindCheckoutPolicyRequest = {
+    checkoutPolicy?: ApiCheckoutPolicy;
+    mobileAppPolicy?: ApiMobileAppPolicy;
+};
+type CheckoutSurface = 'phone' | 'desktop';
+type StartCheckoutRequest = {
+    method: ApiCheckoutMethod;
+    surface: CheckoutSurface;
+};
+type ZippyMobileAppConfig = {
+    policy?: MobileAppPolicy;
+};
 type PaymentSessionPayer = {
     paymentId: string;
     displayName: string;
     profileImage: string | null;
 };
+/** Payer preview returned from verify — same fields as session payer. */
+type PayerPreview = PaymentSessionPayer;
+type VerifyPayerResponse = {
+    items: PayerPreview[];
+};
 type PaymentSession = {
     sessionId: string;
     amount: string;
@@ -32,12 +59,15 @@ type PaymentSession = {
     absoluteExpiresAt: string;
     phase: PaymentSessionPhase;
     checkoutMethod: ApiCheckoutMethod | null;
+    /** Set after bind-policy — `null` = full chooser when `mobileAppPolicy` is set. */
+    checkoutPolicy: BoundCheckoutPolicy;
+    /** Set after bind-policy succeeds; null until then. */
+    mobileAppPolicy: ApiMobileAppPolicy | null;
     paymentStartAt: string | null;
     /** Pay window countdown — only meaningful when phase is PAYING. */
     paymentExpiryAt: string | null;
     createdAt: string;
 };
-type VerifyPayerResponse = PaymentSessionPayer;
 type ProblemJson = {
     type?: string;
     title?: string;
@@ -71,6 +101,10 @@ type ZippyPayConfig = {
     mode?: EmbedMode;
     container?: HTMLElement | string;
     theme?: ZippyTheme;
+    /** When omitted, customer can choose QR or Manual. */
+    checkoutPolicy?: CheckoutPolicy;
+    /** Phone-only app handoff. Ignored on non-phone devices. */
+    mobileApp?: ZippyMobileAppConfig;
     locale?: 'en';
     redirectOnComplete?: boolean;
     redirectOnFailure?: boolean;
@@ -83,8 +117,8 @@ type ZippyPayConfig = {
     onError?: (error: ZippyPayError) => void;
     onClose?: () => void;
 };
-type CheckoutMethod = 'qr' | 'manual';
-type CheckoutPhase = 'loading' | 'choose-method' | 'qr-active' | 'manual-entry' | 'manual-confirm' | 'awaiting' | 'success' | 'expired' | 'cancelled' | 'declined' | 'failed' | 'error' | 'invalid-session';
+type CheckoutMethod = 'qr' | 'manual' | 'mobileApp';
+type CheckoutPhase = 'loading' | 'choose-method' | 'qr-active' | 'mobile-app-active' | 'manual-entry' | 'manual-picker' | 'manual-confirm' | 'awaiting' | 'success' | 'expired' | 'cancelled' | 'declined' | 'failed' | 'error' | 'invalid-session';
 declare const TERMINAL_STATUSES: readonly PaymentSessionStatus[];
 declare const POLLABLE_STATUSES: readonly PaymentSessionStatus[];
 declare class ZippyPayError extends Error {
@@ -111,11 +145,13 @@ declare class PaymentSessionClient {
     private readonly clientToken;
     constructor(config: ApiClientConfig);
     getSession(): Promise<PaymentSession>;
-    verifyPayer(paymentId: string): Promise<VerifyPayerResponse>;
+    bindCheckoutPolicy(body: BindCheckoutPolicyRequest): Promise<PaymentSession>;
+    verifyPayer(query: string): Promise<VerifyPayerResponse>;
     attachPayer(paymentId: string): Promise<PaymentSession>;
-    startCheckout(method: ApiCheckoutMethod): Promise<PaymentSession>;
-    startQrCheckout(): Promise<PaymentSession>;
-    startManualCheckout(): Promise<PaymentSession>;
+    startCheckout(method: StartCheckoutRequest['method'], surface: CheckoutSurface): Promise<PaymentSession>;
+    startQrCheckout(surface: CheckoutSurface): Promise<PaymentSession>;
+    startMobileAppCheckout(surface: CheckoutSurface): Promise<PaymentSession>;
+    startManualCheckout(surface: CheckoutSurface): Promise<PaymentSession>;
     private sessionPath;
     private headers;
     private request;
@@ -166,6 +202,8 @@ declare class CheckoutController implements ZippyPayCheckoutInstance {
     private session;
     private paymentId;
     private verifiedPayer;
+    private verifyMatches;
+    private lastVerifiedQuery;
     private committedMethod;
     private phase;
     private errorMessage;
@@ -174,6 +212,14 @@ declare class CheckoutController implements ZippyPayCheckoutInstance {
     private modalOpen;
     private exitMode;
     private terminalFailureReason;
+    private uiOptions;
+    private appHandoffStatus;
+    private clearAppHandoffWatch;
+    private methodSwitchInProgress;
+    private entryRoutingDone;
+    private payWindowExpiryTimer;
+    private unsubscribeSurface;
+    private static readonly PAY_WINDOW_PHASES;
     constructor(config: ZippyPayConfig);
     open(): void;
     close(): void;
@@ -181,7 +227,13 @@ declare class CheckoutController implements ZippyPayCheckoutInstance {
     private snapshotUiState;
     private syncUi;
     private bootstrap;
+    private bindPolicy;
+    private applyBoundUiOptions;
+    private handleSurfaceChange;
     private applySession;
+    private schedulePayWindowExpiryWatch;
+    private clearPayWindowExpiryWatch;
+    private handlePayWindowExpired;
     private resolveActivePhase;
     private handleSessionUpdate;
     private handleFailure;
@@ -191,8 +243,21 @@ declare class CheckoutController implements ZippyPayCheckoutInstance {
     private failurePhaseFromReason;
     private teardownView;
     private handleBootstrapError;
+    private handlePollError;
     private handleError;
+    private routeIdleEntry;
+    private openMobileApp;
+    private beginMobileAppHandoff;
+    private installZippy;
+    private startMobileAppFlow;
+    private canStartAppClaim;
     private chooseMethod;
+    private chooseFallbackMethod;
+    private backToChooseMethod;
+    private backToManualEntry;
+    private backToMobileAppFallback;
+    private isMobileAppManualFallbackActive;
+    private selectPayer;
     private verify;
     private attach;
     private handleFlowError;
@@ -227,11 +292,74 @@ declare global {
 
 /** Personal Zippy handles: 3–20 chars, optional single dot, no leading/trailing dot. */
 declare const PAYMENT_ID_PATTERN: RegExp;
+declare const E164_PHONE_PATTERN: RegExp;
+declare const EMAIL_PATTERN: RegExp;
 declare function normalizePaymentId(value: string): string;
+/** Normalize a payer verify query before sending to the API. */
+declare function normalizePayerQuery(value: string): string;
 declare function isValidPaymentId(value: string): boolean;
+/** Client-side pre-validation for payer verify `query` (server is authoritative). */
+declare function isValidPayerQuery(value: string): boolean;
 declare function paymentIdValidationMessage(): string;
+declare function payerQueryValidationMessage(): string;
 declare function formatAmount(amount: string, currency: string): string;
 
+type MobileStorePlatform = 'ios' | 'android';
+/** True when checkout runs on a phone-sized touch device. */
+declare function isPhoneDevice(): boolean;
+/** True when the browser reports an Android user agent. */
+declare function isAndroidDevice(): boolean;
+declare function detectCheckoutSurface(): CheckoutSurface;
+declare function subscribeCheckoutSurface(onChange: (surface: CheckoutSurface) => void): () => void;
+
+/** Fixed App Store / Google Play URLs for Zippy Pay (managed server-side; not merchant-configurable). */
+type AppStoreLinks = {
+    ios: string;
+    android: string;
+};
+declare const ANDROID_APP_PACKAGE = "com.zippy.pay";
+/** HTTPS store URLs — used for QR codes and desktop fallback links. */
+declare const APP_STORE_LINKS: AppStoreLinks;
+/** Opens the native App Store app on iOS (no specific listing until app id is available). */
+declare const IOS_APP_STORE_NATIVE_URL = "itms-apps://apps.apple.com/";
+/** Opens the native Play Store app on Android. */
+declare const ANDROID_PLAY_STORE_NATIVE_URL = "market://details?id=com.zippy.pay";
+declare function resolveAppStoreUrl(platform: MobileStorePlatform): string;
+/**
+ * URL used when the customer taps Install Zippy.
+ * iOS and Android both use native store schemes from a user gesture.
+ */
+declare function resolveAppStoreOpenUrl(platform: MobileStorePlatform): string;
+
+type EntryRoutingAction = 'chooser' | 'auto-qr' | 'auto-manual' | 'enforce-mobile-app';
+type MethodAvailability = {
+    qr: boolean;
+    manual: boolean;
+    mobileApp: boolean;
+};
+type ResolvedCheckoutUiOptions = {
+    checkoutPolicy: BoundCheckoutPolicy;
+    mobileAppPolicy: ApiMobileAppPolicy;
+    surface: CheckoutSurface;
+    methodAvailability: MethodAvailability;
+    allowManualBack: boolean;
+};
+type AppClaimCheckoutMethod = Extract<ApiCheckoutMethod, 'QR' | 'MOBILE_APP'>;
+declare function isCheckoutPolicyBound(session: PaymentSession): boolean;
+declare function isFullChooserPolicy(checkoutPolicy: BoundCheckoutPolicy): boolean;
+declare function resolveMobileAppPolicy(mobileApp?: ZippyMobileAppConfig): ApiMobileAppPolicy;
+declare function buildBindPolicyRequest(config: {
+    checkoutPolicy?: CheckoutPolicy;
+    mobileApp?: ZippyMobileAppConfig;
+}): BindCheckoutPolicyRequest;
+declare function resolveMethodAvailability(checkoutPolicy: BoundCheckoutPolicy, mobileAppPolicy: ApiMobileAppPolicy, surface: CheckoutSurface): MethodAvailability;
+declare function resolveEntryRouting(checkoutPolicy: BoundCheckoutPolicy, mobileAppPolicy: ApiMobileAppPolicy, surface: CheckoutSurface): EntryRoutingAction;
+declare function isCheckoutStartAllowed(checkoutPolicy: BoundCheckoutPolicy, mobileAppPolicy: ApiMobileAppPolicy, surface: CheckoutSurface, method: AppClaimCheckoutMethod): boolean;
+declare function resolveAutoStartMethod(checkoutPolicy: BoundCheckoutPolicy, mobileAppPolicy: ApiMobileAppPolicy, surface: CheckoutSurface): AppClaimCheckoutMethod | null;
+declare function resolveCheckoutUiOptionsFromBound(checkoutPolicy: BoundCheckoutPolicy, mobileAppPolicy: ApiMobileAppPolicy, surface?: CheckoutSurface): ResolvedCheckoutUiOptions;
+declare function resolveCheckoutUiOptionsFromSession(session: PaymentSession, surface?: CheckoutSurface): ResolvedCheckoutUiOptions;
+declare function resolveCheckoutUiOptions(checkoutPolicy?: CheckoutPolicy, mobileApp?: ZippyMobileAppConfig, surface?: CheckoutSurface): ResolvedCheckoutUiOptions;
+
 /** Deep link scanned by the Zippy app — sessionId only, never clientToken. */
 declare function buildPaymentQrPayload(sessionId: string): string;
 type QrErrorCorrection = 'L' | 'M' | 'Q' | 'H';
@@ -242,6 +370,20 @@ declare function renderPaymentQrSvg(sessionId: string, cellSize?: number, errorC
 declare function renderBrandedPaymentQrSvg(sessionId: string, cellSize?: number): string;
 /** QR markup wrapper for the checkout UI. */
 declare function renderPaymentQrMarkup(sessionId: string, cellSize?: number): string;
+/** Plain QR markup for arbitrary URLs (e.g. app store links). */
+declare function renderUrlQrMarkup(url: string, cellSize?: number): string;
+
+/** Android intent URL — more reliable than raw `zippy://` in Chrome. */
+declare function buildAndroidPaymentIntentUrl(sessionId: string): string;
+/** Platform-aware deep link used when the customer taps Pay with Zippy / Try again. */
+declare function buildPaymentDeepLinkOpenUrl(sessionId: string, platform?: MobileStorePlatform): string;
+/** Sends the current tab to the App Store or Google Play for this device. */
+declare function openAppStore(platform?: MobileStorePlatform): void;
+/**
+ * Opens the Zippy app from a user gesture (Pay with Zippy / Try again).
+ * Keeps the checkout page visible so failed-handoff UI can appear afterward.
+ */
+declare function openPaymentDeepLink(sessionId: string): void;
 
 /** Aligned with zippy-kyc-web-sdk `src/styles/tokens.css` */
 declare const DEFAULT_THEME: Required<Omit<ZippyTheme, 'mode'>> & {
@@ -262,4 +404,4 @@ declare const ZippyPay: {
     create(config: ZippyPayConfig): ZippyPayCheckoutInstance;
 };
 
-export { type ApiCheckoutMethod, CheckoutController, type CheckoutMethod, type CheckoutPhase, DEFAULT_THEME, ELEMENT_TAG, type EmbedMode, PAYMENT_ID_PATTERN, POLLABLE_STATUSES, type PaymentSession, PaymentSessionClient, type PaymentSessionPayer, type PaymentSessionPhase, type PaymentSessionStatus, type ProblemJson, SessionPoller, TERMINAL_STATUSES, type VerifyPayerResponse, ZIPPY_API_BASE_URLS, ZIPPY_API_PATH_PREFIX, type ZippyEnvironment, ZippyPay, ZippyPayCheckoutElement, type ZippyPayCheckoutInstance, type ZippyPayConfig, ZippyPayError, type ZippyTheme, applyThemeToHost, attachPayerWithRetry, buildPaymentQrPayload, createCheckout, ZippyPay as default, defineZippyPayCheckoutElement, formatAmount, getCountdownTarget, getPayWindowRemainingRatio, getSoftIdleHint, isTerminalStatus, isValidPaymentId, isZippyEnvironment, msUntil, normalizePaymentId, parseZippyEnvironment, paymentIdValidationMessage, phaseFromSession, renderBrandedPaymentQrSvg, renderPaymentQrMarkup, renderPaymentQrSvg, renderQrSvg, resolveApiBaseUrl, resolveTheme, shouldShowPayProgress };
+export { ANDROID_APP_PACKAGE, ANDROID_PLAY_STORE_NATIVE_URL, APP_STORE_LINKS, type ApiCheckoutMethod, type ApiCheckoutPolicy, type ApiMobileAppPolicy, type AppStoreLinks, type BindCheckoutPolicyRequest, type BoundCheckoutPolicy, CheckoutController, type CheckoutMethod, type CheckoutPhase, type CheckoutPolicy, type CheckoutSurface, DEFAULT_THEME, E164_PHONE_PATTERN, ELEMENT_TAG, EMAIL_PATTERN, type EmbedMode, IOS_APP_STORE_NATIVE_URL, type MobileAppPolicy, PAYMENT_ID_PATTERN, POLLABLE_STATUSES, type PayerPreview, type PaymentSession, PaymentSessionClient, type PaymentSessionPayer, type PaymentSessionPhase, type PaymentSessionStatus, type ProblemJson, SessionPoller, type StartCheckoutRequest, TERMINAL_STATUSES, type VerifyPayerResponse, ZIPPY_API_BASE_URLS, ZIPPY_API_PATH_PREFIX, type ZippyEnvironment, type ZippyMobileAppConfig, ZippyPay, ZippyPayCheckoutElement, type ZippyPayCheckoutInstance, type ZippyPayConfig, ZippyPayError, type ZippyTheme, applyThemeToHost, attachPayerWithRetry, buildAndroidPaymentIntentUrl, buildBindPolicyRequest, buildPaymentDeepLinkOpenUrl, buildPaymentQrPayload, createCheckout, ZippyPay as default, defineZippyPayCheckoutElement, detectCheckoutSurface, formatAmount, getCountdownTarget, getPayWindowRemainingRatio, getSoftIdleHint, isAndroidDevice, isCheckoutPolicyBound, isCheckoutStartAllowed, isFullChooserPolicy, isPhoneDevice, isTerminalStatus, isValidPayerQuery, isValidPaymentId, isZippyEnvironment, msUntil, normalizePayerQuery, normalizePaymentId, openAppStore, openPaymentDeepLink, parseZippyEnvironment, payerQueryValidationMessage, paymentIdValidationMessage, phaseFromSession, renderBrandedPaymentQrSvg, renderPaymentQrMarkup, renderPaymentQrSvg, renderQrSvg, renderUrlQrMarkup, resolveApiBaseUrl, resolveAppStoreOpenUrl, resolveAppStoreUrl, resolveAutoStartMethod, resolveCheckoutUiOptions, resolveCheckoutUiOptionsFromBound, resolveCheckoutUiOptionsFromSession, resolveEntryRouting, resolveMethodAvailability, resolveMobileAppPolicy, resolveTheme, shouldShowPayProgress, subscribeCheckoutSurface };