npm package: @paygate/react-native
Description: PayGate React Native SDK - Accept Mobile Money payments in Ghana using WebView
Author: Ebenezer Sakyi
Latest version: 0.1.0

# @paygate/react-native

Official PayGate React Native SDK for accepting Mobile Money payments in Ghana using WebView.

## Installation

```bash
npm install @paygate/react-native react-native-webview
# or
yarn add @paygate/react-native react-native-webview
```

### iOS Setup

```bash
cd ios && pod install
```

### Android Setup

No additional setup required.

## Quick Start

### 1. Wrap your app with PayGateProvider and add PayGateAutoModal

```tsx
import { PayGateProvider, PayGateAutoModal } from '@paygate/react-native';

function App() {
  return (
    <PayGateProvider
      publicKey="pk_test_your_public_key"
      baseUrl="https://paygate.com"
    >
      <NavigationContainer>
        <AppNavigator />
      </NavigationContainer>
      {/* Add the auto modal at the root */}
      <PayGateAutoModal />
    </PayGateProvider>
  );
}
```

### 2. Create a checkout session on your server

```typescript
// Server-side (Node.js)
import PayGate from 'paygate';

const paygate = new PayGate('sk_test_your_secret_key');

const session = await paygate.checkoutSessions.create({
  amount: 100.00,
  currency: 'GHS',
  success_url: 'https://yoursite.com/success',
  cancel_url: 'https://yoursite.com/cancel',
});

// Return session.id to your mobile app
```

### 3. Use the usePayGate hook to trigger payments

```tsx
import { usePayGate } from '@paygate/react-native';
import { Button, Alert } from 'react-native';

function CheckoutScreen() {
  const { checkout, isVisible } = usePayGate();

  const handlePay = async () => {
    try {
      // Get session ID from your server
      const response = await fetch('https://your-api.com/create-session', {
        method: 'POST',
        body: JSON.stringify({ amount: 100 }),
      });
      const { sessionId } = await response.json();

      // Open the payment modal
      checkout({
        sessionId,
        onSuccess: (data) => {
          console.log('Payment successful!', data);
          Alert.alert('Success', 'Payment completed!');
          // Navigate to success screen or update UI
        },
        onCancel: () => {
          console.log('Payment cancelled');
        },
        onError: (error) => {
          console.error('Payment error:', error);
          Alert.alert('Error', error.message);
        },
      });
    } catch (error) {
      Alert.alert('Error', 'Failed to create checkout session');
    }
  };

  return (
    <Button
      title="Pay GHS 100.00"
      onPress={handlePay}
      disabled={isVisible}
    />
  );
}
```

## Components

### PayGateProvider

Wrap your application with `PayGateProvider` to enable PayGate functionality.

```tsx
<PayGateProvider
  publicKey="pk_test_xxx"
  baseUrl="https://paygate.com"
>
  {children}
</PayGateProvider>
```

### PayGateAutoModal

An auto-managed modal that responds to `checkout()` and `payWithLink()` calls.
Place at the root of your app.

```tsx
<PayGateAutoModal />
```

### PayGateModal

A manually controlled modal for more control.

```tsx
const [visible, setVisible] = useState(false);

<PayGateModal
  visible={visible}
  sessionId="cs_xxx"
  onSuccess={(data) => {
    console.log('Paid!', data);
    setVisible(false);
  }}
  onCancel={() => setVisible(false)}
  onClose={() => setVisible(false)}
  animationType="slide"
  showCloseButton={true}
/>
```

### PayGate (WebView Component)

Low-level WebView component for custom implementations.

```tsx
<PayGate
  sessionId="cs_xxx"
  onSuccess={(data) => console.log('Paid!', data)}
  onCancel={() => console.log('Cancelled')}
  onError={(error) => console.error(error)}
  onLoad={() => console.log('Loaded')}
  style={{ flex: 1 }}
  showLoader={true}
/>
```

## Hooks

### usePayGate

```tsx
const {
  checkout,     // (params: CheckoutParams) => void
  payWithLink,  // (params: PaymentLinkParams) => void
  close,        // () => void
  isVisible,    // boolean
  publicKey,    // string
  baseUrl,      // string
} = usePayGate();
```

## Payment Links

You can also accept payments using payment links:

```tsx
const { payWithLink } = usePayGate();

const handleDonate = () => {
  payWithLink({
    linkId: 'pl_xxx',
    amount: 50.00,  // For dynamic amount links
    email: 'customer@example.com',
    phone: '0241234567',
    onSuccess: (data) => {
      console.log('Donation successful!', data);
    },
    onCancel: () => {
      console.log('Donation cancelled');
    },
  });
};
```

## TypeScript

This package includes TypeScript definitions:

```typescript
import type {
  PayGateConfig,
  CheckoutParams,
  PaymentLinkParams,
  PaymentResult,
  PayGateError,
} from '@paygate/react-native';
```

## Test Mode

Use test mode keys (`pk_test_xxx`) during development. In test mode, you can simulate different payment outcomes without processing real transactions.

## Troubleshooting

### WebView not loading

Make sure you have installed and linked `react-native-webview`:

```bash
npm install react-native-webview
cd ios && pod install
```

### Modal not appearing

Ensure `PayGateAutoModal` is placed at the root level of your app, after `PayGateProvider`:

```tsx
<PayGateProvider publicKey="pk_test_xxx">
  <App />
  <PayGateAutoModal /> {/* Must be inside provider */}
</PayGateProvider>
```

## License

MIT