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

# @paygate/react

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

## Installation

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

## Quick Start

### 1. Wrap your app with PayGateProvider

```tsx
import { PayGateProvider } from '@paygate/react';

function App() {
  return (
    <PayGateProvider publicKey="pk_test_your_public_key">
      <YourApp />
    </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 frontend
```

### 3. Use PayGateButton or usePayGate hook

```tsx
import { PayGateButton } from '@paygate/react';

function Checkout({ sessionId }) {
  return (
    <PayGateButton
      sessionId={sessionId}
      onSuccess={(data) => {
        console.log('Payment successful!', data);
        // Redirect to success page or update UI
      }}
      onCancel={() => {
        console.log('Payment cancelled');
      }}
    >
      Pay GHS 100.00
    </PayGateButton>
  );
}
```

Or use the hook for more control:

```tsx
import { usePayGate } from '@paygate/react';

function CustomCheckout({ sessionId }) {
  const { openCheckout, isOpen, isLoading } = usePayGate();

  const handlePay = () => {
    openCheckout(sessionId, {
      onSuccess: (data) => {
        console.log('Payment successful!', data);
      },
      onCancel: () => {
        console.log('Payment cancelled');
      },
      onError: (error) => {
        console.error('Payment error:', error);
      },
    });
  };

  return (
    <button onClick={handlePay} disabled={isOpen || isLoading}>
      {isLoading ? 'Loading...' : 'Pay Now'}
    </button>
  );
}
```

## Components

### PayGateProvider

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

```tsx
<PayGateProvider
  publicKey="pk_test_xxx"
  baseUrl="https://paygate.com" // Optional, defaults to production
>
  {children}
</PayGateProvider>
```

### PayGateButton

A pre-styled button that opens the checkout popup.

```tsx
<PayGateButton
  sessionId="cs_xxx"           // Checkout session ID
  // OR
  paymentLinkId="pl_xxx"       // Payment link ID
  amount={50}                  // Amount for dynamic payment links

  onSuccess={(data) => {}}     // Called on successful payment
  onCancel={() => {}}          // Called when user cancels
  onError={(error) => {}}      // Called on error

  className="my-button"        // Custom class
  style={{ ... }}              // Custom styles
  disabled={false}             // Disable button

  popupOptions={{
    position: 'center',        // 'center' | 'right'
    showBackdrop: true,
    closeOnBackdropClick: true,
    zIndex: 9999,
  }}
>
  Pay Now
</PayGateButton>
```

### PayGateInline

Embed the checkout form directly in your page.

```tsx
<PayGateInline
  sessionId="cs_xxx"
  height="600px"
  onSuccess={(data) => {}}
  onCancel={() => {}}
  onError={(error) => {}}
  onLoad={() => {}}
/>
```

## Hooks

### usePayGate

Access PayGate SDK functionality programmatically.

```tsx
const {
  openCheckout,    // (sessionId, options) => void
  openPaymentLink, // (linkId, options) => void
  closePopup,      // () => void
  isOpen,          // boolean
  isLoading,       // boolean
  publicKey,       // string
} = usePayGate();
```

### useCheckoutSession

Fetch checkout session data.

```tsx
const {
  session,   // CheckoutSession | null
  isLoading, // boolean
  error,     // PayGateError | null
  refetch,   // () => Promise<void>
} = useCheckoutSession('cs_xxx');
```

## Payment Links

You can also use payment links for simpler integrations:

```tsx
<PayGateButton
  paymentLinkId="pl_xxx"
  amount={25.00}  // Optional: for dynamic amount links
  onSuccess={(data) => console.log('Paid!', data)}
>
  Donate GHS 25.00
</PayGateButton>
```

Or with the hook:

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

openPaymentLink('pl_xxx', {
  amount: 25.00,
  email: 'customer@example.com',
  phone: '0241234567',
  onSuccess: (data) => console.log('Paid!', data),
});
```

## TypeScript

This package includes TypeScript definitions. All types are exported:

```typescript
import type {
  PayGateConfig,
  CheckoutOptions,
  PaymentLinkOptions,
  PaymentResult,
  PayGateError,
  CheckoutSession,
  PaymentLink,
} from '@paygate/react';
```

## Test Mode

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

## License

MIT