# React Native

Accept payments in your React Native app. The SDK opens the ZevPay checkout page in a WebView modal and returns the result when payment completes.

## Installation

```bash
npm install @zevpay/react-native react-native-webview
```

For iOS:

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

Requires React Native 0.72+ and `react-native-webview` 13+.

## Quick start

```tsx
import { useState } from 'react';
import { Button } from 'react-native';
import { ZevPayCheckout } from '@zevpay/react-native';

function CheckoutScreen() {
  const [visible, setVisible] = useState(false);

  return (
    <>
      <Button title="Pay ₦5,000" onPress={() => setVisible(true)} />

      <ZevPayCheckout
        visible={visible}
        publicKey="pk_test_your_public_key"
        email="customer@example.com"
        amount={500000}
        onSuccess={(data) => {
          setVisible(false);
          console.log('Paid! Reference:', data.reference);
          // Verify payment on your server
        }}
        onCancel={() => setVisible(false)}
      />
    </>
  );
}
```

## Component API

### `<ZevPayCheckout>`

A modal component that renders the checkout page in a WebView.

```tsx
<ZevPayCheckout
  visible={true}
  publicKey="pk_test_xxx"
  email="customer@example.com"
  amount={500000}
  reference="ORDER-123"
  firstName="John"
  lastName="Doe"
  metadata={{ orderId: '123' }}
  paymentMethods={['bank_transfer', 'payid']}
  onSuccess={(data) => console.log(data.reference)}
  onCancel={() => setVisible(false)}
  onError={(error) => console.error(error)}
/>
```

### Props

| Prop | Type | Required | Description |
|------|------|----------|-------------|
| `visible` | `boolean` | Yes | Show/hide the modal |
| `publicKey` | `string` | Yes | Your public key (`pk_live_*` or `pk_test_*`) |
| `email` | `string` | Yes | Customer email |
| `amount` | `number` | Yes | Amount in kobo (₦1 = 100 kobo) |
| `currency` | `string` | No | Currency code (default: `NGN`) |
| `reference` | `string` | No | Your unique transaction reference |
| `firstName` | `string` | No | Customer first name |
| `lastName` | `string` | No | Customer last name |
| `metadata` | `object` | No | Additional metadata |
| `paymentMethods` | `string[]` | No | `bank_transfer`, `payid`, `card` |
| `onSuccess` | `function` | Yes | Called with `{ reference, params }` |
| `onCancel` | `function` | Yes | Called when user closes the modal |
| `onError` | `function` | No | Called on WebView errors |

## Hook API

### `useZevPayCheckout()`

A Promise-based hook for imperative checkout flow.

```tsx
import { ZevPayCheckout, useZevPayCheckout } from '@zevpay/react-native';

function CheckoutScreen() {
  const checkout = useZevPayCheckout();

  const handlePay = async () => {
    const result = await checkout.open({
      publicKey: 'pk_test_your_public_key',
      email: 'customer@example.com',
      amount: 500000,
    });

    if (result.success) {
      console.log('Paid!', result.reference);
      // Verify payment on your server
    } else if (result.cancelled) {
      console.log('User cancelled');
    } else if (result.error) {
      console.error('Error:', result.error);
    }
  };

  return (
    <>
      <Button title="Pay" onPress={handlePay} />

      {checkout.options && (
        <ZevPayCheckout
          visible={checkout.visible}
          onSuccess={checkout.onSuccess}
          onCancel={checkout.onCancel}
          onError={checkout.onError}
          {...checkout.options}
        />
      )}
    </>
  );
}
```

### Return value

| Property | Type | Description |
|----------|------|-------------|
| `open` | `(options) => Promise<CheckoutResult>` | Opens checkout, resolves on completion |
| `close` | `() => void` | Programmatically close the modal |
| `visible` | `boolean` | Current modal visibility |
| `options` | `CheckoutOptions \| null` | Current checkout options |
| `onSuccess` | `function` | Pass to `<ZevPayCheckout>` |
| `onCancel` | `function` | Pass to `<ZevPayCheckout>` |
| `onError` | `function` | Pass to `<ZevPayCheckout>` |

### `CheckoutResult`

```typescript
interface CheckoutResult {
  success: boolean;     // Payment was successful
  cancelled: boolean;   // User cancelled
  reference?: string;   // Payment reference (when successful)
  error?: Error;        // Error (when failed)
}
```

## Server-side verification

::: warning Always verify on your server
The client-side callback only indicates the user completed the flow. Always verify the payment on your server using the reference.
:::

```typescript
// Your server (Node.js example)
import ZevPay from '@zevpay/node';

const zevpay = new ZevPay('sk_test_your_secret_key');
const session = await zevpay.checkout.verify(reference);

if (session.status === 'completed') {
  // Payment is confirmed
}
```

## Resources

- [API Reference](/api/overview) — Full endpoint documentation
- [Standard Checkout](/sdks/standard) — Underlying checkout flow
- [Webhook Events](/webhooks/events) — All event types
- [npm](https://www.npmjs.com/package/@zevpay/react-native) — Package registry