@scwar/nestjs-monnify

A comprehensive NestJS module for integrating with the Monnify API. This package provides a clean, type-safe interface for all Monnify services including collections, disbursements, wallets, customer verification, sub-accounts, invoices, settlements, and transactions.

Features

• 🚀 Full Monnify API Coverage - Collections, Disbursements, Wallets, Verification, Sub-Accounts, Invoices, Settlements, Transactions
• 🔒 Type Safety - Full TypeScript support with comprehensive interfaces
• 🏗️ NestJS Native - Built specifically for NestJS applications
• 🔄 Automatic Retries - Configurable retry logic with exponential backoff
• 🌍 Environment Support - Sandbox and production environments
• 📚 Comprehensive Documentation - Well-documented methods and interfaces
• 🧪 Test Coverage - Extensive test suite for reliability

Installation

npm install @scwar/nestjs-monnify

Quick Start

1. Import the Module

import { Module } from '@nestjs/common';
import { MonnifyModule } from '@scwar/nestjs-monnify';

@Module({
  imports: [
    MonnifyModule.forRoot({
      secretKey: 'your-secret-key',
      publicKey: 'your-public-key',
      contractCode: 'your-contract-code',
      environment: 'sandbox', // or 'production'
    }),
  ],
})
export class AppModule {}

2. Use the Service

import { Injectable } from '@nestjs/common';
import { MonnifyService } from '@scwar/nestjs-monnify';

@Injectable()
export class PaymentService {
  constructor(private readonly monnifyService: MonnifyService) {}

  async initializePayment() {
    const payment = await this.monnifyService.collections.initializeTransaction({
      amount: 1000,
      customerName: 'John Doe',
      customerEmail: '[email protected]',
      paymentReference: 'REF-123',
      paymentDescription: 'Payment for services',
      currencyCode: 'NGN',
      contractCode: 'your-contract-code',
      redirectUrl: 'https://yourapp.com/callback',
    });

    return payment;
  }
}

Configuration Options

| Option | Type | Required | Default | Description | |--------|------|----------|---------|-------------| | secretKey | string | ✅ | - | Your Monnify secret key | | publicKey | string | ✅ | - | Your Monnify public key | | contractCode | string | ✅ | - | Your Monnify contract code | | environment | 'sandbox' | 'production' | ❌ | 'sandbox' | API environment | | baseUrl | string | ❌ | Auto-detected | Custom API base URL | | timeout | number | ❌ | 30000 | Request timeout in ms | | retries | number | ❌ | 3 | Number of retry attempts | | retryDelay | number | ❌ | 1000 | Initial retry delay in ms | | maxRetryDelay | number | ❌ | 10000 | Maximum retry delay in ms |

Services

Collections Service

Handle payment collections and customer reserved accounts.

// Initialize a transaction
const transaction = await monnifyService.collections.initializeTransaction({
  amount: 1000,
  customerName: 'John Doe',
  customerEmail: '[email protected]',
  paymentReference: 'REF-123',
  paymentDescription: 'Payment for services',
  currencyCode: 'NGN',
  contractCode: 'your-contract-code',
});

// Get transaction status
const status = await monnifyService.collections.getTransactionStatus('transaction-ref');

// Create reserved account
const account = await monnifyService.collections.createReservedAccount({
  accountReference: 'ACC-123',
  accountName: 'John Doe Account',
  customerEmail: '[email protected]',
  customerName: 'John Doe',
  contractCode: 'your-contract-code',
});

Disbursements Service

Handle money transfers and disbursements.

// Single transfer
const transfer = await monnifyService.disbursements.initiateSingleTransfer({
  amount: 1000,
  reference: 'TRF-123',
  narration: 'Transfer to John',
  destinationBankCode: '044',
  destinationAccountNumber: '1234567890',
  destinationAccountName: 'John Doe',
  currency: 'NGN',
  sourceAccountNumber: '0987654321',
});

// Bulk transfer
const bulkTransfer = await monnifyService.disbursements.initiateBulkTransfer({
  title: 'Bulk Transfer',
  batchReference: 'BATCH-123',
  narration: 'Bulk transfer to employees',
  sourceAccountNumber: '0987654321',
  currency: 'NGN',
  onValidationFailure: 'CONTINUE',
  notificationInterval: 30,
  transactions: [
    {
      amount: 1000,
      reference: 'TRF-001',
      narration: 'Transfer to John',
      destinationBankCode: '044',
      destinationAccountNumber: '1234567890',
      destinationAccountName: 'John Doe',
    },
  ],
});

Wallets Service

Manage digital wallets and balance operations.

// Create wallet
const wallet = await monnifyService.wallets.createWallet({
  walletReference: 'WALLET-123',
  walletName: 'John Doe Wallet',
  customerEmail: '[email protected]',
  customerName: 'John Doe',
  currencyCode: 'NGN',
  contractCode: 'your-contract-code',
});

// Get wallet balance
const balance = await monnifyService.wallets.getWalletBalance('WALLET-123');

// Get wallet statement
const statement = await monnifyService.wallets.getWalletStatement({
  walletReference: 'WALLET-123',
  fromDate: '2024-01-01',
  toDate: '2024-12-31',
  pageSize: 10,
  pageNumber: 1,
});

Verification Service

Verify customer information including BVN, bank accounts, and phone numbers.

// Verify BVN
const bvn = await monnifyService.verification.verifyBvn({
  bvn: '12345678901',
  dateOfBirth: '1990-01-01',
});

// Verify bank account
const account = await monnifyService.verification.verifyBankAccount({
  accountNumber: '1234567890',
  bankCode: '044',
});

// Verify phone number
const phone = await monnifyService.verification.verifyPhoneNumber({
  phoneNumber: '+2348012345678',
});

Sub-Accounts Service

Manage sub-accounts for revenue sharing and split payments.

// Create a sub-account
const subAccount = await monnifyService.subAccounts.createSubAccount({
  subAccountCode: 'SUB_001',
  subAccountName: 'Test Sub Account',
  email: '[email protected]',
  mobileNumber: '+2348012345678',
  splitPercentage: 10,
  feePercentage: 2,
  feeBearer: true,
  splitType: 'PERCENTAGE',
  currencyCode: 'NGN',
  contractCode: 'your-contract-code',
});

// Get sub-account details
const details = await monnifyService.subAccounts.getSubAccountDetails('SUB_001');

// Get sub-account balance
const balance = await monnifyService.subAccounts.getSubAccountBalance('SUB_001');

// Get sub-account transactions
const transactions = await monnifyService.subAccounts.getSubAccountTransactions({
  subAccountCode: 'SUB_001',
  pageSize: 10,
  pageNumber: 1,
});

// Deactivate sub-account
const deactivated = await monnifyService.subAccounts.deactivateSubAccount({
  subAccountCode: 'SUB_001',
  reason: 'No longer needed',
});

Invoices Service

Create and manage invoices for your customers.

// Create an invoice
const invoice = await monnifyService.invoices.createInvoice({
  invoiceReference: 'INV_001',
  description: 'Test Invoice',
  amount: 10000,
  currencyCode: 'NGN',
  contractCode: 'your-contract-code',
  customerEmail: '[email protected]',
  customerName: 'John Doe',
  customerPhoneNumber: '+2348012345678',
  expiryDate: '2024-12-31',
  redirectUrl: 'https://example.com/redirect',
  paymentMethods: ['CARD', 'ACCOUNT_TRANSFER'],
  invoiceItems: [
    {
      itemName: 'Test Item',
      description: 'Test item description',
      quantity: 1,
      unitPrice: 10000,
      subTotal: 10000,
      vatRate: 7.5,
      vatAmount: 750,
      totalAmount: 10750,
    },
  ],
});

// Get invoice details
const details = await monnifyService.invoices.getInvoiceDetails('INV_001');

// Get invoice payment status
const status = await monnifyService.invoices.getInvoicePaymentStatus('INV_001');

// Send invoice reminder
const reminder = await monnifyService.invoices.sendInvoiceReminder({
  invoiceReference: 'INV_001',
  message: 'Please complete your payment',
});

// Cancel invoice
const cancelled = await monnifyService.invoices.cancelInvoice({
  invoiceReference: 'INV_001',
  reason: 'Customer requested cancellation',
});

Settlements Service

Manage settlements and payout configurations.

// Get settlements list
const settlements = await monnifyService.settlements.getSettlements({
  pageSize: 10,
  pageNumber: 1,
  fromDate: '2024-01-01',
  toDate: '2024-12-31',
});

// Get settlement summary
const summary = await monnifyService.settlements.getSettlementSummary({
  fromDate: '2024-01-01',
  toDate: '2024-12-31',
});

// Create settlement configuration
const config = await monnifyService.settlements.createSettlementConfiguration({
  bankCode: '044',
  accountNumber: '1234567890',
  accountName: 'Test Account',
  isDefault: true,
});

// Get settlement configurations
const configurations = await monnifyService.settlements.getSettlementConfigurations();

// Initiate settlement payout
const payout = await monnifyService.settlements.initiateSettlementPayout({
  settlementReference: 'SETTLE_001',
  payoutMethod: 'BANK_TRANSFER',
  destinationAccount: '1234567890',
  destinationBankCode: '044',
  destinationAccountName: 'Test Account',
});

Transactions Service

Comprehensive transaction management, monitoring, and analytics.

// Get transaction status
const status = await monnifyService.transactions.getTransactionStatus('TXN_REF_123');

// Get all transactions with filters
const transactions = await monnifyService.transactions.getAllTransactions({
  pageSize: 10,
  pageNumber: 1,
  fromDate: '2024-01-01',
  toDate: '2024-12-31',
  status: 'PAID',
  paymentMethod: 'CARD',
});

// Get transaction logs
const logs = await monnifyService.transactions.getTransactionLogs({
  pageSize: 10,
  pageNumber: 1,
  fromDate: '2024-01-01',
  toDate: '2024-12-31',
});

// Get transactions by status
const successful = await monnifyService.transactions.getSuccessfulTransactions(10, 1);
const failed = await monnifyService.transactions.getFailedTransactions(10, 1);
const pending = await monnifyService.transactions.getPendingTransactions(10, 1);

// Get transactions by payment method
const cardTransactions = await monnifyService.transactions.getTransactionsByPaymentMethod('CARD', 10, 1);

// Get transactions by date range
const dateRangeTransactions = await monnifyService.transactions.getTransactionsByDateRange(
  '2024-01-01',
  '2024-12-31',
  10,
  1
);

// Get transactions by customer email
const customerTransactions = await monnifyService.transactions.getTransactionsByCustomerEmail(
  '[email protected]',
  10,
  1
);

// Verify transaction
const verification = await monnifyService.transactions.verifyTransaction({
  transactionReference: 'TXN_REF_123',
  amount: 10000, // Optional: verify specific amount
});

// Get transaction summary
const summary = await monnifyService.transactions.getTransactionSummary(
  '2024-01-01',
  '2024-12-31'
);

// Get transaction analytics
const analytics = await monnifyService.transactions.getTransactionAnalytics(
  '2024-01-01',
  '2024-12-31'
);

// Refund transactions
const fullRefund = await monnifyService.transactions.refundTransaction({
  transactionReference: 'TXN_REF_123',
  refundAmount: 10000,
  refundReason: 'Customer requested refund',
  customerNote: 'Refund processed as requested',
});

const partialRefund = await monnifyService.transactions.partialRefundTransaction({
  transactionReference: 'TXN_REF_456',
  refundAmount: 5000,
  refundReason: 'Partial refund for damaged item',
  customerNote: 'Partial refund for damaged item',
});

Async Configuration

For dynamic configuration (e.g., from environment variables):

import { ConfigModule, ConfigService } from '@nestjs/config';

@Module({
  imports: [
    ConfigModule.forRoot(),
    MonnifyModule.forRootAsync({
      imports: [ConfigModule],
      useFactory: (configService: ConfigService) => ({
        secretKey: configService.get('MONNIFY_SECRET_KEY'),
        publicKey: configService.get('MONNIFY_PUBLIC_KEY'),
        contractCode: configService.get('MONNIFY_CONTRACT_CODE'),
        environment: configService.get('MONNIFY_ENVIRONMENT'),
      }),
      inject: [ConfigService],
    }),
  ],
})
export class AppModule {}

Error Handling

The package provides comprehensive error handling:

try {
  const result = await monnifyService.collections.initializeTransaction(request);
  // Handle success
} catch (error) {
  if (error.response?.data) {
    // Monnify API error
    console.error('Monnify Error:', error.response.data.responseMessage);
  } else {
    // Network or other error
    console.error('Error:', error.message);
  }
}

Testing

import { Test, TestingModule } from '@nestjs/testing';
import { MonnifyModule } from '@scwar/nestjs-monnify';

describe('PaymentService', () => {
  let service: PaymentService;

  beforeEach(async () => {
    const module: TestingModule = await Test.createTestingModule({
      imports: [
        MonnifyModule.forRoot({
          secretKey: 'test-secret',
          publicKey: 'test-public',
          contractCode: 'test-contract',
          environment: 'sandbox',
        }),
      ],
      providers: [PaymentService],
    }).compile();

    service = module.get<PaymentService>(PaymentService);
  });

  it('should be defined', () => {
    expect(service).toBeDefined();
  });
});

Contributing

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

License

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

Support

• 📖 Monnify API Documentation
• 🐛 Report Issues
• 💬 Discussions

New Services Added

Sub-Accounts Service

• Create Sub-Accounts: Set up sub-accounts for revenue sharing
• Manage Sub-Accounts: Update, deactivate, and reactivate sub-accounts
• Track Transactions: Monitor sub-account transactions and settlements
• Balance Management: Check sub-account balances and statements

Invoices Service

• Invoice Creation: Generate professional invoices with line items
• Invoice Management: Update, cancel, and track invoice status
• Payment Tracking: Monitor invoice payment status and transactions
• Customer Communication: Send reminders and notifications

Settlements Service

• Settlement Tracking: Monitor settlement status and history
• Configuration Management: Set up settlement bank accounts
• Payout Processing: Initiate and track settlement payouts
• Reporting: Generate settlement summaries and reports

Changelog

See CHANGELOG.md for a list of changes and version history.