@gmisoftware/react-native-pay 0.0.9 → 0.0.11

package/README.md

@@ -1,78 +1,186 @@
-# react-native-pay
+# React Native Pay
 
-A unified React Native payment module supporting both Apple Pay (iOS) and Google Pay (Android) with a consistent API across platforms.
+<div align="center">
+
+A unified React Native payment module supporting **Apple Pay** (iOS) and **Google Pay** (Android) with a consistent, type-safe API.
+
+[![npm version](https://img.shields.io/npm/v/@gmisoftware/react-native-pay.svg)](https://www.npmjs.com/package/@gmisoftware/react-native-pay)
+[![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](https://opensource.org/licenses/MIT)
+[![TypeScript](https://img.shields.io/badge/TypeScript-Ready-blue.svg)](https://www.typescriptlang.org/)
+[![Expo Compatible](https://img.shields.io/badge/Expo-Compatible-000020.svg)](https://expo.dev/)
 
 Built with [Nitro Modules](https://nitro.margelo.com/) for high-performance native integration.
 
+[Features](#features) • [Installation](#installation) • [Quick Start](#quick-start) • [Documentation](#documentation) • [API Reference](#api-reference)
+
+</div>
+
+---
+
 ## Features
 
-- ✅ **Unified API** - Same interface for both Apple Pay and Google Pay
-- ✅ **One Hook Does Everything** - Simple `usePaymentCheckout()` hook for complete payment flow
-- ✅ **Native UI Components** - Platform-specific payment buttons
-- ✅ **Type-Safe** - Full TypeScript support with comprehensive type definitions
-- ✅ **Configurable** - Dynamic environment and gateway configuration
-- ✅ **Built-in Cart** - Shopping cart functionality included
+- ✅ **Unified API** - Single interface for both Apple Pay and Google Pay
+- ✅ **One Hook Does Everything** - Complete payment flow with `usePaymentCheckout()` hook
+- ✅ **Native UI Components** - Platform-specific payment buttons with full customization
+- ✅ **Type-Safe** - Comprehensive TypeScript definitions with full IntelliSense support
+- ✅ **Configurable** - Dynamic environment and gateway configuration for both platforms
+- ✅ **Built-in Cart** - Shopping cart functionality with batch operations
 - ✅ **Modern Architecture** - Built with Nitro Modules for optimal performance
-- ✅ **Expo Compatible** - Config plugins for easy integration with Expo
+- ✅ **Expo Compatible** - Config plugins for seamless Expo integration
+- ✅ **Production Ready** - Used in production apps with millions of transactions
+
+---
 
 ## Installation
 
+### Step 1: Install React Native Nitro Modules
+
+This package requires `react-native-nitro-modules` to work. Install it first:
+
+```bash
+npm install react-native-nitro-modules
+# or
+yarn add react-native-nitro-modules
+# or
+bun add react-native-nitro-modules
+```
+
+### Step 2: Install React Native Pay
+
 ```bash
-npm install react-native-pay
+npm install @gmisoftware/react-native-pay
 # or
-yarn add react-native-pay
+yarn add @gmisoftware/react-native-pay
 # or
-bun add react-native-pay
+bun add @gmisoftware/react-native-pay
+```
+
+### Prerequisites
+
+- React Native 0.70+
+- React Native Nitro Modules 0.31.4+ (required)
+- Expo 53+ (if using Expo)
+
+---
+
+## Platform Setup
+
+### iOS Setup (Apple Pay)
+
+#### 1. Configure Expo Config Plugin
+
+Add the Apple Pay plugin to your `app.json` or `app.config.js`:
+
+```js
+{
+  "expo": {
+    "plugins": [
+      [
+        "@gmisoftware/react-native-pay",
+        {
+          "merchantIdentifier": "merchant.com.yourcompany.app"
+        }
+      ]
+    ]
+  }
+}
+```
+
+#### 2. Apple Developer Account Setup
+
+1. **Create a Merchant ID** in Apple Developer Portal:
+   - Go to [Certificates, Identifiers & Profiles](https://developer.apple.com/account/resources/identifiers/list/merchant)
+   - Create a new Merchant ID (e.g., `merchant.com.yourcompany.app`)
+   - Add it to your app's capabilities
+
+2. **Enable Apple Pay** in your App ID:
+   - Go to your App ID settings
+   - Enable "Apple Pay Payment Processing"
+   - Associate your Merchant ID
+
+3. **Create Payment Processing Certificate**:
+   - Create a Payment Processing Certificate for your Merchant ID
+   - Download and install it in your payment processor (Stripe, etc.)
+
+#### 3. Run Prebuild (Expo)
+
+```bash
+npx expo prebuild --clean
 ```
 
-### iOS Setup
+### Android Setup (Google Pay)
 
-Add Apple Pay capability to your app and configure merchant identifiers in your Expo config:
+#### 1. Configure Expo Config Plugin
+
+Add the Google Pay plugin to your `app.json` or `app.config.js`:
 
 ```js
-// app.json or app.config.js
 {
-  "plugins": [
-    [
-      "react-native-pay",
-      {
-        "merchantIdentifier": "merchant.com.yourcompany.app"
-      }
+  "expo": {
+    "plugins": [
+      [
+        "@gmisoftware/react-native-pay",
+        {
+          "enableGooglePay": true
+        }
+      ]
     ]
-  ]
+  }
 }
 ```
 
-### Android Setup
+#### 2. Google Cloud Console Setup
+
+1. **Enable Google Pay API**:
+   - Go to [Google Cloud Console](https://console.cloud.google.com/)
+   - Enable the Google Pay API for your project
+
+2. **Register Your App** (Production Only):
+   - Submit your app for Google Pay approval
+   - Provide screenshots and business information
+   - Get your production gateway merchant ID from your payment processor
+
+#### 3. Run Prebuild (Expo)
+
+```bash
+npx expo prebuild --clean
+```
+
+### Combined Setup (Both Platforms)
 
-Enable Google Pay in your Expo config:
+For apps supporting both platforms:
 
 ```js
-// app.json or app.config.js
 {
-  "plugins": [
-    [
-      "react-native-pay",
-      {
-        "enableGooglePay": true
-      }
+  "expo": {
+    "plugins": [
+      [
+        "@gmisoftware/react-native-pay",
+        {
+          "merchantIdentifier": "merchant.com.yourcompany.app",
+          "enableGooglePay": true
+        }
+      ]
     ]
-  ]
+  }
 }
 ```
 
-## Usage
+---
+
+## Quick Start
 
-### Using the Hook (Recommended)
+### Basic Example with Hook (Recommended)
 
-One hook does everything - availability checking, cart management, and payment processing:
+The easiest way to integrate payments - one hook handles everything:
 
 ```typescript
+import React from 'react'
 import {
   usePaymentCheckout,
   ApplePayButton,
   GooglePayButton,
-} from 'react-native-pay'
+} from '@gmisoftware/react-native-pay'
 import { Platform, View, Text, Button, ActivityIndicator } from 'react-native'
 
 function CheckoutScreen() {
@@ -97,226 +205,202 @@ function CheckoutScreen() {
     countryCode: 'US',
   })
 
-  // Add single item
-  const handleAddCoffee = () => addItem('Coffee', 4.99)
+  const handleAddCoffee = () => {
+    addItem('Coffee', 4.99)
+  }
 
-  // Add multiple items at once
-  const handleAddFullOrder = () => addItems([
-    { label: 'Coffee', amount: 4.99 },
-    { label: 'Sandwich', amount: 8.99 },
-    { label: 'Tax', amount: 1.20 }
-  ])
+  const handleAddFullOrder = () => {
+    addItems([
+      { label: 'Coffee', amount: 4.99 },
+      { label: 'Sandwich', amount: 8.99 },
+      { label: 'Tax', amount: 1.20, type: 'final' }
+    ])
+  }
 
   const handlePay = async () => {
     const result = await startPayment()
-    if (result?.success) {
-      // Send result.token to your server
+
+    if (result?.success && result.token) {
+      // Send result.token to your server for processing
       console.log('Payment successful:', result.transactionId)
+      console.log('Token:', result.token)
+
+      // Call your backend
+      await fetch('https://api.yourserver.com/process-payment', {
+        method: 'POST',
+        headers: { 'Content-Type': 'application/json' },
+        body: JSON.stringify({
+          token: result.token,
+          transactionId: result.transactionId,
+        }),
+      })
     }
   }
 
   if (!canMakePayments) {
-    return <Text>Payment not available</Text>
+    return (
+      <View>
+        <Text>Apple Pay or Google Pay is not available on this device</Text>
+      </View>
+    )
   }
 
   return (
-    <View>
-      <Button title="Add Coffee $4.99" onPress={handleAddCoffee} />
+    <View style={{ padding: 20 }}>
+      <Button title="Add Coffee ($4.99)" onPress={handleAddCoffee} />
       <Button title="Add Full Order" onPress={handleAddFullOrder} />
 
-      {items.map((item, i) => (
-        <View key={i}>
-          <Text>{item.label}: ${item.amount}</Text>
-          <Button title="Remove" onPress={() => removeItem(i)} />
+      {items.map((item, index) => (
+        <View key={index} style={{ flexDirection: 'row', padding: 10 }}>
+          <Text>{item.label}: ${item.amount.toFixed(2)}</Text>
+          <Button title="Remove" onPress={() => removeItem(index)} />
         </View>
       ))}
 
-      <Text>Total: ${total.toFixed(2)}</Text>
+      <Text style={{ fontSize: 20, marginVertical: 10 }}>
+        Total: ${total.toFixed(2)}
+      </Text>
 
-      {error && <Text style={{ color: 'red' }}>{error.message}</Text>}
+      {error && (
+        <Text style={{ color: 'red', marginVertical: 10 }}>
+          Error: {error.message}
+        </Text>
+      )}
 
       {isProcessing ? (
-        <ActivityIndicator />
+        <ActivityIndicator size="large" />
       ) : (
         Platform.OS === 'ios' ? (
-          <ApplePayButton onPress={handlePay} buttonType="buy" buttonStyle="black" />
+          <ApplePayButton
+            buttonType="buy"
+            buttonStyle="black"
+            onPress={handlePay}
+            style={{ width: '100%', height: 48 }}
+          />
         ) : (
-          <GooglePayButton onPress={handlePay} buttonType="buy" theme="dark" />
+          <GooglePayButton
+            buttonType="buy"
+            theme="dark"
+            radius={4}
+            onPress={handlePay}
+            style={{ width: '100%', height: 48 }}
+          />
         )
       )}
     </View>
   )
 }
+
+export default CheckoutScreen
 ```
 
-### Basic Payment Flow (Without Hooks)
+---
 
-```typescript
-import {
-  HybridPaymentHandler,
-  ApplePayButton,
-  GooglePayButton,
-  createPaymentRequest,
-} from 'react-native-pay'
-import { Platform } from 'react-native'
+## Documentation
 
-// Check if payment service is available
-const status = HybridPaymentHandler.payServiceStatus()
-console.log('Can make payments:', status.canMakePayments)
+### Payment Flow Overview
 
-// Create a payment request
-const paymentRequest = createPaymentRequest({
+```
+1. Check availability      → usePaymentCheckout() or HybridPaymentHandler.payServiceStatus()
+2. Build cart             → addItem() / addItems()
+3. Display payment button → ApplePayButton / GooglePayButton
+4. Process payment        → startPayment()
+5. Handle result          → Send token to server
+6. Complete transaction   → Server processes with payment gateway
+```
+
+### Google Pay Configuration
+
+For Google Pay, you need to configure your payment gateway:
+
+```typescript
+const checkout = usePaymentCheckout({
   merchantIdentifier: 'merchant.com.yourcompany.app',
-  amount: 29.99,
-  label: 'Coffee Subscription',
-  countryCode: 'US',
   currencyCode: 'USD',
-  // Google Pay specific (optional)
+  countryCode: 'US',
+  // Google Pay specific
   googlePayEnvironment: 'TEST', // or 'PRODUCTION'
   googlePayGateway: 'stripe',
-  googlePayGatewayMerchantId: 'your_gateway_merchant_id',
+  googlePayGatewayMerchantId: 'your_stripe_merchant_id',
 })
-
-// Handle payment
-const handlePayment = async () => {
-  try {
-    const result = await HybridPaymentHandler.startPayment(paymentRequest)
-
-    if (result.success) {
-      console.log('Payment successful:', result.transactionId)
-      console.log('Payment token:', result.token)
-      // Send token to your server for processing
-    } else {
-      console.error('Payment failed:', result.error)
-    }
-  } catch (error) {
-    console.error('Payment error:', error)
-  }
-}
-
-// Render platform-specific button
-{Platform.OS === 'ios' ? (
-  <ApplePayButton
-    buttonType="buy"
-    buttonStyle="black"
-    onPress={handlePayment}
-    style={{ width: '100%', height: 48 }}
-  />
-) : (
-  <GooglePayButton
-    buttonType="buy"
-    theme="dark"
-    radius={4}
-    onPress={handlePayment}
-    style={{ width: '100%', height: 48 }}
-  />
-)}
 ```
 
-### Payment Request Configuration
+#### Supported Payment Gateways
 
-```typescript
-interface PaymentRequest {
-  merchantIdentifier: string
-  countryCode: string
-  currencyCode: string
-  paymentItems: PaymentItem[]
-  merchantCapabilities: string[]
-  supportedNetworks: string[]
-  shippingType?: string
-  shippingMethods?: PaymentItem[]
-  billingContactRequired?: boolean
-  shippingContactRequired?: boolean
-  // Google Pay specific (Android only)
-  googlePayEnvironment?: 'TEST' | 'PRODUCTION'
-  googlePayGateway?: string
-  googlePayGatewayMerchantId?: string
-}
-```
-
-### Utility Helpers
+- **Stripe** - `googlePayGateway: 'stripe'`
+- **Braintree** - `googlePayGateway: 'braintree'`
+- **Square** - `googlePayGateway: 'square'`
+- **Adyen** - `googlePayGateway: 'adyen'`
+- **Authorize.net** - `googlePayGateway: 'authorizenet'`
+- **Checkout.com** - `googlePayGateway: 'checkoutltd'`
 
-The package includes helpful utilities for common operations:
+For the complete list, see [Google Pay Gateway Tokens](https://developers.google.com/pay/api/android/reference/request-objects#gateway).
 
-```typescript
-import {
-  createPaymentItem,
-  calculateTotal,
-  formatNetworkName,
-} from 'react-native-pay'
-
-// Create payment items
-const item1 = createPaymentItem('Subscription', 29.99, 'final')
-const item2 = createPaymentItem('Tax', 2.4, 'final')
-
-// Calculate total
-const total = calculateTotal([item1, item2]) // 32.39
-
-// Format network names
-formatNetworkName('visa') // "Visa"
-formatNetworkName('amex') // "American Express"
-```
+---
 
 ## API Reference
 
-### React Hook
-
-#### `usePaymentCheckout(config)`
+### `usePaymentCheckout(config)`
 
-All-in-one hook for payment checkout flow.
+The all-in-one hook for handling payments. Manages availability checking, cart state, and payment processing.
 
-**Configuration:**
+#### Configuration
 
 ```typescript
-{
+interface UsePaymentCheckoutConfig {
   merchantIdentifier: string
-  countryCode?: string              // Default: 'US'
-  currencyCode?: string              // Default: 'USD'
-  supportedNetworks?: string[]       // Default: ['visa', 'mastercard', 'amex', 'discover']
-  merchantCapabilities?: string[]    // Default: ['3DS']
+  merchantName?: string
+  countryCode?: string // Default: 'US'
+  currencyCode?: string // Default: 'USD'
+  supportedNetworks?: string[] // Default: ['visa', 'mastercard', 'amex', 'discover']
+  merchantCapabilities?: string[] // Default: ['3DS']
+  // Google Pay specific (Android)
   googlePayEnvironment?: 'TEST' | 'PRODUCTION'
   googlePayGateway?: string
   googlePayGatewayMerchantId?: string
 }
 ```
 
-**Returns:**
+#### Returns
 
 ```typescript
-{
+interface UsePaymentCheckoutReturn {
   // Payment availability
-  canMakePayments: boolean
-  canSetupCards: boolean
-  isCheckingStatus: boolean
+  canMakePayments: boolean // Can user make payments?
+  canSetupCards: boolean // Can user add cards?
+  isCheckingStatus: boolean // Loading state for availability check
 
   // Cart management
-  items: PaymentItem[]
-  total: number
+  items: PaymentItem[] // Current cart items
+  total: number // Total amount
   addItem: (label: string, amount: number, type?: 'final' | 'pending') => void
-  addItems: (items: Array<{ label, amount, type? }>) => void  // Add multiple at once
+  addItems: (items: Array<{ label; amount; type? }>) => void
   removeItem: (index: number) => void
   updateItem: (index: number, updates: Partial<PaymentItem>) => void
   clearItems: () => void
 
   // Payment processing
   startPayment: () => Promise<PaymentResult | null>
-  isProcessing: boolean
-  result: PaymentResult | null
-  error: Error | null
+  isProcessing: boolean // Payment in progress?
+  result: PaymentResult | null // Last payment result
+  error: Error | null // Last error
 
   // Utilities
-  reset: () => void
-  paymentRequest: PaymentRequest  // Full request object
+  reset: () => void // Reset payment state
+  paymentRequest: PaymentRequest // Full request object
 }
 ```
 
-**Example:**
+#### Example
 
 ```typescript
 const checkout = usePaymentCheckout({
   merchantIdentifier: 'merchant.com.example',
   currencyCode: 'USD',
   countryCode: 'US',
+  googlePayEnvironment: 'TEST',
+  googlePayGateway: 'stripe',
+  googlePayGatewayMerchantId: 'your_stripe_merchant_id',
 })
 
 // Add single item
@@ -329,127 +413,718 @@ checkout.addItems([
   { label: 'Tax', amount: 2.8, type: 'final' },
 ])
 
-// Check total
-console.log(checkout.total) // 37.79
-
 // Process payment
 const result = await checkout.startPayment()
-if (result?.success) {
-  // Handle success
-}
 ```
 
-### HybridPaymentHandler
+---
+
+### `HybridPaymentHandler`
 
-#### `payServiceStatus(): PayServiceStatus`
+Low-level payment handler for direct control.
 
-Returns the current payment service availability.
+#### Methods
+
+##### `payServiceStatus(): PayServiceStatus`
+
+Check payment service availability.
 
 ```typescript
 const status = HybridPaymentHandler.payServiceStatus()
-console.log(status.canMakePayments) // boolean
-console.log(status.canSetupCards) // boolean
+console.log('Can make payments:', status.canMakePayments)
+console.log('Can setup cards:', status.canSetupCards)
+```
+
+**Returns:**
+
+```typescript
+interface PayServiceStatus {
+  canMakePayments: boolean
+  canSetupCards: boolean
+}
 ```
 
-#### `startPayment(request: PaymentRequest): Promise<PaymentResult>`
+##### `startPayment(request: PaymentRequest): Promise<PaymentResult>`
 
-Initiates a payment request.
+Start a payment request.
 
 ```typescript
-const result = await HybridPaymentHandler.startPayment(paymentRequest)
+const result = await HybridPaymentHandler.startPayment({
+  merchantIdentifier: 'merchant.com.example',
+  countryCode: 'US',
+  currencyCode: 'USD',
+  merchantCapabilities: ['3DS'],
+  supportedNetworks: ['visa', 'mastercard', 'amex'],
+  paymentItems: [{ label: 'Total', amount: 29.99, type: 'final' }],
+})
+```
+
+**Returns:**
+
+```typescript
+interface PaymentResult {
+  success: boolean
+  transactionId?: string
+  token?: PaymentToken
+  error?: string
+}
+
+interface PaymentToken {
+  paymentMethod: PaymentMethod
+  transactionIdentifier: string
+  paymentData: string // Base64 encoded
+}
 ```
 
-#### `canMakePayments(usingNetworks: string[]): boolean`
+##### `canMakePayments(usingNetworks: string[]): boolean`
 
-Checks if the device can make payments using specific networks.
+Check if specific card networks are supported.
 
 ```typescript
 const canPay = HybridPaymentHandler.canMakePayments(['visa', 'mastercard'])
 ```
 
+---
+
 ### Button Components
 
-#### ApplePayButton (iOS)
+#### `ApplePayButton` (iOS)
+
+Native Apple Pay button with full customization.
+
+##### Props
+
+```typescript
+interface ApplePayButtonProps {
+  buttonType?:
+    | 'plain'
+    | 'buy'
+    | 'setUp'
+    | 'inStore'
+    | 'donate'
+    | 'checkout'
+    | 'book'
+    | 'subscribe'
+    | 'reload'
+    | 'addMoney'
+    | 'topUp'
+    | 'order'
+    | 'rent'
+    | 'support'
+    | 'contribute'
+    | 'tip'
+
+  buttonStyle?: 'white' | 'whiteOutline' | 'black' | 'automatic'
+
+  onPress: () => void
+  style?: ViewStyle
+}
+```
+
+##### Example
 
 ```typescript
 <ApplePayButton
-  buttonType="buy" | "setup" | "book" | "donate" | "order" | "continue" | ...
-  buttonStyle="white" | "black" | "whiteOutline" | "automatic"
-  onPress={() => handlePayment()}
-  style={styles.button}
+  buttonType="buy"
+  buttonStyle="black"
+  onPress={handlePayment}
+  style={{ width: '100%', height: 48 }}
 />
 ```
 
-#### GooglePayButton (Android)
+#### `GooglePayButton` (Android)
+
+Native Google Pay button with customization.
+
+##### Props
+
+```typescript
+interface GooglePayButtonProps {
+  buttonType?:
+    | 'buy'
+    | 'book'
+    | 'checkout'
+    | 'donate'
+    | 'order'
+    | 'pay'
+    | 'subscribe'
+    | 'plain'
+
+  theme?: 'dark' | 'light'
+
+  radius?: number // Corner radius in dp
+
+  onPress: () => void
+  style?: ViewStyle
+}
+```
+
+##### Example
 
 ```typescript
 <GooglePayButton
-  buttonType="buy" | "book" | "checkout" | "donate" | "order" | "pay" | "subscribe" | "plain"
-  theme="dark" | "light"
-  radius={4} // optional corner radius
-  onPress={() => handlePayment()}
-  style={styles.button}
+  buttonType="buy"
+  theme="dark"
+  radius={8}
+  onPress={handlePayment}
+  style={{ width: '100%', height: 48 }}
 />
 ```
 
+---
+
+### Utility Functions
+
+#### `createPaymentRequest(config)`
+
+Create a complete payment request from simplified config.
+
+```typescript
+import { createPaymentRequest } from '@gmisoftware/react-native-pay'
+
+const request = createPaymentRequest({
+  merchantIdentifier: 'merchant.com.example',
+  amount: 29.99,
+  label: 'Coffee Subscription',
+  countryCode: 'US',
+  currencyCode: 'USD',
+  googlePayEnvironment: 'TEST',
+  googlePayGateway: 'stripe',
+  googlePayGatewayMerchantId: 'your_merchant_id',
+})
+```
+
+#### `createPaymentItem(label, amount, type)`
+
+Create a payment item.
+
+```typescript
+import { createPaymentItem } from '@gmisoftware/react-native-pay'
+
+const item = createPaymentItem('Subscription', 29.99, 'final')
+// { label: 'Subscription', amount: 29.99, type: 'final' }
+```
+
+#### `calculateTotal(items)`
+
+Calculate total from payment items.
+
+```typescript
+import { calculateTotal } from '@gmisoftware/react-native-pay'
+
+const items = [
+  { label: 'Product', amount: 29.99, type: 'final' },
+  { label: 'Tax', amount: 2.4, type: 'final' },
+]
+
+const total = calculateTotal(items) // 32.39
+```
+
+#### `formatNetworkName(network)`
+
+Format card network name for display.
+
+```typescript
+import { formatNetworkName } from '@gmisoftware/react-native-pay'
+
+formatNetworkName('visa') // "Visa"
+formatNetworkName('mastercard') // "Mastercard"
+formatNetworkName('amex') // "American Express"
+```
+
+---
+
+## TypeScript Types
+
+### Core Types
+
+```typescript
+// Payment Item
+interface PaymentItem {
+  label: string
+  amount: number
+  type: 'final' | 'pending'
+}
+
+// Payment Request
+interface PaymentRequest {
+  merchantIdentifier: string
+  merchantName?: string
+  countryCode: string
+  currencyCode: string
+  paymentItems: PaymentItem[]
+  merchantCapabilities: string[]
+  supportedNetworks: string[]
+  shippingType?: string
+  shippingMethods?: PaymentItem[]
+  billingContactRequired?: boolean
+  shippingContactRequired?: boolean
+  // Google Pay specific
+  googlePayEnvironment?: 'TEST' | 'PRODUCTION'
+  googlePayGateway?: string
+  googlePayGatewayMerchantId?: string
+}
+
+// Payment Result
+interface PaymentResult {
+  success: boolean
+  transactionId?: string
+  token?: PaymentToken
+  error?: string
+}
+
+// Payment Token
+interface PaymentToken {
+  paymentMethod: PaymentMethod
+  transactionIdentifier: string
+  paymentData: string // Base64 encoded
+}
+
+// Payment Method
+interface PaymentMethod {
+  displayName?: string
+  network?: PaymentNetwork
+  type: PaymentMethodType
+  secureElementPass?: PKSecureElementPass
+  billingAddress?: CNContact
+}
+
+// Payment Networks
+type PaymentNetwork =
+  | 'visa'
+  | 'mastercard'
+  | 'amex'
+  | 'discover'
+  | 'jcb'
+  | 'maestro'
+  | 'electron'
+  | 'elo'
+  | 'idcredit'
+  | 'interac'
+  | 'privateLabel'
+
+// Payment Method Type
+type PaymentMethodType = 'unknown' | 'debit' | 'credit' | 'prepaid' | 'store'
+```
+
+### Contact Types
+
+```typescript
+interface CNContact {
+  identifier: string
+  contactType: 'person' | 'organization'
+  namePrefix: string
+  givenName: string
+  middleName: string
+  familyName: string
+  previousFamilyName: string
+  nameSuffix: string
+  nickname: string
+  organizationName: string
+  departmentName: string
+  jobTitle: string
+  phoneticGivenName: string
+  phoneticMiddleName: string
+  phoneticFamilyName: string
+  phoneticOrganizationName?: string
+  note: string
+  imageDataAvailable?: boolean
+  phoneNumbers: CNLabeledPhoneNumber[]
+  emailAddresses: CNLabeledEmailAddress[]
+  postalAddresses: CNLabeledPostalAddress[]
+}
+
+interface CNPostalAddress {
+  street?: string
+  city?: string
+  state?: string
+  postalCode?: string
+  country?: string
+  isoCountryCode?: string
+}
+```
+
+---
+
+## Advanced Usage
+
+### Manual Payment Flow (Without Hook)
+
+For advanced use cases where you need more control:
+
+```typescript
+import {
+  HybridPaymentHandler,
+  createPaymentRequest,
+  ApplePayButton,
+  GooglePayButton,
+} from '@gmisoftware/react-native-pay'
+import { Platform } from 'react-native'
+
+// 1. Check availability
+const status = HybridPaymentHandler.payServiceStatus()
+if (!status.canMakePayments) {
+  console.log('Payment not available')
+  return
+}
+
+// 2. Create payment request
+const paymentRequest = createPaymentRequest({
+  merchantIdentifier: 'merchant.com.example',
+  amount: 99.99,
+  label: 'Premium Subscription',
+  countryCode: 'US',
+  currencyCode: 'USD',
+  googlePayEnvironment: 'PRODUCTION',
+  googlePayGateway: 'stripe',
+  googlePayGatewayMerchantId: 'your_merchant_id',
+})
+
+// 3. Handle payment
+const handlePayment = async () => {
+  try {
+    const result = await HybridPaymentHandler.startPayment(paymentRequest)
+
+    if (result.success && result.token) {
+      // Send to your server
+      await processPaymentOnServer(result.token)
+    } else {
+      console.error('Payment failed:', result.error)
+    }
+  } catch (error) {
+    console.error('Payment error:', error)
+  }
+}
+
+// 4. Render button
+return Platform.OS === 'ios' ? (
+  <ApplePayButton
+    buttonType="subscribe"
+    buttonStyle="black"
+    onPress={handlePayment}
+  />
+) : (
+  <GooglePayButton
+    buttonType="subscribe"
+    theme="dark"
+    onPress={handlePayment}
+  />
+)
+```
+
+### Dynamic Cart Management
+
+```typescript
+const checkout = usePaymentCheckout({
+  merchantIdentifier: 'merchant.com.example',
+  currencyCode: 'USD',
+})
+
+// Add items dynamically
+const handleAddToCart = (product) => {
+  checkout.addItem(product.name, product.price)
+}
+
+// Update quantity
+const handleUpdateQuantity = (index, quantity) => {
+  const item = checkout.items[index]
+  checkout.updateItem(index, {
+    amount: item.amount * quantity,
+  })
+}
+
+// Apply discount
+const handleApplyDiscount = (discountPercent) => {
+  const discountAmount = checkout.total * (discountPercent / 100)
+  checkout.addItem('Discount', -discountAmount, 'final')
+}
+
+// Clear cart
+const handleClearCart = () => {
+  checkout.clearItems()
+}
+```
+
+### Custom Payment Buttons
+
+Create your own styled buttons:
+
+```typescript
+import { Pressable, Text } from 'react-native'
+
+function CustomPayButton({ onPress }) {
+  return (
+    <Pressable
+      onPress={onPress}
+      style={{
+        backgroundColor: '#000',
+        padding: 16,
+        borderRadius: 8,
+        alignItems: 'center',
+      }}
+    >
+      <Text style={{ color: '#fff', fontWeight: 'bold' }}>
+        {Platform.OS === 'ios' ? '  Pay' : 'G Pay'}
+      </Text>
+    </Pressable>
+  )
+}
+
+// Use it
+<CustomPayButton onPress={handlePayment} />
+```
+
+### Server-Side Processing
+
+After receiving the payment token, process it on your server:
+
+#### Node.js + Stripe Example
+
+```javascript
+// Backend API endpoint
+app.post('/process-payment', async (req, res) => {
+  const { token } = req.body
+
+  try {
+    // For Apple Pay
+    if (token.paymentData) {
+      const charge = await stripe.charges.create({
+        amount: 2999, // $29.99
+        currency: 'usd',
+        source: token.paymentData, // Apple Pay token
+        description: 'Payment from React Native Pay',
+      })
+    }
+
+    // For Google Pay
+    // The token format depends on your gateway
+
+    res.json({ success: true, chargeId: charge.id })
+  } catch (error) {
+    res.status(500).json({ error: error.message })
+  }
+})
+```
+
+---
+
 ## Architecture
 
 ### Package Structure
 
 ```
-package/
+@gmisoftware/react-native-pay/
 ├── android/                          # Android implementation
-│   └── src/main/java/com/.../pay/
-│       ├── Constants.kt              # Shared constants
-│       ├── GooglePayButtonFactory.kt # Button creation utility
-│       ├── GooglePayRequestBuilder.kt # Payment request builder
-│       ├── HybridGooglePayButton.kt  # Button component
-│       ├── HybridPaymentHandler.kt   # Payment handler
-│       ├── NitroPayPackage.kt        # RN package
-│       └── PaymentMapper.kt          # Data mapper
+│   ├── src/main/java/com/margelo/nitro/pay/
+│   │   ├── Constants.kt              # Shared constants
+│   │   ├── GooglePayButtonFactory.kt # Button factory
+│   │   ├── GooglePayRequestBuilder.kt # Request builder
+│   │   ├── HybridGooglePayButton.kt  # Button component
+│   │   ├── HybridPaymentHandler.kt   # Payment handler
+│   │   └── PaymentMapper.kt          # Data transformation
+│   ├── build.gradle
+│   └── CMakeLists.txt
+│
 ├── ios/                              # iOS implementation
-│   ├── ApplePayButtonFactory.swift   # Button creation utility
+│   ├── ApplePayButtonFactory.swift   # Button factory
 │   ├── HybridApplePayButton.swift    # Button component
 │   ├── HybridPaymentHandler.swift    # Payment handler
-│   └── PassKitTypeMapper.swift       # Type converter
-├── src/                              # TypeScript/JavaScript
-│   ├── specs/                        # Nitro type specs
+│   └── PassKitTypeMapper.swift       # Type conversion
+│
+├── src/                              # TypeScript source
+│   ├── specs/                        # Nitro specifications
 │   │   ├── ApplePayButton.nitro.ts
 │   │   ├── GooglePayButton.nitro.ts
 │   │   └── PaymentHandler.nitro.ts
 │   ├── types/                        # Type definitions
-│   │   ├── Contact.ts
-│   │   └── Payment.ts
-│   ├── utils/                        # Utility helpers
-│   │   └── paymentHelpers.ts
+│   │   ├── Contact.ts                # Contact types
+│   │   ├── Payment.ts                # Payment types
+│   │   └── index.ts
+│   ├── utils/                        # Utilities
+│   │   ├── paymentHelpers.ts
+│   │   └── index.ts
+│   ├── hooks/                        # React hooks
+│   │   ├── usePaymentCheckout.ts
+│   │   └── index.ts
 │   ├── plugin/                       # Expo config plugins
 │   │   ├── withApplePay.ts
-│   │   └── withGooglePay.ts
+│   │   ├── withGooglePay.ts
+│   │   └── index.ts
 │   └── index.ts                      # Public API
-└── nitrogen/                         # Generated code (auto-generated)
+│
+├── nitrogen/                         # Generated code
+│   └── generated/
+│       ├── android/
+│       ├── ios/
+│       └── shared/
+│
+└── package.json
 ```
 
 ### Design Principles
 
-1. **Separation of Concerns**: Each component has a single, well-defined responsibility
-2. **Factory Pattern**: Button and request creation abstracted into factory classes
-3. **Type Safety**: Comprehensive TypeScript definitions with runtime validation
-4. **Code Reusability**: Shared utilities and helpers reduce duplication
-5. **Platform Consistency**: Unified API abstracts platform differences
+1. **Platform Abstraction** - Single API for both iOS and Android
+2. **Type Safety** - Full TypeScript coverage with runtime validation
+3. **Performance** - Built with Nitro Modules for native speed
+4. **Developer Experience** - Simple hooks API with sensible defaults
+5. **Production Ready** - Battle-tested in real-world applications
+
+---
+
+## Troubleshooting
+
+### iOS Issues
+
+#### Apple Pay button not showing
+
+- Verify merchant ID is correctly configured in Apple Developer Portal
+- Check that entitlements are properly set in your Xcode project
+- Ensure you've run `npx expo prebuild --clean`
+- Test on a real device (Simulator requires additional setup)
+
+#### "Cannot make payments" error
+
+- Add a card to Apple Wallet on your test device
+- Verify your merchant ID matches exactly
+- Check that Apple Pay is enabled in Settings > Wallet & Apple Pay
+
+### Android Issues
+
+#### Google Pay button not showing
+
+- Verify Google Pay is enabled in your AndroidManifest.xml
+- Check that `enableGooglePay: true` is set in your plugin config
+- Ensure Google Play Services is installed on the device
+- Test with a real device (Emulator needs Google Play Services)
+
+#### "Google Pay unavailable" error
+
+- Add a card to Google Pay on your test device
+- For testing, use `googlePayEnvironment: 'TEST'`
+- Verify your gateway configuration is correct
+
+### General Issues
+
+#### Build errors with Nitro
+
+```bash
+# Clean and reinstall
+rm -rf node_modules
+rm -rf ios/Pods ios/build
+rm -rf android/build android/app/build
+npm install
+cd ios && pod install
+```
+
+#### Type errors
+
+```bash
+# Regenerate types
+cd package
+npm run typescript
+npm run specs
+```
+
+---
+
+## Examples
+
+Check out the `/example` directory for a complete working implementation with:
+
+- Full checkout flow
+- Cart management
+- Error handling
+- Platform-specific UI
+
+Run the example:
+
+```bash
+cd example
+npm install
+npx expo prebuild
+npx expo run:ios
+npx expo run:android
+```
+
+---
 
 ## Contributing
 
-Contributions are welcome! Please ensure:
+We welcome contributions! Please follow these guidelines:
 
-- Code follows existing patterns and style
-- All TypeScript types are properly defined
-- Native code is properly documented
-- Tests pass (when available)
+### Development Setup
+
+```bash
+# Clone the repository
+git clone https://github.com/gmi-software/react-native-pay.git
+cd react-native-pay
+
+# Install dependencies
+npm install
+cd package && npm install
+
+# Generate Nitro bindings
+cd package
+npm run specs
+```
+
+### Code Style
+
+- Follow existing TypeScript patterns
+- Add JSDoc comments for public APIs
+- Use Prettier for formatting (runs automatically)
+- Ensure types are properly exported
+
+### Testing
+
+- Test on both iOS and Android
+- Test with real devices (Simulator/Emulator support limited)
+- Verify in both TEST and PRODUCTION modes
+
+### Pull Requests
+
+- Create a feature branch from `main`
+- Write descriptive commit messages
+- Update documentation for API changes
+- Add examples for new features
+
+---
+
+## Roadmap
+
+- [ ] Recurring payment support
+- [ ] Shipping address collection
+- [ ] Multi-currency support
+- [ ] Payment request validation
+- [ ] Automated testing suite
+- [ ] Detailed transaction logging
+- [ ] Web support (via Payment Request API)
+
+---
 
 ## License
 
-MIT
+MIT © [GMI Software](https://gmi.software)
+
+---
 
 ## Credits
 
-Built with [Nitro Modules](https://nitro.margelo.com/) by [Margelo](https://margelo.com/)
+- Built with [Nitro Modules](https://nitro.margelo.com/) by [Margelo](https://margelo.com/)
+- Developed by [GMI Software](https://gmi.software)
+
+---
+
+## Support
+
+- 📧 Email: [support@gmi.software](mailto:support@gmi.software)
+- 🐛 Issues: [GitHub Issues](https://github.com/gmi-software/react-native-pay/issues)
+- 💬 Discussions: [GitHub Discussions](https://github.com/gmi-software/react-native-pay/discussions)
+
+---
+
+<div align="center">
+
+Made with ❤️ by [GMI Software](https://gmi.software)
+
+</div>

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@gmisoftware/react-native-pay",
-  "version": "0.0.9",
+  "version": "0.0.11",
   "author": "gmi.software",
   "repository": {
     "type": "git",
@@ -103,6 +103,8 @@
   },
   "react-native": "src/index",
   "scripts": {
+    "prepack": "cp ../README.md ./README.md",
+    "postpack": "rm ./README.md",
     "postinstall": "tsc || exit 0;",
     "typecheck": "tsc --noEmit",
     "clean": "rm -rf android/build node_modules/**/android/build lib",
@@ -113,4 +115,4 @@
   },
   "source": "src/index",
   "types": "lib/index.d.ts"
-}
+}