npm package: @ivorypay/react-sdk
Description: Official React SDK for IvoryPay — accept crypto and fiat payments in your React web app.
Author: IvoryPay
Latest version: 0.1.0

# @ivorypay/react-sdk

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

---

## Installation

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

---

## Setup

Call `IvoryPay.initialize` once at app startup with your **public key**.

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

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

> **Public key only.** Never use your secret key (`sk_...`) in a browser app.

---

## Two checkout modes

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

A self-contained React component that handles the full payment lifecycle:
- Calls the API to initiate the transaction
- Renders wallet address + copy button (crypto) or bank details (fiat)
- Polls for confirmation every 5 seconds
- Handles success / expired / failed states automatically

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

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

#### Fiat example

```tsx
<IvoryPayCheckout
  request={{
    amount: 10000,
    email: 'customer@example.com',
    type: 'FIAT',
    baseFiat: 'NGN',
  }}
  onSuccess={() => router.push('/success')}
  onError={(msg) => alert(msg)}
/>
```

---

### 2. Modal checkout (`IvoryPayModal`)

Renders the IvoryPay hosted checkout page inside an iframe modal overlay. Controlled by an `open` boolean.

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

function ProductPage() {
  const [open, setOpen] = useState(false);
  const [checkoutUrl, setCheckoutUrl] = useState('');

  const handlePay = async () => {
    const tx = await IvoryPay.initiateTransaction({
      amount: 5000,
      email: 'customer@example.com',
      type: 'CRYPTO',
      baseFiat: 'NGN',
      crypto: 'USDT',
      chain: 'BSC_MAINNET',
    });
    setCheckoutUrl(tx.collectionDetails.checkoutUrl!);
    setOpen(true);
  };

  return (
    <>
      <button onClick={handlePay}>Pay Now</button>

      <IvoryPayModal
        checkoutUrl={checkoutUrl}
        open={open}
        onSuccess={() => { setOpen(false); router.push('/success'); }}
        onFailed={() => setOpen(false)}
        onClosed={() => setOpen(false)}
      />
    </>
  );
}
```

The modal listens for `window.postMessage` events from the checkout page:
- `{ event: "payment.success" }` → `onSuccess`
- `{ event: "payment.failed" }` → `onFailed`
- `{ event: "payment.closed" }` → `onClosed`

The modal also closes when the user clicks the backdrop or presses `Escape`.

---

## Manual API usage

```ts
// Initiate
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 (crypto)
console.log(tx.collectionDetails.checkoutUrl); // hosted checkout URL

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

---

## 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)