BudPay TypeScript SDK

A lightweight, high-fidelity, and type-safe SDK for integrating BudPay into your TypeScript/JavaScript projects. Built with performance and security in mind.

🚀 Features

• Standardized Responses: Every API call returns a consistent { success, status, message, data } object.
• Type Safety: Comprehensive TypeScript definitions for all request and response payloads.
• Enhanced Debugging: Integrated diagnostic logging with sensitive data masking (keys, cards).
• Security: HMAC-SHA256 signature verification for the required endpoints.
• Pending Features: Webhook signature verification and card encryption (⚠️ Work In Progress).
• Zero Dependencies: Lightweight footprint (only zod for validation).
• Dual Support: Works with both ESM and CommonJS.

📦 Installation

npm install @emmanuelapabiekun/budpay
# or
yarn add @emmanuelapabiekun/budpay
# or
pnpm add @emmanuelapabiekun/budpay
# or
bun add @emmanuelapabiekun/budpay

🛠️ Configuration

Initialize the SDK with your BudPay secret and public keys. You can find these in your BudPay Dashboard.

import { BudPay } from "@emmanuelapabiekun/budpay";

const budpay = new BudPay({
  secretKey: process.env.BUDPAY_SECRET_KEY,
  publicKey: process.env.BUDPAY_PUBLIC_KEY,
  debug: true, // Enable for detailed diagnostic logs
});

[!NOTE] If keys are not provided in the constructor, the SDK will automatically look for BUDPAY_SECRET_KEY and BUDPAY_PUBLIC_KEY environment variables.

📖 Usage Examples

Verify a Transaction

const response = await budpay.transactions.verify("TRANSACTION_REFERENCE");

if (response.success) {
  console.log("Payment Successful:", response.data);
} else {
  console.error("Verification Failed:", response.message);
}

Create a Payout

const result = await budpay.payouts.transfer({
  amount: "1000",
  account_number: "0123456789",
  bank_code: "058",
  currency: "NGN",
  reference: "unique_bill_ref_" + Date.now(),
  narration: "unique_bill_ref_" + Date.now(),
  bank_name: "Test Bank",
  meta_data: [
    {
      sender_name: "sender_name",
      sender_address: "sender_address",
    },
  ],
});

Bill Payment

const result = await budpay.bills.airtimeTopup({
  amount: "1000",
  reference: "unique_bill_ref_" + Date.now(),
  provider: "mtn",
  number: "08012345678",
});

Verify Webhook Signature (⚠️ Work In Progress)

The Webhook verification utility is currently under maintenance and has been temporarily deactivated in the SDK.

// BudPay.verifyWebhook(...) // Currently throws an error

🔍 Modules

The SDK provides organized access to the entire BudPay API suite:

| Module | Description | | ----------------- | -------------------------------------------------- | | transactions | Payment initialization, verification, and history. | | payouts | Bank transfers and wallet payouts. | | bills | Airtime, data, and utility payments. | | virtualAccounts | Dynamic and static bank account collection. | | customers | Customer profile management. | | wallet | Balance checks and internal transfers. | | settlements | Track payouts to your business bank account. | | invoices | Professional invoice generation. | | paymentLinks | Easy-to-share payment URLs. | | identity | Account name verification and ID checks. |

🛡️ Security & Privacy

This SDK takes security seriously:

• Masking: When debug: true is enabled, sensitive fields like card numbers and API keys are automatically redacted in logs.
• Encryption: Built-in AES-CBC encryption for handling sensitive card data (⚠️ Work In Progress).
• Validation: All inputs are validated using zod before being sent to the server.

📄 Documentation

For detailed information on API parameters and behavior, please refer to the Official BudPay Documentation.

🤝 Contributing

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

📜 License

MIT © Emmanuel Apabiekun