Skip to content
Voltax

Getting Started

Voltax is a unified payment SDK that simplifies integrating multiple African payment gateways (Paystack, Flutterwave, Hubtel, etc) 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
  • 🔄 Factory Pattern: Use Voltax() for single providers, VoltaxAdapter for multiple
  • ⚡ 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

Quick Start

Section titled “Quick Start”

  1. Import the SDK

    You can import the Voltax factory function:

    import Voltax from "@noelzappy/voltax";

    Or import specific adapters directly:

    import { PaystackAdapter, HubtelAdapter } from "@noelzappy/voltax";

  2. Initialize a Provider

    Use the Voltax factory function to create a provider instance with full type inference:

    // Single provider setup (recommended)
    const paystack = Voltax("paystack", {
      secretKey: process.env.PAYSTACK_SECRET_KEY!,
    });
    

    const hubtel = Voltax("hubtel", {
      clientId: process.env.HUBTEL_CLIENT_ID!,
      clientSecret: process.env.HUBTEL_CLIENT_SECRET!,
      merchantAccountNumber: process.env.HUBTEL_MERCHANT_ACCOUNT!,
    });

    Or use VoltaxAdapter for multiple providers:

    import { VoltaxAdapter } from "@noelzappy/voltax";
    

    const voltax = new VoltaxAdapter({
      paystack: { secretKey: process.env.PAYSTACK_SECRET_KEY! },
      flutterwave: { secretKey: process.env.FLUTTERWAVE_SECRET_KEY! },
      hubtel: {
        clientId: process.env.HUBTEL_CLIENT_ID!,
        clientSecret: process.env.HUBTEL_CLIENT_SECRET!,
        merchantAccountNumber: process.env.HUBTEL_MERCHANT_ACCOUNT!,
      },
    });

  3. Initiate a Payment

    Use the provider to initiate a payment:

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

    const response = await paystack.initiatePayment({
      amount: 100.0, // 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 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
MoolreGhana, NigeriaGHS, NGN

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”