Skip to content
Voltax

Getting Started

Voltax is a unified payment SDK that simplifies integrating multiple African payment gateways (Paystack, Flutterwave, Hubtel) into a single, consistent API. Build faster, switch providers easily, and maintain less code.

Features

Section titled “Features”
  • 🛡 Strictly Typed: Built with TypeScript + Zod for runtime validation
  • 🔗 Standardized API: One interface (VoltaxProvider) for all gateways
  • 🔄 Adapter Pattern: Swap providers without rewriting business logic
  • ⚡ Lightweight: Tree-shakeable, ESM & CJS support
  • 🔒 Secure: No hardcoded keys, enforced validation checks

Prerequisites

Section titled “Prerequisites”

Before you begin, make sure you have:

  • Node.js 18 or later
  • npm, pnpm, or yarn package manager
  • API credentials from at least one supported payment provider

Installation

Section titled “Installation”

Install the Voltax SDK using your preferred package manager.

```bash npm install @noelzappy/voltax ``` ```bash pnpm add @noelzappy/voltax ``` ```bash yarn add @noelzappy/voltax ```

Quick Start

Section titled “Quick Start”

  1. Import the SDK

    You can import the Voltax class either as a default export or named export:

    // Default import
    import Voltax from '@noelzappy/voltax';
    

    // Or named import
    import { Voltax } from '@noelzappy/voltax';

  2. Initialize the SDK

    Configure the SDK with the providers you want to use. You only need to provide configuration for the providers you’ll be using:

    const voltax = new Voltax({
      // Paystack configuration
      paystack: {
        secretKey: process.env.PAYSTACK_SECRET_KEY!,
      },
      // Flutterwave configuration (optional)
      flutterwave: {
        secretKey: process.env.FLUTTERWAVE_SECRET_KEY!,
      },
      // Hubtel configuration (optional)
      hubtel: {
        clientId: process.env.HUBTEL_CLIENT_ID!,
        clientSecret: process.env.HUBTEL_CLIENT_SECRET!,
        merchantAccountNumber: process.env.HUBTEL_MERCHANT_ACCOUNT!,
      },
    });

  3. Initialize a Payment

    Use the provider of your choice to initialize a payment:

    import { Currency } from '@noelzappy/voltax';
    

    const response = await voltax.paystack.initializePayment({
      amount: 100.00,  // Amount in major currency units (e.g., 100 NGN)
      email: 'customer@example.com',
      currency: Currency.NGN,
      reference: 'unique-transaction-ref-123',
      callbackUrl: 'https://yoursite.com/payment/callback',
      description: 'Payment for Order #123',
    });
    

    // Redirect user to complete payment
    console.log(response.authorizationUrl);

  4. Verify the Payment

    After the user completes the payment, verify the transaction:

    import { PaymentStatus } from '@noelzappy/voltax';
    

    const verification = await voltax.paystack.verifyTransaction('unique-transaction-ref-123');
    

    if (verification.status === PaymentStatus.SUCCESS) {
      console.log('Payment successful!');
    } else if (verification.status === PaymentStatus.PENDING) {
      console.log('Payment is still processing...');
    } else {
      console.log('Payment failed.');
    }

Supported Providers

Section titled “Supported Providers”
ProviderCountriesCurrencies
PaystackNigeria, Ghana, South Africa, KenyaNGN, GHS, ZAR, KES, USD
FlutterwaveNigeria, Ghana, Kenya, South Africa, and moreNGN, GHS, KES, ZAR, USD
HubtelGhanaGHS

Configuration Reference

Section titled “Configuration Reference”

Paystack Configuration

Section titled “Paystack Configuration”
interface PaystackConfig {
  secretKey: string;  // Your Paystack secret key
}

Flutterwave Configuration

Section titled “Flutterwave Configuration”
interface FlutterwaveConfig {
  secretKey: string;  // Your Flutterwave secret key
}

Hubtel Configuration

Section titled “Hubtel Configuration”
interface HubtelConfig {
  clientId: string;           // Your Hubtel client ID
  clientSecret: string;       // Your Hubtel client secret
  merchantAccountNumber: string;  // Your Hubtel merchant account number
}

Next Steps

Section titled “Next Steps”