Flutterwave Universal

A modern, lightweight, and type-safe Flutterwave API SDK built with TypeScript. Designed for compatibility across Node.js, Bun, and edge runtimes (e.g., Cloudflare Workers, Vercel Edge Functions).

Features

• Full TypeScript support: Built from the ground up with TypeScript for excellent developer experience
• Universal Runtime Compatibility: Works seamlessly in Node.js, Bun, Deno, and edge environments
• Zero Dependencies: Minimal runtime dependencies for lightweight integration
• ESM and CJS builds: Support for both module systems
• Modern API: Leverages the native fetch API
• Comprehensive Coverage: Support for all Flutterwave payment services

Installation

npm

npm install flutterwave-universal

Yarn

yarn add flutterwave-universal

pnpm

pnpm add flutterwave-universal

Bun

bun add flutterwave-universal

Deno

import { Flutterwave } from "npm:flutterwave-universal";

Quick Start

import { Flutterwave } from "flutterwave-universal";

// Initialize the Flutterwave SDK with your secret key
const flw = new Flutterwave({
  secretKey: "YOUR_FLUTTERWAVE_SECRET_KEY",
  // Optional configuration
  timeout: 30000, // 30 seconds
});

// Example: Create a payment link
async function createPaymentLink() {
  try {
    const paymentLink = await flw.paymentLinks.create({
      amount: 1000,
      currency: "NGN",
      description: "Payment for product",
      title: "Product Purchase",
      customer: {
        email: "[email protected]",
        name: "John Doe",
        phone_number: "08012345678",
      },
      redirect_url: "https://example.com/callback",
    });
    
    console.log("Payment link created:", paymentLink);
    return paymentLink;
  } catch (error) {
    console.error("Error creating payment link:", error);
    throw error;
  }
}

Usage Examples

Process Card Payments

// Charge a card
const cardPayment = await flw.charges.card({
  card_number: "5531886652142950",
  cvv: "564",
  expiry_month: "09",
  expiry_year: "32",
  currency: "NGN",
  amount: 1000,
  email: "[email protected]",
  fullname: "John Doe",
  tx_ref: "unique-transaction-reference",
  redirect_url: "https://example.com/callback",
});

Verify Transactions

// Verify a transaction by ID
const verificationResult = await flw.transactions.verify({
  id: "12345",
});

// Or verify by reference
const verificationByRef = await flw.transactions.verifyByReference({
  tx_ref: "unique-transaction-reference",
});

Create Virtual Account

// Create a virtual account for a customer
const virtualAccount = await flw.virtualAccounts.create({
  email: "[email protected]",
  is_permanent: true,
  bvn: "12345678901",
  tx_ref: "unique-reference",
  first_name: "John",
  last_name: "Doe",
  narration: "John Doe's Account",
});

API Reference

The SDK provides access to the following Flutterwave services:

• Payments: Process various payment methods

  • charges - Card, Bank Transfer, USSD, etc.
  • paymentLinks - Create and manage payment links
  • transactions - Verify and manage transactions

• Financial Accounts:

  • virtualAccounts - Create and manage virtual accounts
  • banks - Get list of supported banks
  • transfers - Process transfers to bank accounts

• Subscriptions:

  • subscriptions - Manage payment subscriptions
  • plans - Create and manage subscription plans

• Verification:

  • otp - Generate and validate OTPs
  • billVerification - Verify bill payments

• Others:

  • settlements - Manage settlements
  • subaccounts - Create and manage subaccounts
  • misc - Miscellaneous endpoints

For detailed documentation on each module, please refer to the API documentation.

Runtime Compatibility

This SDK is designed to work across multiple JavaScript runtimes:

| Runtime | Compatibility | Notes | | ------- | ------------- | ----- | | Node.js | ✅ Full | Tested with Node.js 16+ | | Bun | ✅ Full | Tested with Bun 1.0+ | | Deno | ✅ Full | Via npm: specifier | | Cloudflare Workers | ✅ Full | No special configuration needed | | Vercel Edge Functions | ✅ Full | Compatible with Edge Runtime | | Netlify Edge Functions | ✅ Full | Works with Netlify Edge |

Testing Across Different Runtimes

You can verify compatibility across different JavaScript runtimes without installing them locally using Docker:

# Make the script executable
chmod +x test_all_runtimes.sh

# Run tests across all supported runtimes
./test_all_runtimes.sh

This will build and run Docker containers for each supported runtime:

• Node.js
• Bun
• Deno
• Cloudflare Workers (simulated environment)

Requirements

• Docker installed on your machine
• Internet connection (to pull Docker images)

Testing Individual Runtimes

You can also test individual runtimes:

# Test in Node.js
docker build -t flutterwave-node-test -f ./dockerfiles/Dockerfile.node .
docker run --rm flutterwave-node-test

# Test in Bun
docker build -t flutterwave-bun-test -f ./dockerfiles/Dockerfile.bun .
docker run --rm flutterwave-bun-test

# Test in Deno
docker build -t flutterwave-deno-test -f ./dockerfiles/Dockerfile.deno .
docker run --rm flutterwave-deno-test

# Test in Cloudflare Workers (simulated)
docker build -t flutterwave-cloudflare-test -f ./dockerfiles/Dockerfile.cloudflare .
docker run --rm flutterwave-cloudflare-test

Error Handling

The SDK uses a standardized error system for consistent error handling:

try {
  const result = await flw.paymentLinks.create({
    // payment details
  });
} catch (error) {
  if (error instanceof FlutterwaveError) {
    console.error("Flutterwave API Error:", error.message);
    console.error("Error Code:", error.code);
    console.error("Error Data:", error.data);
  } else {
    console.error("Unexpected error:", error);
  }
}

Advanced Configuration

const flw = new Flutterwave({
  secretKey: "YOUR_FLUTTERWAVE_SECRET_KEY",
  timeout: 60000, // 60 seconds timeout for requests
  // Add other configuration options as needed
});

Contributing

Contributions are welcome! Please feel free to submit a Pull Request.

1. Fork the repository
2. Create your feature branch (git checkout -b feature/amazing-feature)
3. Commit your changes (git commit -m 'feat: add some amazing feature')
4. Push to the branch (git push origin feature/amazing-feature)
5. Open a Pull Request

Please make sure your code follows the existing style and includes appropriate tests.

Documentation

For more detailed documentation, please check the docs directory:

• API Reference
• Webhooks Guide
• Error Handling
• Runtime-specific notes

License

This project is licensed under the MIT License - see the LICENSE file for details.

Security

If you discover any security related issues, please email the author instead of using the issue tracker.

Support

For questions and support, please open an issue on the GitHub repository.