Skip to main content

​
Overview

Track all your bill payments, view receipts, and analyze spending patterns. This guide covers accessing payment history and generating reports. What you’ll learn:
  • Get payment history
  • Filter by category
  • Search payments
  • View payment details
  • Export records

​
Get Payment History

Retrieve all your bill payments. 
import MoneiSDK from 'monei-sdk';

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

// Get all bill payments
const payments = await monei.billsRecords.getBills({
  page: 1,
  limit: 20
});

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

payments.data.forEach(payment => {
  console.log(`${payment.billerName} - ₦${payment.amount}`);
  console.log(`  Customer: ${payment.customerName}`);
  console.log(`  Status: ${payment.status}`);
  console.log(`  Date: ${new Date(payment.createdAt).toLocaleString()}`);
  console.log(`  Reference: ${payment.reference}`);
  console.log('');
});
Query Parameters:
ParameterTypeDescription
pagenumberPage number (default: 1)
limitnumberItems per page (default: 10, max: 100)
statusstringFilter by status (successful, failed, pending)
categorystringFilter by category (airtime, data, cable_tv, etc.)
startDatestringStart date (YYYY-MM-DD)
endDatestringEnd date (YYYY-MM-DD)
billerIdstringFilter by biller
Response: 
{
  "statusCode": 200,
  "message": "Payment history retrieved successfully",
  "data": [
    {
      "reference": "BILL-ABC123XYZ",
      "status": "successful",
      "amount": 1000,
      "fee": 0,
      "totalAmount": 1000,
      "billerName": "MTN Nigeria",
      "billerId": "mtn-ng",
      "category": "airtime",
      "customerName": "JOHN DOE",
      "customerId": "08012345678",
      "type": "PREPAID",
      "createdAt": "2024-02-15T10:30:00Z"
    }
  ],
  "pagination": {
    "page": 1,
    "limit": 20,
    "total": 150,
    "pages": 8
  }
}

​
Filter by Category

Get payments for specific bill category. 
// Get airtime payments
const airtimePayments = await monei.billsRecords.getBills({
  category: 'airtime',
  limit: 10
});

console.log('Airtime Payments:\n');
airtimePayments.data.forEach(p => {
  console.log(`${p.billerName}: ₦${p.amount} to ${p.customerId}`);
  console.log(`  Date: ${new Date(p.createdAt).toLocaleDateString()}`);
});

// Get electricity payments
const electricityPayments = await monei.billsRecords.getBills({
  category: 'electricity',
  limit: 10
});

console.log('\nElectricity Payments:\n');
electricityPayments.data.forEach(p => {
  console.log(`${p.billerName}: ₦${p.amount}`);
  console.log(`  Meter: ${p.customerId}`);
  console.log(`  Token: ${p.token || 'N/A'}`);
});

// Get cable TV payments
const cablePayments = await monei.billsRecords.getBills({
  category: 'cable_tv',
  limit: 10
});

console.log('\nCable TV Payments:\n');
cablePayments.data.forEach(p => {
  console.log(`${p.billerName}: ₦${p.amount}`);
  console.log(`  Smartcard: ${p.customerId}`);
  console.log(`  Package: ${p.packageName || 'N/A'}`);
});

​
Filter by Date Range

Get payments within a specific period. 
// Get this month's payments
const thisMonth = await monei.billsRecords.getBills({
  startDate: '2024-02-01',
  endDate: '2024-02-29'
});

console.log(`Payments in February: ${thisMonth.pagination.total}`);

// Calculate total spent
const totalSpent = thisMonth.data.reduce((sum, p) => 
  p.status === 'successful' ? sum + p.totalAmount : sum, 0
);

console.log(`Total Spent: ₦${totalSpent.toLocaleString()}`);

// Group by category
const byCategory = {};
thisMonth.data.forEach(p => {
  if (p.status === 'successful') {
    byCategory[p.category] = (byCategory[p.category] || 0) + p.totalAmount;
  }
});

console.log('\nSpending by Category:');
Object.entries(byCategory).forEach(([category, amount]) => {
  console.log(`${category}: ₦${amount.toLocaleString()}`);
});

​
Get Payment Details

Retrieve detailed information about a specific payment. 
// Get payment by reference
const payment = await monei.billsRecords.getBillByReference('BILL-ABC123XYZ');

console.log('Payment Details:');
console.log('================');
console.log('Reference:', payment.reference);
console.log('Status:', payment.status);
console.log('Biller:', payment.billerName);
console.log('Category:', payment.category);
console.log('Customer:', payment.customerName);
console.log('Customer ID:', payment.customerId);
console.log('Amount:', payment.amount);
console.log('Fee:', payment.fee);
console.log('Total:', payment.totalAmount);
console.log('Type:', payment.type);
console.log('Date:', new Date(payment.createdAt).toLocaleString());

// Show category-specific details
if (payment.category === 'electricity' && payment.token) {
  console.log('\nElectricity Details:');
  console.log('Token:', payment.token);
  console.log('Units:', payment.units, 'kWh');
  console.log('Meter:', payment.customerId);
}

if (payment.category === 'cable_tv' && payment.packageName) {
  console.log('\nCable TV Details:');
  console.log('Package:', payment.packageName);
  console.log('Smartcard:', payment.customerId);
  console.log('Renewal Date:', payment.renewalDate);
}

​
Spending Analytics

Analyze your bill payment patterns. 
async function analyzeSpending(startDate, endDate) {
  const payments = await monei.billsRecords.getBills({

    startDate: startDate,
    endDate: endDate,
    status: 'successful',
    limit: 1000
  });
  
  const analytics = {
    totalSpent: 0,
    totalPayments: payments.pagination.total,
    byCategory: {},
    byBiller: {},
    averageAmount: 0,
    largestPayment: null,
    mostFrequentBiller: null
  };
  
  // Process payments
  payments.data.forEach(p => {
    // Total spent
    analytics.totalSpent += p.totalAmount;
    
    // By category
    analytics.byCategory[p.category] = 
      (analytics.byCategory[p.category] || 0) + p.totalAmount;
    
    // By biller
    analytics.byBiller[p.billerName] = {
      count: (analytics.byBiller[p.billerName]?.count || 0) + 1,
      amount: (analytics.byBiller[p.billerName]?.amount || 0) + p.totalAmount
    };
    
    // Largest payment
    if (!analytics.largestPayment || p.totalAmount > analytics.largestPayment.amount) {
      analytics.largestPayment = {
        reference: p.reference,
        biller: p.billerName,
        amount: p.totalAmount,
        date: p.createdAt
      };
    }
  });
  
  // Average
  analytics.averageAmount = analytics.totalSpent / analytics.totalPayments;
  
  // Most frequent
  const billerCounts = Object.entries(analytics.byBiller)
    .sort((a, b) => b[1].count - a[1].count);
  analytics.mostFrequentBiller = billerCounts[0];
  
  // Display
  console.log('Spending Analytics');
  console.log('==================');
  console.log('Total Spent:', `₦${analytics.totalSpent.toLocaleString()}`);
  console.log('Total Payments:', analytics.totalPayments);
  console.log('Average Amount:', `₦${analytics.averageAmount.toFixed(2)}`);
  
  console.log('\nBy Category:');
  Object.entries(analytics.byCategory).forEach(([cat, amt]) => {
    console.log(`  ${cat}: ₦${amt.toLocaleString()}`);
  });
  
  console.log('\nMost Frequent Biller:');
  console.log(`  ${analytics.mostFrequentBiller[0]}`);
  console.log(`  Payments: ${analytics.mostFrequentBiller[1].count}`);
  console.log(`  Total: ₦${analytics.mostFrequentBiller[1].amount.toLocaleString()}`);
  
  console.log('\nLargest Payment:');
  console.log(`  ${analytics.largestPayment.biller}: ₦${analytics.largestPayment.amount.toLocaleString()}`);
  console.log(`  Date: ${new Date(analytics.largestPayment.date).toLocaleDateString()}`);
  
  return analytics;
}

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

​
Export History

Export payment history for record-keeping. 
async function exportToCSV(startDate, endDate) {
  const payments = await monei.bills.getHistory({
    startDate: startDate,
    endDate: endDate,
    limit: 1000
  });
  
  // CSV headers
  const headers = [
    'Date',
    'Reference',
    'Biller',
    'Category',
    'Customer',
    'Customer ID',
    'Amount',
    'Fee',
    'Total',
    'Status'
  ];
  
  // CSV rows
  const rows = payments.data.map(p => [
    new Date(p.createdAt).toLocaleDateString(),
    p.reference,
    p.billerName,
    p.category,
    p.customerName,
    p.customerId,
    p.amount,
    p.fee,
    p.totalAmount,
    p.status
  ]);
  
  // Combine
  const csv = [
    headers.join(','),
    ...rows.map(row => row.join(','))
  ].join('\n');
  
  // Save to file
  const fs = require('fs');
  fs.writeFileSync('bill-payments.csv', csv);
  
  console.log('Exported', payments.data.length, 'payments to bill-payments.csv');
  
  return csv;
}

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

​
Best Practices

Regular Reviews

Review payment history monthly

Save Receipts

Keep payment references for important bills

Track Spending

Monitor spending patterns by category

Export Records

Export history for accounting/tax purposes

Check Failed

Review failed payments and reasons

Reconcile

Match payments with bank statements

​
Next Steps

Overview

Bill payments introduction

Discovery

Browse available billers

Validation

Validate customer details

Payments

Make bill payments