@ivorypay/react-native-sdk

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

Installation

yarn add @ivorypay/react-native-sdk

For the WebView checkout mode, also install:

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_...).

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

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

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

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

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

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

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
console.log(tx.amountInCrypto);            // exact crypto amount
console.log(tx.expiresAt);                 // expiry timestamp

Verify a transaction

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

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