Installation

# npm
npm install @frizzyondabeat/react-karrabo

# yarn
yarn add @frizzyondabeat/react-karrabo

# pnpm
pnpm add @frizzyondabeat/react-karrabo

GitHub Packages users: add a .npmrc to your project first:

@frizzyondabeat:registry=https://npm.pkg.github.com
//npm.pkg.github.com/:_authToken=YOUR_GITHUB_TOKEN

Quick Start

import { usePayment } from '@frizzyondabeat/react-karrabo';

function CheckoutButton() {
  const initializePayment = usePayment({
    publicKey: 'your-public-key',
    checkoutBaseUrl: 'https://checkout.karrabo.com',
    email: '[email protected]',
    amount: 5000,
    currency: 'NGN',
  });

  return (
    <button
      onClick={() =>
        initializePayment({
          onSuccess: (response) => console.log('Payment successful', response),
          onClose: () => console.log('Checkout closed'),
          onError: (error) => console.error('Payment failed', error),
        })
      }
    >
      Pay ₦5,000
    </button>
  );
}

Payment Modes

inline (default)

Opens a centered modal overlay with the checkout embedded in an iframe. The modal appears with a smooth loading spinner, then resizes to fit the checkout page automatically.

initializePayment({ /* mode defaults to 'inline' */ });

redirect

Navigates the user to a payment link URL in the same tab.

const initializePayment = usePayment({
  publicKey: 'your-public-key',
  checkoutBaseUrl: 'https://checkout.karrabo.com',
  email: '[email protected]',
  amount: 5000,
  mode: 'redirect',
  paymentLinkUrl: 'https://pay.karrabo.com/link/abc123',
});

new_tab

Opens the checkout in a new browser tab.

const initializePayment = usePayment({
  publicKey: 'your-public-key',
  checkoutBaseUrl: 'https://checkout.karrabo.com',
  email: '[email protected]',
  amount: 5000,
  mode: 'new_tab',
});

API Reference

usePayment(config)

A React hook that accepts your checkout configuration and returns an initializePayment function.

const initializePayment = usePayment(config: HookConfig);

Call initializePayment to trigger the checkout:

initializePayment({
  onSuccess?: (response?: any) => void;
  onClose?: () => void;
  onError?: (error?: any) => void;
  config?: Partial<PaymentConfig>; // override hook-level config per call
});

PaymentConfig

| Prop | Type | Required | Default | Description | |------|------|:--------:|---------|-------------| | publicKey | string | ✅ | — | Your Karrabo public key | | checkoutBaseUrl | string | ✅ | — | Base URL of the Karrabo checkout | | email | string | ✅ | — | Customer's email address | | amount | number | ✅ | — | Amount in the smallest currency unit (e.g. kobo for NGN) | | currency | Currency | — | 'NGN' | Payment currency | | reference | string | — | — | Unique transaction reference | | firstName | string | — | — | Customer's first name | | lastName | string | — | — | Customer's last name | | phone | string \| number | — | — | Customer's phone number | | label | string | — | — | Display label on the checkout | | channels | PaymentChannel[] | — | — | Payment channels to enable | | metadata | PaymentMetadata | — | — | Extra data attached to the transaction | | mode | PaymentMode | — | 'inline' | How to open the checkout | | paymentLinkUrl | string | — | — | Direct payment link (used with redirect or new_tab mode) |

Types

type Currency = 'NGN' | 'GHS' | 'USD' | 'ZAR' | 'KES' | 'XOF' | 'GBP' | 'EUR' | (string & {});

type PaymentChannel = 'card' | 'bank' | 'ussd' | 'qr' | 'mobile_money' | 'bank_transfer';

type PaymentMode = 'inline' | 'redirect' | 'new_tab';

interface PaymentMetadata {
  custom_fields?: PaymentCustomField[];
  [key: string]: any;
}

interface PaymentCustomField {
  display_name: string;
  variable_name: string;
  value: any;
}

Override Config Per Call

You can set base config on the hook and override specific fields per call:

const initializePayment = usePayment({
  publicKey: 'your-public-key',
  checkoutBaseUrl: 'https://checkout.karrabo.com',
  email: '[email protected]',
  amount: 0,
  currency: 'NGN',
});

// Override amount and reference for each unique transaction
initializePayment({
  config: { amount: 10000, reference: 'ORDER_001' },
  onSuccess: (res) => console.log(res),
});

TypeScript

This library ships with full TypeScript declarations. All types are exported directly:

import type {
  PaymentConfig,
  HookConfig,
  InitializePayment,
  Currency,
  PaymentMode,
  PaymentChannel,
  PaymentMetadata,
  PaymentCustomField,
} from '@frizzyondabeat/react-karrabo';

Peer Dependencies

| Package | Version | |---------|---------| | react | ^16.0.0 \|\| ^17.0.0 \|\| ^18.0.0 \|\| ^19.0.0 | | react-dom | ^16.0.0 \|\| ^17.0.0 \|\| ^18.0.0 \|\| ^19.0.0 |

Test Coverage

| File | Statements | Branches | Functions | Lines | |------|:----------:|:--------:|:---------:|:-----:| | payment-actions.ts | 98.14% | 87.3% | 87.5% | 98.91% | | use-payment.ts | 100% | 100% | 100% | 100% | | All files | 98.33% | 89.33% | 92.3% | 99.03% |

Run coverage locally:

npx jest --coverage

License

MIT © Karrabo