@zahlen/checkout-react

🚀 Installation

npm install @zahlen/checkout-react @zahlen/checkout
# or
yarn add @zahlen/checkout-react @zahlen/checkout

📖 Quick Start

Option 1: Simple Button (Easiest)

import { ZahlenProvider, ZahlenButton } from '@zahlen/checkout-react';

function App() {
  return (
    <ZahlenProvider apiKey="pk_live_your_api_key">
      <ProductPage />
    </ZahlenProvider>
  );
}

function ProductPage() {
  return (
    <ZahlenButton
      amount={499900}        // ₦4,999 in kobo
      currency="NGN"
      description="Premium Plan"
      onSuccess={(result) => {
        console.log('Paid!', result);
        // Redirect to success page
      }}
      onError={(error) => {
        toast.error(error.message);
      }}
    >
      💳 Pay ₦4,999
    </ZahlenButton>
  );
}

Option 2: useZahlen Hook (Recommended)

import { ZahlenProvider, useZahlen } from '@zahlen/checkout-react';

function App() {
  return (
    <ZahlenProvider apiKey="pk_live_your_api_key" theme="dark">
      <ProductPage />
    </ZahlenProvider>
  );
}

function ProductPage() {
  const { openCheckout, isProcessing } = useZahlen();

  const handleBuy = async () => {
    try {
      const result = await openCheckout({
        amount: 499900,
        currency: 'NGN',
        description: 'Premium Plan',
      });
      console.log('Payment successful!', result);
      router.push('/success');
    } catch (error) {
      console.error('Payment failed:', error);
    }
  };

  return (
    <button onClick={handleBuy} disabled={isProcessing}>
      {isProcessing ? 'Processing...' : 'Buy Now'}
    </button>
  );
}

Option 3: Controlled Component (Full Control)

import { useState } from 'react';
import { ZahlenCheckout } from '@zahlen/checkout-react';
import { Zahlen } from '@zahlen/checkout';

// Initialize once at app entry
Zahlen.init({ apiKey: 'pk_live_your_api_key' });

function ProductPage() {
  const [isOpen, setIsOpen] = useState(false);

  return (
    <>
      <button onClick={() => setIsOpen(true)}>Pay Now</button>

      <ZahlenCheckout
        open={isOpen}
        onClose={() => setIsOpen(false)}
        amount={499900}
        currency="NGN"
        description="Premium Plan"
        onSuccess={(result) => {
          setIsOpen(false);
          router.push('/success');
        }}
        onError={(error) => {
          console.error(error);
        }}
      />
    </>
  );
}

📚 API Reference

<ZahlenProvider>

Wrap your app with this provider to use Zahlen hooks.

<ZahlenProvider
  apiKey="pk_live_xxx"     // Required
  theme="dark"             // Optional: 'dark' | 'light' | 'auto'
>
  {children}
</ZahlenProvider>

useZahlen()

Hook to access Zahlen functionality.

const {
  isInitialized,  // boolean - whether SDK is ready
  isProcessing,   // boolean - whether payment is in progress
  openCheckout,   // (options) => Promise<PaymentResult>
  closeCheckout,  // () => void
  setTheme,       // (theme) => void
} = useZahlen();

<ZahlenButton>

Pre-styled checkout button.

| Prop | Type | Required | Description | |------|------|----------|-------------| | amount | number | ✅ | Amount in smallest unit | | currency | string | ✅ | ISO currency code | | description | string | | Payment description | | customerEmail | string | | Customer email | | metadata | object | | Custom metadata | | onSuccess | function | | Success callback | | onError | function | | Error callback | | onClose | function | | Close callback | | className | string | | CSS class | | style | object | | Inline styles | | disabled | boolean | | Disable button |

<ZahlenCheckout>

Controlled checkout component.

| Prop | Type | Required | Description | |------|------|----------|-------------| | open | boolean | ✅ | Control modal visibility | | onClose | function | ✅ | Close callback | | amount | number | ✅ | Amount in smallest unit | | currency | string | ✅ | ISO currency code | | onSuccess | function | ✅ | Success callback | | onError | function | | Error callback | | description | string | | Payment description |

🎨 Customization

import { Zahlen } from '@zahlen/checkout';

// After init, customize theme
Zahlen.init({
  apiKey: 'pk_live_xxx',
  customStyles: {
    '--zahlen-primary': '#FF6B6B',
    '--zahlen-bg': '#1A1A2E',
  }
});

📄 License

MIT © Zahlen