Skip to main content

​
Overview

Pay bills instantly from your Monei wallet. This guide covers making payments, tracking status, and handling different payment scenarios. What you’ll learn:
  • Make bill payments
  • Track payment status
  • Handle payment responses
  • Retry failed payments
  • Best practices

​
Make Payment

Pay a bill after validating customer details. 
import MoneiSDK from 'monei-sdk';

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

// Pay MTN airtime
const payment = await monei.billsPay.buyElectricity({
  billerId: 'mtn-ng',
  customerId: '08012345678',
  amount: 1000,
  type: 'PREPAID'
});

console.log('Payment Successful!');
console.log('Reference:', payment.reference);
console.log('Status:', payment.status);
console.log('Amount:', payment.amount);
console.log('Fee:', payment.fee);
console.log('Total Paid:', payment.totalAmount);
console.log('Customer:', payment.customerName);
console.log('Biller:', payment.billerName);
Request Parameters:
ParameterTypeRequiredDescription
billerIdstringYesBiller identifier
customerIdstringYesCustomer ID (phone, meter, smartcard)
amountnumberYesPayment amount
typestringYesPREPAID or POSTPAID
referencestringNoCustom reference (auto-generated if not provided)
Response: 
{
  "statusCode": 200,
  "message": "Payment successful",
  "data": {
    "reference": "BILL-ABC123XYZ",
    "status": "successful",
    "amount": 1000,
    "fee": 0,
    "totalAmount": 1000,
    "customerName": "JOHN DOE",
    "customerId": "08012345678",
    "billerName": "MTN Nigeria",
    "billerId": "mtn-ng",
    "type": "PREPAID",
    "createdAt": "2024-02-15T10:30:00Z"
  }
}

​
Complete Payment Flow

async function completeBillPayment(billerId, customerId, amount) {
  try {
    // 1. Validate customer
    console.log('Step 1: Validating customer...');
    const validation = await monei.billsValidation.validate({
      billerId: billerId,
      customerId: customerId,
      type: 'PREPAID'
    });
    
    console.log('✓ Customer validated:', validation.customerName);
    
    // 2. Check wallet balance
    console.log('\nStep 2: Checking balance...');
    const wallet = await monei.wallet.getWallet();
    const balance = parseFloat(wallet.nairaBalance);
    
    if (balance < amount) {
      throw new Error(`Insufficient balance. Have: ₦${balance}, Need: ₦${amount}`);
    }
    
    console.log('✓ Sufficient balance:', balance);
    
    // 3. Confirm payment details
    console.log('\nPayment Summary:');
    console.log('Biller:', validation.billerName);
    console.log('Customer:', validation.customerName);
    console.log('Amount: ₦' + amount);
    
    // 4. Make payment
    console.log('\nStep 3: Processing payment...');
    const payment = await monei.billsPay.buyElectricity({
      billerId: billerId,
      customerId: customerId,
      amount: amount,
      type: 'PREPAID'
    });
    
    console.log('\n✓ Payment successful!');
    console.log('Reference:', payment.reference);
    console.log('Status:', payment.status);
    console.log('Total Paid: ₦' + payment.totalAmount);
    
    return payment;
    
  } catch (error) {
    console.error('Payment failed:', error.message);
    throw error;
  }
}

// Usage
await completeBillPayment('mtn-ng', '08012345678', 1000);

​
Payment by Category

// Buy MTN airtime
const payment = await monei.billsPay.buyAirtime({
  billerId: 'mtn-ng',
  customerId: '08012345678',
  amount: 1000,
  type: 'PREPAID'
});
Processing: Instant (< 10 seconds) Fee: Free Min: ₦50, Max: ₦50,000

​
Payment Status

Monitor payment progress:
StatusDescriptionAction
pendingPayment initiatedWait for processing
processingBeing processedWait for completion
successfulPayment completedService delivered
failedPayment failedCheck error, retry
reversedPayment reversedAmount refunded
// Check payment status
const status = await monei.bills.getPaymentStatus('BILL-ABC123XYZ');

console.log('Payment Status:', status.status);

if (status.status === 'successful') {
  console.log('✓ Payment completed');
  if (status.token) {
    console.log('Electricity Token:', status.token);
  }
} else if (status.status === 'failed') {
  console.log('✗ Payment failed');
  console.log('Reason:', status.failureReason);
} else {
  console.log('⏳ Still processing...');
}

​
Electricity Token

For electricity payments, token is returned in the response: 
// Buy electricity
const payment = await monei.billsPay.buyElectricity({
  billerId: 'ikedc-prepaid',
  customerId: '12345678901',
  amount: 5000,
  type: 'PREPAID'
});

if (payment.status === 'successful' && payment.token) {
  console.log('✓ Payment successful!');
  console.log('\nElectricity Token:');
  console.log('Token:', payment.token);
  console.log('Units:', payment.units, 'kWh');
  console.log('Meter Number:', payment.customerId);
  console.log('Customer:', payment.customerName);
  console.log('Address:', payment.address);
  
  // Display to user or send via SMS/email
  sendTokenToCustomer(payment.token, payment.customerId);
}

​
Error Handling

Error: Wallet balance too lowSolution:
// Check balance before payment
const wallet = await monei.wallet.me();
const balance = parseFloat(wallet.nairaBalance);
const totalCost = amount + fee;

if (balance < totalCost) {
  console.log('Insufficient balance');
  console.log('Need:', totalCost);
  console.log('Have:', balance);
  console.log('Shortage:', totalCost - balance);
  
  // Prompt user to fund wallet
  return;
}
Error: Payment processing failedCommon causes:
  • Biller system down
  • Network issues
  • Invalid customer ID
  • Service unavailable
Solution:
  • Check payment status
  • Amount automatically refunded
  • Retry after few minutes
  • Contact support if persists
Error: Payment already processedCause: Same reference used twicePrevention:
// Generate unique reference
const reference = `BILL-${Date.now()}-${Math.random().toString(36).substr(2, 9)}`;

const payment = await monei.bills.pay({
  billerId: 'mtn-ng',
  customerId: '08012345678',
  amount: 1000,
  type: 'PREPAID',
  reference: reference
});
Error: Biller service temporarily downAction:
  • Retry after 5-10 minutes
  • Try during off-peak hours
  • Use alternative biller if available
  • Check system status

​
Best Practices

Validate First

Always validate customer before payment

Check Balance

Verify sufficient funds before initiating

Save Reference

Keep payment reference for tracking

Show Confirmation

Display success message with details

Handle Errors

Implement proper error handling

Track Status

Monitor payment until successful

​
Next Steps

Overview

Bill payments introduction

Discovery

Browse available billers

Validation

Validate customer details

History

View payment history