@ivorypay/react-sdk

Official React SDK for IvoryPay — accept crypto and fiat payments in your React web app.

Installation

yarn add @ivorypay/react-sdk

Setup

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

// 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

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

function PaymentPage() {
  return (
    <IvoryPayCheckout
      request={{
        amount: 5000,
        email: '[email protected]',
        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

<IvoryPayCheckout
  request={{
    amount: 10000,
    email: '[email protected]',
    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.

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: '[email protected]',
      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

// Initiate
const tx = await IvoryPay.initiateTransaction({
  amount: 5000,
  email: '[email protected]',
  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

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