npm package: @ivorypay/react-native-sdk
Description: Official React Native SDK for IvoryPay — accept crypto and fiat payments with a single integration.
Author: IvoryPay
Latest version: 0.1.0

# @ivorypay/react-native-sdk

Official React Native SDK for [IvoryPay](https://ivorypay.io) — accept crypto and fiat payments in your React Native app.

---

## Installation

```sh
yarn add @ivorypay/react-native-sdk
```

For the WebView checkout mode, also install:

```sh
yarn add react-native-webview
cd ios && pod install
```

---

## Setup

Call `IvoryPay.initialize` once at app startup with your **public key** (`pk_test_...` or `pk_live_...`).

```tsx
// App.tsx
import { IvoryPay } from '@ivorypay/react-native-sdk';

IvoryPay.initialize({ publicKey: 'pk_test_xxxxxxxxxxxxxxxx' });

export default function App() {
  return <RootNavigator />;
}
```

> **Public key only.** Never use your secret key in a mobile app.

---

## Two checkout modes

### 1. Custom UI (`IvoryPayCheckout`)

A fully native React Native component that handles the complete payment lifecycle:
- Calls the API to initiate the transaction
- Renders wallet address (crypto) or bank details (fiat)
- Polls for payment confirmation every 5 seconds
- Shows success / expired / failed states automatically

```tsx
import { IvoryPayCheckout } from '@ivorypay/react-native-sdk';

function PaymentScreen() {
  return (
    <IvoryPayCheckout
      request={{
        amount: 5000,
        email: 'customer@example.com',
        firstName: 'John',
        lastName: 'Doe',
        type: 'CRYPTO',
        baseFiat: 'NGN',
        crypto: 'USDT',
        chain: 'BSC_MAINNET',
      }}
      onSuccess={() => navigation.replace('SuccessScreen')}
      onError={(msg) => console.error(msg)}
      onClose={() => navigation.goBack()}
    />
  );
}
```

#### Fiat example

```tsx
<IvoryPayCheckout
  request={{
    amount: 10000,
    email: 'customer@example.com',
    type: 'FIAT',
    baseFiat: 'NGN',
  }}
  onSuccess={() => navigation.replace('SuccessScreen')}
  onError={(msg) => Alert.alert('Error', msg)}
/>
```

---

### 2. WebView checkout (`IvoryPayWebViewCheckout`)

Wraps the IvoryPay hosted checkout page in a WebView. Use this if you prefer the hosted UI.

First, initiate the transaction to get the `checkoutUrl`:

```tsx
import { IvoryPay, IvoryPayWebViewCheckout } from '@ivorypay/react-native-sdk';

async function openCheckout() {
  const tx = await IvoryPay.initiateTransaction({
    amount: 5000,
    email: 'customer@example.com',
    type: 'CRYPTO',
    baseFiat: 'NGN',
    crypto: 'USDT',
    chain: 'BSC_MAINNET',
  });

  navigation.navigate('WebViewCheckout', {
    checkoutUrl: tx.collectionDetails.checkoutUrl!,
  });
}

function WebViewCheckoutScreen({ route }) {
  return (
    <IvoryPayWebViewCheckout
      checkoutUrl={route.params.checkoutUrl}
      onSuccess={() => navigation.replace('SuccessScreen')}
      onFailed={() => navigation.goBack()}
      onClosed={() => navigation.goBack()}
    />
  );
}
```

The checkout page communicates back via `window.ReactNativeWebView.postMessage` with events:
- `payment.success`
- `payment.failed`
- `payment.closed`

---

## Manual API usage

You can also call the API directly without any UI component:

### Initiate a transaction

```ts
const tx = await IvoryPay.initiateTransaction({
  amount: 5000,
  email: 'customer@example.com',
  type: 'CRYPTO',
  baseFiat: 'NGN',
  crypto: 'USDT',
  chain: 'BSC_MAINNET',
});

console.log(tx.collectionDetails.address); // wallet address
console.log(tx.amountInCrypto);            // exact crypto amount
console.log(tx.expiresAt);                 // expiry timestamp
```

### Verify a transaction

```ts
const status = await IvoryPay.verifyTransaction(tx.reference);
// status.status: 'PENDING' | 'PROCESSING' | 'CONFIRMING' | 'SUCCESS' | 'FAILED' | 'EXPIRED' | 'MISMATCH'
```

---

## Types

```ts
type TransactionType = 'CRYPTO' | 'FIAT';

type TransactionStatus =
  | 'PENDING'
  | 'PROCESSING'
  | 'CONFIRMING'
  | 'SUCCESS'
  | 'FAILED'
  | 'EXPIRED'
  | 'MISMATCH';

type SupportedToken = 'USDT' | 'USDC' | 'BTC' | 'ETH' | 'SOL';

type SupportedNetwork =
  | 'BSC_MAINNET'
  | 'BSC_TESTNET'
  | 'POLYGON'
  | 'SOLANA'
  | 'BITCOIN'
  | 'ETH'
  | 'TRON'
  | 'MATIC';

type SupportedFiatCurrency = 'NGN' | 'KES' | 'GHS' | 'ZAR' | 'USD';
```

---

## Environments

| Key prefix  | Environment |
|-------------|-------------|
| `pk_test_`  | Sandbox     |
| `pk_live_`  | Production  |

---

## License

MIT — see [LICENSE](LICENSE)