Management

Overview

Track all your transactions across Naira wallet, crypto, offramp, and bill payments in one unified interface. This guide covers transaction management, monitoring, and reporting. What you’ll learn:

Get all transactions
View transaction details
Track transaction status
Search and filter
Export transaction data

Transaction Types

Monei supports multiple transaction types:

Naira

Deposits, payouts, transfers

Crypto

EVM and Solana transactions

Offramp

Crypto to fiat conversions

Bill Payments

Airtime, data, utilities

Swaps

Token swaps on DEXs

P2P

Peer-to-peer transfers

Get All Transactions

Retrieve all your transactions across all types.

import MoneiSDK from 'monei-sdk';

const monei = new MoneiSDK({
  apiKey: process.env.MONEI_API_KEY,
});

// Get all transactions
const transactions = await monei.transactions.getUserTransactions({
  page: 1,
  limit: 20,
  sortBy: 'createdAt',
  sortOrder: 'desc'
});

console.log(`Total Transactions: ${transactions.pagination.total}\n`);

transactions.transactions.forEach(tx => {
  console.log(`${tx.type} - ₦${tx.amount} ${tx.currency}`);
  console.log(`  Status: ${tx.status}`);
  console.log(`  Reference: ${tx.reference}`);
  console.log(`  Date: ${new Date(tx.createdAt).toLocaleString()}`);
  console.log(`  Narration: ${tx.narration || 'N/A'}`);
  console.log('');
});

Query Parameters:

Parameter	Type	Description	Default
`page`	number	Page number	1
`limit`	number	Items per page (max: 100)	10
`status`	string	Filter by status	All
`type`	string	Filter by type	All
`currency`	string	Filter by currency	All
`minAmount`	number	Minimum amount	None
`maxAmount`	number	Maximum amount	None
`startDate`	string	Start date (YYYY-MM-DD)	None
`endDate`	string	End date (YYYY-MM-DD)	None
`sortBy`	string	Sort field	createdAt
`sortOrder`	string	asc or desc	desc

Response:

{
  "statusCode": 200,
  "message": "Transactions retrieved successfully",
  "data": {
    "transactions": [
      {
        "id": "tx_abc123",
        "reference": "TXN-ABC123XYZ",
        "type": "DEBIT",
        "status": "SUCCESS",
        "amount": 5000,
        "currency": "NGN",
        "narration": "MTN Airtime Purchase",
        "metadata": {
          "billerId": "mtn-ng",
          "customerName": "JOHN DOE"
        },
        "createdAt": "2024-02-15T10:30:00Z",
        "updatedAt": "2024-02-15T10:30:05Z"
      }
    ],
    "pagination": {
      "page": 1,
      "limit": 20,
      "total": 150,
      "pages": 8
    }
  }
}

Transaction Types

Type	Description	Example
`DEBIT`	Money leaving your wallet	Bill payment, payout, transfer out
`CREDIT`	Money entering your wallet	Deposit, refund, transfer in
`PEER-TRANSFER`	P2P transfer	Send/receive from other users
`SWAP`	Token exchange	DEX swap on EVM/Solana
`OFFRAMP`	Crypto to fiat	USDT to NGN conversion

Transaction Status

Understanding transaction states:

Status	Description	Final State
`PENDING`	Transaction initiated	No
`PROCESSING`	Being processed	No
`SUCCESS`	Completed successfully	Yes
`COMPLETED`	Fully completed	Yes
`FAILED`	Transaction failed	Yes
`REVERSED`	Reversed/refunded	Yes
`CANCELLED`	Cancelled by user	Yes

Get Transaction by ID

Retrieve specific transaction details.

// Get transaction by ID
const transaction = await monei.transactions.getById('tx_abc123');

console.log('Transaction Details:');
console.log('===================');
console.log('ID:', transaction.id);
console.log('Reference:', transaction.reference);
console.log('Type:', transaction.type);
console.log('Status:', transaction.status);
console.log('Amount:', transaction.amount, transaction.currency);
console.log('Narration:', transaction.narration);
console.log('Created:', new Date(transaction.createdAt).toLocaleString());
console.log('Updated:', new Date(transaction.updatedAt).toLocaleString());

// Check metadata for additional info
if (transaction.metadata) {
  console.log('\nMetadata:');
  console.log(JSON.stringify(transaction.metadata, null, 2));
}

// For blockchain transactions
if (transaction.metadata?.signature || transaction.metadata?.txHash) {
  console.log('\nBlockchain Details:');
  console.log('Hash:', transaction.metadata.signature || transaction.metadata.txHash);
  console.log('Network:', transaction.metadata.network || transaction.metadata.chainId);
}

Get Transaction by Reference

Retrieve transaction using your custom reference.

// Get by reference
const transaction = await monei.transactions.getByReference('TXN-ABC123XYZ');

console.log('Transaction found!');
console.log('ID:', transaction.id);
console.log('Reference:', transaction.reference);
console.log('Status:', transaction.status);
console.log('Amount:', transaction.amount, transaction.currency);

Filter Transactions

Filter transactions by various criteria.

// Get successful transactions only
const successful = await monei.transactions.getUserTransactions({
  status: 'SUCCESS',
  limit: 20
});

console.log('Successful Transactions:', successful.pagination.total);

// Get debit transactions (money out)
const debits = await monei.transactions.getUserTransactions({
  type: 'DEBIT',
  limit: 20
});

console.log('Debit Transactions:', debits.pagination.total);

// Get credit transactions (money in)
const credits = await monei.transactions.getUserTransactions({
  type: 'CREDIT',
  limit: 20
});

console.log('Credit Transactions:', credits.pagination.total);

// Get transactions by currency
const usdTransactions = await monei.transactions.getUserTransactions({
  currency: 'USD',
  limit: 20
});

console.log('USD Transactions:', usdTransactions.pagination.total);

// Get transactions by amount range
const largeTransactions = await monei.transactions.getUserTransactions({
  minAmount: 10000,
  maxAmount: 100000,
  limit: 20
});

console.log('Large Transactions (₦10K-₦100K):', largeTransactions.pagination.total);

// Get transactions by date range
const thisMonth = await monei.transactions.getUserTransactions({
  startDate: '2024-02-01',
  endDate: '2024-02-29',
  limit: 100
});

console.log('This Month:', thisMonth.pagination.total);

Transaction Analytics

Analyze your transaction patterns.

async function analyzeTransactions(startDate, endDate) {
  // Get all transactions
  const txns = await monei.transactions.getUserTransactions({
    startDate: startDate,
    endDate: endDate,
    limit: 1000
  });
  
  const analytics = {
    total: txns.pagination.total,
    totalIn: 0,
    totalOut: 0,
    byType: {},
    byCurrency: {},
    byStatus: {},
    largestTransaction: null
  };
  
  // Process each transaction
  txns.transactions.forEach(tx => {
    // Calculate in/out
    if (tx.type === 'CREDIT') {
      analytics.totalIn += tx.amount;
    } else if (tx.type === 'DEBIT') {
      analytics.totalOut += tx.amount;
    }
    
    // By type
    analytics.byType[tx.type] = (analytics.byType[tx.type] || 0) + 1;
    
    // By currency
    analytics.byCurrency[tx.currency] = 
      (analytics.byCurrency[tx.currency] || 0) + tx.amount;
    
    // By status
    analytics.byStatus[tx.status] = (analytics.byStatus[tx.status] || 0) + 1;
    
    // Largest transaction
    if (!analytics.largestTransaction || tx.amount > analytics.largestTransaction.amount) {
      analytics.largestTransaction = tx;
    }
  });
  
  // Calculate net
  analytics.net = analytics.totalIn - analytics.totalOut;
  
  // Display
  console.log('Transaction Analytics');
  console.log('====================');
  console.log('Total Transactions:', analytics.total);
  console.log('Total In: ₦' + analytics.totalIn.toLocaleString());
  console.log('Total Out: ₦' + analytics.totalOut.toLocaleString());
  console.log('Net: ₦' + analytics.net.toLocaleString());
  
  console.log('\nBy Type:');
  Object.entries(analytics.byType).forEach(([type, count]) => {
    console.log(`  ${type}: ${count}`);
  });
  
  console.log('\nBy Currency:');
  Object.entries(analytics.byCurrency).forEach(([currency, amount]) => {
    console.log(`  ${currency}: ${amount.toLocaleString()}`);
  });
  
  console.log('\nBy Status:');
  Object.entries(analytics.byStatus).forEach(([status, count]) => {
    console.log(`  ${status}: ${count}`);
  });
  
  console.log('\nLargest Transaction:');
  console.log(`  ${analytics.largestTransaction.type}: ${analytics.largestTransaction.amount} ${analytics.largestTransaction.currency}`);
  console.log(`  ${analytics.largestTransaction.narration}`);
  
  return analytics;
}

// Analyze this month
await analyzeTransactions('2024-02-01', '2024-02-29');

Export Transactions

Export transaction data for accounting or reporting.

async function exportToCSV(startDate, endDate) {
  const txns = await monei.transactions.getUserTransactions({
    startDate: startDate,
    endDate: endDate,
    limit: 1000
  });
  
  // CSV headers
  const headers = [
    'Date',
    'Reference',
    'Type',
    'Status',
    'Amount',
    'Currency',
    'Narration'
  ];
  
  // CSV rows
  const rows = txns.transactions.map(tx => [
    new Date(tx.createdAt).toISOString(),
    tx.reference,
    tx.type,
    tx.status,
    tx.amount,
    tx.currency,
    tx.narration || ''
  ]);
  
  // Combine
  const csv = [
    headers.join(','),
    ...rows.map(row => row.map(field => `"${field}"`).join(','))
  ].join('\n');
  
  // Save
  const fs = require('fs');
  fs.writeFileSync('transactions.csv', csv);
  
  console.log('Exported', txns.transactions.length, 'transactions');
  
  return csv;
}

// Export this month
await exportToCSV('2024-02-01', '2024-02-29');

Best Practices

Use Pagination

Don’t fetch all transactions at once - use pagination

Filter Wisely

Use filters to reduce response size and improve performance

Save References

Always save transaction references for tracking

Monitor Status

Check pending transactions regularly

Export Regularly

Export transaction history for accounting

Use Webhooks

Set up webhooks for real-time updates

Next Steps

Filtering

Advanced filtering and search

Naira Wallet

Manage Naira transactions

EVM Blockchain

View crypto transactions

Bill Payments

View bill payment history

Introduction

Core Concepts

Account Management

Naira Wallet

EVM Blockchain

Solana

Offramp (Crypto to Fiat)

Bill Payments

Transactions

Security

Testing

Overview

Transaction Types

Naira

Crypto

Offramp

Bill Payments

Swaps

P2P

Get All Transactions

Transaction Types

Transaction Status

Get Transaction by ID

Get Transaction by Reference

Filter Transactions

Transaction Analytics

Export Transactions

Best Practices

Use Pagination

Filter Wisely

Save References

Monitor Status

Export Regularly

Use Webhooks

Next Steps

Filtering

Naira Wallet

EVM Blockchain

Bill Payments

Introduction

Core Concepts

Account Management

Naira Wallet

EVM Blockchain

Solana

Offramp (Crypto to Fiat)

Bill Payments

Transactions

Security

Testing

​Overview

​Transaction Types

Naira

Crypto

Offramp

Bill Payments

Swaps

P2P

​Get All Transactions

​Transaction Types

​Transaction Status

​Get Transaction by ID

​Get Transaction by Reference

​Filter Transactions

​Transaction Analytics

​Export Transactions

​Best Practices

Use Pagination

Filter Wisely

Save References

Monitor Status

Export Regularly

Use Webhooks

​Next Steps

Filtering

Naira Wallet

EVM Blockchain

Bill Payments

Overview

Transaction Types

Get All Transactions

Transaction Types

Transaction Status

Get Transaction by ID

Get Transaction by Reference

Filter Transactions

Transaction Analytics

Export Transactions

Best Practices

Next Steps