@idealyst/payments 1.2.108

package/README.md

@@ -0,0 +1,100 @@
+# @idealyst/payments
+
+Cross-platform payment provider abstractions for React and React Native. Wraps Stripe's Platform Pay API for Apple Pay and Google Pay on mobile.
+
+## Installation
+
+```bash
+yarn add @idealyst/payments
+```
+
+### Native (required for mobile payments)
+
+```bash
+yarn add @stripe/stripe-react-native
+```
+
+Follow the [Stripe React Native setup guide](https://github.com/stripe/stripe-react-native#installation) for iOS/Android configuration.
+
+### Web
+
+No additional dependencies. Web provides a stub that reports all payment methods as unavailable — use [Stripe Elements](https://stripe.com/docs/stripe-js/react) (`@stripe/react-stripe-js`) for web payments.
+
+## Quick Start
+
+```tsx
+import { usePayments } from '@idealyst/payments';
+
+function CheckoutScreen() {
+  const {
+    isReady,
+    isApplePayAvailable,
+    isGooglePayAvailable,
+    isProcessing,
+    error,
+    confirmPayment,
+  } = usePayments({
+    config: {
+      publishableKey: 'pk_test_xxx',
+      merchantIdentifier: 'merchant.com.myapp',
+      merchantName: 'My App',
+      merchantCountryCode: 'US',
+    },
+  });
+
+  const handlePay = async () => {
+    const result = await confirmPayment({
+      clientSecret: 'pi_xxx_secret_xxx', // from your server
+      amount: { amount: 1099, currencyCode: 'usd' },
+      lineItems: [
+        { label: 'Widget', amount: 999 },
+        { label: 'Tax', amount: 100 },
+      ],
+    });
+    console.log('Paid:', result.paymentIntentId);
+  };
+
+  if (!isReady) return null;
+
+  return (
+    <Button
+      onPress={handlePay}
+      disabled={isProcessing || (!isApplePayAvailable && !isGooglePayAvailable)}
+      label={isApplePayAvailable ? 'Pay with Apple Pay' : 'Pay with Google Pay'}
+    />
+  );
+}
+```
+
+## Flat Function API
+
+For more control, use the flat functions directly:
+
+```typescript
+import {
+  initializePayments,
+  checkPaymentAvailability,
+  confirmPayment,
+  createPaymentMethod,
+} from '@idealyst/payments';
+
+await initializePayments({
+  publishableKey: 'pk_test_xxx',
+  merchantName: 'My App',
+  merchantCountryCode: 'US',
+});
+
+const methods = await checkPaymentAvailability();
+const result = await confirmPayment({ clientSecret: '...', amount: { amount: 1099, currencyCode: 'usd' } });
+```
+
+## Platform Support
+
+| Feature | iOS | Android | Web |
+|---------|-----|---------|-----|
+| Apple Pay | Yes | — | — |
+| Google Pay | — | Yes | — |
+| Card (via sheet) | Yes | Yes | — |
+| usePayments hook | Yes | Yes | Stub |
+
+Web returns all methods as unavailable. Use `@stripe/react-stripe-js` for web payments.

package/package.json

@@ -0,0 +1,71 @@
+{
+  "name": "@idealyst/payments",
+  "version": "1.2.108",
+  "description": "Cross-platform payment provider abstractions for React and React Native (Apple Pay, Google Pay, Stripe)",
+  "documentation": "https://github.com/IdealystIO/idealyst-framework/tree/main/packages/payments#readme",
+  "readme": "README.md",
+  "main": "src/index.ts",
+  "module": "src/index.ts",
+  "types": "src/index.ts",
+  "react-native": "src/index.native.ts",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/IdealystIO/idealyst-framework.git",
+    "directory": "packages/payments"
+  },
+  "author": "Idealyst <contact@idealyst.io>",
+  "license": "MIT",
+  "publishConfig": {
+    "access": "public"
+  },
+  "exports": {
+    ".": {
+      "react-native": "./src/index.native.ts",
+      "browser": {
+        "types": "./src/index.web.ts",
+        "import": "./src/index.web.ts",
+        "require": "./src/index.web.ts"
+      },
+      "default": {
+        "types": "./src/index.ts",
+        "import": "./src/index.ts",
+        "require": "./src/index.ts"
+      }
+    }
+  },
+  "scripts": {
+    "prepublishOnly": "echo 'Publishing TypeScript source directly'",
+    "publish:npm": "npm publish"
+  },
+  "peerDependencies": {
+    "@stripe/stripe-react-native": ">=0.38.0",
+    "react": ">=16.8.0",
+    "react-native": ">=0.60.0"
+  },
+  "peerDependenciesMeta": {
+    "@stripe/stripe-react-native": {
+      "optional": true
+    },
+    "react-native": {
+      "optional": true
+    }
+  },
+  "devDependencies": {
+    "@types/react": "^19.1.0",
+    "typescript": "^5.0.0"
+  },
+  "files": [
+    "src",
+    "README.md"
+  ],
+  "keywords": [
+    "react",
+    "react-native",
+    "payments",
+    "apple-pay",
+    "google-pay",
+    "stripe",
+    "platform-pay",
+    "cross-platform"
+  ]
+}

package/src/constants.ts

@@ -0,0 +1,7 @@
+import type { PaymentProviderStatus } from './types';
+
+export const INITIAL_PROVIDER_STATUS: PaymentProviderStatus = {
+  state: 'uninitialized',
+  availablePaymentMethods: [],
+  isPaymentAvailable: false,
+};

package/src/errors.ts

@@ -0,0 +1,46 @@
+import type { PaymentError, PaymentErrorCode } from './types';
+
+export function createPaymentError(
+  code: PaymentErrorCode,
+  message: string,
+  originalError?: unknown,
+): PaymentError {
+  return { code, message, originalError };
+}
+
+/**
+ * Normalize a Stripe error (or any thrown value) into a PaymentError.
+ */
+export function normalizeError(error: unknown): PaymentError {
+  if (error && typeof error === 'object' && 'code' in error) {
+    const stripeError = error as { code?: string; message?: string };
+
+    switch (stripeError.code) {
+      case 'Canceled':
+      case 'cancelled':
+        return createPaymentError(
+          'user_cancelled',
+          'Payment was cancelled by user',
+          error,
+        );
+      case 'Failed':
+        return createPaymentError(
+          'payment_failed',
+          stripeError.message || 'Payment failed',
+          error,
+        );
+      default:
+        return createPaymentError(
+          'provider_error',
+          stripeError.message || 'An error occurred with the payment provider',
+          error,
+        );
+    }
+  }
+
+  if (error instanceof Error) {
+    return createPaymentError('unknown', error.message, error);
+  }
+
+  return createPaymentError('unknown', String(error), error);
+}

package/src/index.native.ts

@@ -0,0 +1,27 @@
+export * from './types';
+export { INITIAL_PROVIDER_STATUS } from './constants';
+export { createPaymentError, normalizeError } from './errors';
+export {
+  initializePayments,
+  checkPaymentAvailability,
+  confirmPayment,
+  createPaymentMethod,
+  getPaymentStatus,
+} from './payments.native';
+
+import { createUsePaymentsHook } from './usePayments';
+import {
+  initializePayments,
+  checkPaymentAvailability,
+  confirmPayment,
+  createPaymentMethod,
+  getPaymentStatus,
+} from './payments.native';
+
+export const usePayments = createUsePaymentsHook({
+  initializePayments,
+  checkPaymentAvailability,
+  confirmPayment,
+  createPaymentMethod,
+  getPaymentStatus,
+});

package/src/index.ts

@@ -0,0 +1,29 @@
+// Default entry — re-exports web implementation.
+// Platform-specific entry points (index.native.ts, index.web.ts) are resolved by bundlers.
+export * from './types';
+export { INITIAL_PROVIDER_STATUS } from './constants';
+export { createPaymentError, normalizeError } from './errors';
+export {
+  initializePayments,
+  checkPaymentAvailability,
+  confirmPayment,
+  createPaymentMethod,
+  getPaymentStatus,
+} from './payments.web';
+
+import { createUsePaymentsHook } from './usePayments';
+import {
+  initializePayments,
+  checkPaymentAvailability,
+  confirmPayment,
+  createPaymentMethod,
+  getPaymentStatus,
+} from './payments.web';
+
+export const usePayments = createUsePaymentsHook({
+  initializePayments,
+  checkPaymentAvailability,
+  confirmPayment,
+  createPaymentMethod,
+  getPaymentStatus,
+});

package/src/index.web.ts

@@ -0,0 +1,27 @@
+export * from './types';
+export { INITIAL_PROVIDER_STATUS } from './constants';
+export { createPaymentError, normalizeError } from './errors';
+export {
+  initializePayments,
+  checkPaymentAvailability,
+  confirmPayment,
+  createPaymentMethod,
+  getPaymentStatus,
+} from './payments.web';
+
+import { createUsePaymentsHook } from './usePayments';
+import {
+  initializePayments,
+  checkPaymentAvailability,
+  confirmPayment,
+  createPaymentMethod,
+  getPaymentStatus,
+} from './payments.web';
+
+export const usePayments = createUsePaymentsHook({
+  initializePayments,
+  checkPaymentAvailability,
+  confirmPayment,
+  createPaymentMethod,
+  getPaymentStatus,
+});

package/src/payments.native.ts

@@ -0,0 +1,301 @@
+// ============================================================================
+// Native Payment Implementation
+// Wraps @stripe/stripe-react-native Platform Pay API for Apple Pay & Google Pay
+// ============================================================================
+
+import { Platform } from 'react-native';
+import type {
+  PaymentConfig,
+  PaymentProviderStatus,
+  PaymentMethodAvailability,
+  PaymentMethodType,
+  PaymentSheetRequest,
+  PaymentResult,
+} from './types';
+import { INITIAL_PROVIDER_STATUS } from './constants';
+import { createPaymentError, normalizeError } from './errors';
+
+// Graceful optional import — @stripe/stripe-react-native may not be installed
+// eslint-disable-next-line @typescript-eslint/no-explicit-any
+let Stripe: any = null;
+try {
+  Stripe = require('@stripe/stripe-react-native');
+} catch {
+  // Will degrade gracefully when methods are called
+}
+
+// Module-level state
+let _status: PaymentProviderStatus = { ...INITIAL_PROVIDER_STATUS };
+let _config: PaymentConfig | null = null;
+
+/**
+ * Get the current payment provider status.
+ */
+export function getPaymentStatus(): PaymentProviderStatus {
+  return { ..._status };
+}
+
+/**
+ * Initialize the Stripe SDK for platform payments.
+ */
+export async function initializePayments(
+  config: PaymentConfig,
+): Promise<void> {
+  if (!Stripe) {
+    _status = {
+      ..._status,
+      state: 'error',
+      error: createPaymentError(
+        'not_available',
+        '@stripe/stripe-react-native is not installed. Run: yarn add @stripe/stripe-react-native',
+      ),
+    };
+    return;
+  }
+
+  _status = { ..._status, state: 'initializing' };
+  _config = config;
+
+  try {
+    await Stripe.initStripe({
+      publishableKey: config.publishableKey,
+      merchantIdentifier: config.merchantIdentifier,
+      urlScheme: config.urlScheme,
+    });
+
+    const availability = await checkPaymentAvailability();
+
+    _status = {
+      state: 'ready',
+      availablePaymentMethods: availability,
+      isPaymentAvailable: availability.some((m) => m.isAvailable),
+    };
+  } catch (error) {
+    _status = {
+      ..._status,
+      state: 'error',
+      error: normalizeError(error),
+    };
+  }
+}
+
+/**
+ * Check which payment methods (Apple Pay, Google Pay, card) are available.
+ */
+export async function checkPaymentAvailability(): Promise<
+  PaymentMethodAvailability[]
+> {
+  if (!Stripe) {
+    return [
+      {
+        type: 'apple_pay',
+        isAvailable: false,
+        unavailableReason: 'Stripe SDK not installed',
+      },
+      {
+        type: 'google_pay',
+        isAvailable: false,
+        unavailableReason: 'Stripe SDK not installed',
+      },
+      { type: 'card', isAvailable: false, unavailableReason: 'Stripe SDK not installed' },
+    ];
+  }
+
+  const results: PaymentMethodAvailability[] = [];
+  const isIOS = Platform.OS === 'ios';
+
+  try {
+    const isSupported = await Stripe.isPlatformPaySupported({
+      googlePay: {
+        testEnv: _config?.testEnvironment ?? false,
+      },
+    });
+
+    results.push({
+      type: 'apple_pay',
+      isAvailable: isIOS && isSupported,
+      unavailableReason: !isIOS
+        ? 'Apple Pay is only available on iOS'
+        : !isSupported
+          ? 'Apple Pay is not configured on this device'
+          : undefined,
+    });
+
+    results.push({
+      type: 'google_pay',
+      isAvailable: !isIOS && isSupported,
+      unavailableReason: isIOS
+        ? 'Google Pay is only available on Android'
+        : !isSupported
+          ? 'Google Pay is not configured on this device'
+          : undefined,
+    });
+  } catch (error) {
+    results.push(
+      {
+        type: 'apple_pay',
+        isAvailable: false,
+        unavailableReason: String(error),
+      },
+      {
+        type: 'google_pay',
+        isAvailable: false,
+        unavailableReason: String(error),
+      },
+    );
+  }
+
+  // Card payments are always conceptually available via Stripe
+  results.push({ type: 'card', isAvailable: true });
+
+  _status = {
+    ..._status,
+    availablePaymentMethods: results,
+    isPaymentAvailable: results.some((m) => m.isAvailable),
+  };
+
+  return results;
+}
+
+/**
+ * Present the platform payment sheet and confirm a PaymentIntent.
+ * Requires `request.clientSecret` from a server-created PaymentIntent.
+ */
+export async function confirmPayment(
+  request: PaymentSheetRequest,
+): Promise<PaymentResult> {
+  assertReady();
+
+  if (!request.clientSecret) {
+    throw createPaymentError(
+      'invalid_request',
+      'clientSecret is required for confirmPayment. Create a PaymentIntent on your server first.',
+    );
+  }
+
+  try {
+    const { error, paymentIntent } =
+      await Stripe!.confirmPlatformPayPayment(request.clientSecret, {
+        googlePay: buildGooglePayConfig(request),
+        applePay: buildApplePayConfig(request),
+      });
+
+    if (error) {
+      throw error;
+    }
+
+    return {
+      paymentMethodType: detectPlatformPayType(),
+      paymentIntentId: paymentIntent?.id,
+      status: paymentIntent?.status,
+    };
+  } catch (error) {
+    throw normalizeError(error);
+  }
+}
+
+/**
+ * Present the platform payment sheet and create a payment method
+ * without confirming. Returns a payment method ID for server-side use.
+ */
+export async function createPaymentMethod(
+  request: PaymentSheetRequest,
+): Promise<PaymentResult> {
+  assertReady();
+
+  try {
+    const { error, paymentMethod } =
+      await Stripe!.createPlatformPayPaymentMethod({
+        googlePay: {
+          ...buildGooglePayConfig(request),
+          amount: request.amount.amount,
+        },
+        applePay: buildApplePayConfig(request),
+      });
+
+    if (error) {
+      throw error;
+    }
+
+    return {
+      paymentMethodType: detectPlatformPayType(),
+      paymentMethodId: paymentMethod?.id,
+    };
+  } catch (error) {
+    throw normalizeError(error);
+  }
+}
+
+// ============================================================================
+// Internal Helpers
+// ============================================================================
+
+function assertReady(): void {
+  if (!Stripe) {
+    throw createPaymentError(
+      'not_available',
+      '@stripe/stripe-react-native is not installed',
+    );
+  }
+  if (_status.state !== 'ready') {
+    throw createPaymentError(
+      'not_initialized',
+      'Payment provider not initialized. Call initializePayments() first.',
+    );
+  }
+}
+
+function detectPlatformPayType(): PaymentMethodType {
+  return Platform.OS === 'ios' ? 'apple_pay' : 'google_pay';
+}
+
+function buildGooglePayConfig(request: PaymentSheetRequest) {
+  return {
+    testEnv: _config?.testEnvironment ?? false,
+    merchantName: _config!.merchantName,
+    merchantCountryCode: _config!.merchantCountryCode,
+    currencyCode: request.amount.currencyCode,
+    billingAddressConfig: request.billingAddress
+      ? {
+          isRequired: request.billingAddress.isRequired ?? false,
+          isPhoneNumberRequired:
+            request.billingAddress.isPhoneNumberRequired ?? false,
+          format:
+            request.billingAddress.format === 'FULL'
+              ? Stripe!.PlatformPay.BillingAddressFormat.Full
+              : Stripe!.PlatformPay.BillingAddressFormat.Min,
+        }
+      : undefined,
+  };
+}
+
+function buildApplePayConfig(request: PaymentSheetRequest) {
+  const cartItems: Array<{
+    label: string;
+    amount: string;
+    paymentType: number;
+  }> = [];
+
+  if (request.lineItems) {
+    for (const item of request.lineItems) {
+      cartItems.push({
+        label: item.label,
+        amount: (item.amount / 100).toFixed(2),
+        paymentType: Stripe!.PlatformPay.PaymentType.Immediate,
+      });
+    }
+  }
+
+  // Total line item (required by Apple Pay)
+  cartItems.push({
+    label: _config?.merchantName ?? 'Total',
+    amount: (request.amount.amount / 100).toFixed(2),
+    paymentType: Stripe!.PlatformPay.PaymentType.Immediate,
+  });
+
+  return {
+    cartItems,
+    merchantCountryCode: _config!.merchantCountryCode,
+    currencyCode: request.amount.currencyCode,
+  };
+}

package/src/payments.web.ts

@@ -0,0 +1,91 @@
+// ============================================================================
+// Web Payment Stub
+//
+// Native payment sheets (Apple Pay, Google Pay) are mobile-only concepts.
+// On web, use Stripe Elements (@stripe/react-stripe-js) or Stripe Checkout.
+//
+// This stub initializes and reports availability so the hook works,
+// but payment operations throw descriptive errors with guidance.
+// ============================================================================
+
+import type {
+  PaymentConfig,
+  PaymentProviderStatus,
+  PaymentMethodAvailability,
+  PaymentSheetRequest,
+  PaymentResult,
+} from './types';
+import { INITIAL_PROVIDER_STATUS } from './constants';
+import { createPaymentError } from './errors';
+
+const WEB_NOT_SUPPORTED_MESSAGE =
+  '@idealyst/payments does not provide a web payment UI. ' +
+  'Use Stripe Elements (@stripe/react-stripe-js) or Stripe Checkout for web payments.';
+
+const WEB_UNAVAILABLE_METHODS: PaymentMethodAvailability[] = [
+  {
+    type: 'apple_pay',
+    isAvailable: false,
+    unavailableReason: 'Apple Pay requires native iOS integration',
+  },
+  {
+    type: 'google_pay',
+    isAvailable: false,
+    unavailableReason: 'Google Pay requires native Android integration',
+  },
+  {
+    type: 'card',
+    isAvailable: false,
+    unavailableReason:
+      'Use Stripe Elements (@stripe/react-stripe-js) for web card payments',
+  },
+];
+
+let _status: PaymentProviderStatus = { ...INITIAL_PROVIDER_STATUS };
+
+/**
+ * Get the current payment provider status.
+ */
+export function getPaymentStatus(): PaymentProviderStatus {
+  return { ..._status };
+}
+
+/**
+ * Initialize — succeeds on web but reports all methods as unavailable.
+ */
+export async function initializePayments(
+  _config: PaymentConfig,
+): Promise<void> {
+  _status = {
+    state: 'ready',
+    availablePaymentMethods: WEB_UNAVAILABLE_METHODS,
+    isPaymentAvailable: false,
+  };
+}
+
+/**
+ * Check availability — all methods are unavailable on web.
+ */
+export async function checkPaymentAvailability(): Promise<
+  PaymentMethodAvailability[]
+> {
+  return WEB_UNAVAILABLE_METHODS;
+}
+
+/**
+ * Not supported on web — throws with guidance to use Stripe Elements.
+ */
+export async function confirmPayment(
+  _request: PaymentSheetRequest,
+): Promise<PaymentResult> {
+  throw createPaymentError('not_supported', WEB_NOT_SUPPORTED_MESSAGE);
+}
+
+/**
+ * Not supported on web — throws with guidance to use Stripe Elements.
+ */
+export async function createPaymentMethod(
+  _request: PaymentSheetRequest,
+): Promise<PaymentResult> {
+  throw createPaymentError('not_supported', WEB_NOT_SUPPORTED_MESSAGE);
+}

package/src/types.ts

@@ -0,0 +1,179 @@
+// ============================================================================
+// Payment Method Types
+// ============================================================================
+
+export type PaymentMethodType = 'apple_pay' | 'google_pay' | 'card';
+
+export interface PaymentMethodAvailability {
+  /** The payment method type. */
+  type: PaymentMethodType;
+  /** Whether this method is available on the current device. */
+  isAvailable: boolean;
+  /** Reason if unavailable. */
+  unavailableReason?: string;
+}
+
+// ============================================================================
+// Configuration
+// ============================================================================
+
+export interface PaymentConfig {
+  /** Stripe publishable key (pk_test_xxx or pk_live_xxx). */
+  publishableKey: string;
+
+  /**
+   * Apple Pay merchant identifier (e.g., "merchant.com.yourapp").
+   * Required for Apple Pay on iOS.
+   */
+  merchantIdentifier?: string;
+
+  /** Merchant display name shown on the payment sheet. */
+  merchantName: string;
+
+  /** ISO 3166-1 alpha-2 country code (e.g., "US", "GB"). */
+  merchantCountryCode: string;
+
+  /**
+   * URL scheme for 3D Secure redirects (e.g., "com.yourapp").
+   * Required on native for 3D Secure / bank redirect flows.
+   */
+  urlScheme?: string;
+
+  /** Use test environment for Google Pay. Default: false. */
+  testEnvironment?: boolean;
+}
+
+// ============================================================================
+// Payment Request
+// ============================================================================
+
+export interface PaymentAmount {
+  /** Amount in the smallest currency unit (e.g., cents for USD). */
+  amount: number;
+  /** ISO 4217 currency code (e.g., "usd", "eur"). */
+  currencyCode: string;
+}
+
+export interface PaymentLineItem {
+  /** Label displayed on the payment sheet (e.g., "Subtotal", "Tax"). */
+  label: string;
+  /** Amount in the smallest currency unit. */
+  amount: number;
+}
+
+export interface BillingAddressConfig {
+  /** Whether billing address is required. */
+  isRequired?: boolean;
+  /** Whether phone number is required. */
+  isPhoneNumberRequired?: boolean;
+  /** Address format: 'MIN' for name+postal, 'FULL' for complete address. */
+  format?: 'MIN' | 'FULL';
+}
+
+export interface PaymentSheetRequest {
+  /**
+   * PaymentIntent client secret from your server.
+   * Required for confirmPayment(), not needed for createPaymentMethod().
+   */
+  clientSecret?: string;
+
+  /** Total payment amount. Used for display and for createPaymentMethod flow. */
+  amount: PaymentAmount;
+
+  /** Line items displayed on the payment sheet. */
+  lineItems?: PaymentLineItem[];
+
+  /** Billing address requirements. */
+  billingAddress?: BillingAddressConfig;
+
+  /** Preferred payment methods. If empty, all available methods are shown. */
+  allowedPaymentMethods?: PaymentMethodType[];
+}
+
+// ============================================================================
+// Payment Result
+// ============================================================================
+
+export interface PaymentResult {
+  /** The payment method type that was used. */
+  paymentMethodType: PaymentMethodType;
+
+  /** Stripe payment method ID (pm_xxx). Present for createPaymentMethod flow. */
+  paymentMethodId?: string;
+
+  /** Stripe PaymentIntent ID (pi_xxx). Present for confirmPayment flow. */
+  paymentIntentId?: string;
+
+  /** PaymentIntent status (e.g., 'succeeded', 'requires_capture'). */
+  status?: string;
+}
+
+// ============================================================================
+// Error Types
+// ============================================================================
+
+export type PaymentErrorCode =
+  | 'not_initialized'
+  | 'not_available'
+  | 'not_supported'
+  | 'user_cancelled'
+  | 'payment_failed'
+  | 'network_error'
+  | 'invalid_config'
+  | 'invalid_request'
+  | 'provider_error'
+  | 'unknown';
+
+export interface PaymentError {
+  code: PaymentErrorCode;
+  message: string;
+  /** Original error from the underlying provider. */
+  originalError?: unknown;
+}
+
+// ============================================================================
+// Provider State
+// ============================================================================
+
+export type PaymentProviderState =
+  | 'uninitialized'
+  | 'initializing'
+  | 'ready'
+  | 'error';
+
+export interface PaymentProviderStatus {
+  state: PaymentProviderState;
+  availablePaymentMethods: PaymentMethodAvailability[];
+  isPaymentAvailable: boolean;
+  error?: PaymentError;
+}
+
+// ============================================================================
+// Hook Types
+// ============================================================================
+
+export interface UsePaymentsOptions {
+  /** If provided, auto-initializes the payment provider. */
+  config?: PaymentConfig;
+  /** Automatically check availability after init. Default: true. */
+  autoCheckAvailability?: boolean;
+}
+
+export interface UsePaymentsResult {
+  // State
+  status: PaymentProviderStatus;
+  isReady: boolean;
+  isProcessing: boolean;
+  availablePaymentMethods: PaymentMethodAvailability[];
+  isApplePayAvailable: boolean;
+  isGooglePayAvailable: boolean;
+  isPaymentAvailable: boolean;
+  error: PaymentError | null;
+
+  // Actions
+  initialize: (config: PaymentConfig) => Promise<void>;
+  checkAvailability: () => Promise<PaymentMethodAvailability[]>;
+  confirmPayment: (request: PaymentSheetRequest) => Promise<PaymentResult>;
+  createPaymentMethod: (request: PaymentSheetRequest) => Promise<PaymentResult>;
+  clearError: () => void;
+}

package/src/usePayments.ts

@@ -0,0 +1,137 @@
+import { useState, useCallback, useEffect, useRef } from 'react';
+import type {
+  UsePaymentsOptions,
+  UsePaymentsResult,
+  PaymentProviderStatus,
+  PaymentConfig,
+  PaymentError,
+  PaymentMethodAvailability,
+  PaymentSheetRequest,
+  PaymentResult,
+} from './types';
+import { INITIAL_PROVIDER_STATUS } from './constants';
+
+/**
+ * Factory that creates a usePayments hook bound to platform-specific functions.
+ * Each platform entry point calls this with the correct implementations.
+ */
+export function createUsePaymentsHook(fns: {
+  initializePayments: (config: PaymentConfig) => Promise<void>;
+  checkPaymentAvailability: () => Promise<PaymentMethodAvailability[]>;
+  confirmPayment: (request: PaymentSheetRequest) => Promise<PaymentResult>;
+  createPaymentMethod: (request: PaymentSheetRequest) => Promise<PaymentResult>;
+  getPaymentStatus: () => PaymentProviderStatus;
+}) {
+  return function usePayments(
+    options: UsePaymentsOptions = {},
+  ): UsePaymentsResult {
+    const { config, autoCheckAvailability = true } = options;
+
+    const [status, setStatus] = useState<PaymentProviderStatus>(
+      INITIAL_PROVIDER_STATUS,
+    );
+    const [isProcessing, setIsProcessing] = useState(false);
+    const [error, setError] = useState<PaymentError | null>(null);
+    const initializedRef = useRef(false);
+
+    // Auto-initialize if config provided
+    useEffect(() => {
+      if (!config || initializedRef.current) return;
+      initializedRef.current = true;
+
+      const init = async () => {
+        await fns.initializePayments(config);
+        const currentStatus = fns.getPaymentStatus();
+        setStatus(currentStatus);
+        setError(currentStatus.error ?? null);
+
+        if (autoCheckAvailability && currentStatus.state === 'ready') {
+          await fns.checkPaymentAvailability();
+          setStatus(fns.getPaymentStatus());
+        }
+      };
+      init();
+    }, [config, autoCheckAvailability]);
+
+    const initialize = useCallback(
+      async (initConfig: PaymentConfig) => {
+        setError(null);
+        await fns.initializePayments(initConfig);
+        const currentStatus = fns.getPaymentStatus();
+        setStatus(currentStatus);
+        setError(currentStatus.error ?? null);
+
+        if (autoCheckAvailability && currentStatus.state === 'ready') {
+          await fns.checkPaymentAvailability();
+          setStatus(fns.getPaymentStatus());
+        }
+      },
+      [autoCheckAvailability],
+    );
+
+    const checkAvailability = useCallback(async () => {
+      const result = await fns.checkPaymentAvailability();
+      setStatus(fns.getPaymentStatus());
+      return result;
+    }, []);
+
+    const confirmPaymentAction = useCallback(
+      async (request: PaymentSheetRequest) => {
+        setIsProcessing(true);
+        setError(null);
+        try {
+          return await fns.confirmPayment(request);
+        } catch (err) {
+          const paymentError = err as PaymentError;
+          setError(paymentError);
+          throw paymentError;
+        } finally {
+          setIsProcessing(false);
+        }
+      },
+      [],
+    );
+
+    const createPaymentMethodAction = useCallback(
+      async (request: PaymentSheetRequest) => {
+        setIsProcessing(true);
+        setError(null);
+        try {
+          return await fns.createPaymentMethod(request);
+        } catch (err) {
+          const paymentError = err as PaymentError;
+          setError(paymentError);
+          throw paymentError;
+        } finally {
+          setIsProcessing(false);
+        }
+      },
+      [],
+    );
+
+    const clearError = useCallback(() => setError(null), []);
+
+    const { availablePaymentMethods } = status;
+
+    return {
+      status,
+      isReady: status.state === 'ready',
+      isProcessing,
+      availablePaymentMethods,
+      isApplePayAvailable: availablePaymentMethods.some(
+        (m) => m.type === 'apple_pay' && m.isAvailable,
+      ),
+      isGooglePayAvailable: availablePaymentMethods.some(
+        (m) => m.type === 'google_pay' && m.isAvailable,
+      ),
+      isPaymentAvailable: status.isPaymentAvailable,
+      error,
+
+      initialize,
+      checkAvailability,
+      confirmPayment: confirmPaymentAction,
+      createPaymentMethod: createPaymentMethodAction,
+      clearError,
+    };
+  };
+}