Skip to main content

Documentation Index

Fetch the complete documentation index at: https://docs.monei.cc/llms.txt

Use this file to discover all available pages before exploring further.

​
Overview

Always validate customer details before making a payment. Validation confirms the customer exists, shows their details, and prevents payment errors. What you’ll learn:
  • Why validation is important
  • Validate customer details
  • Understand validation responses
  • Handle validation errors
  • Best practices

​
Why Validate?

Confirm Customer

Verify customer exists and is active

See Details

View customer name and account info

Prevent Errors

Avoid paying wrong account

Check Balance

See current balance (for postpaid)

​
Validate Customer

Verify customer details before payment. 
import MoneiSDK from 'monei-sdk';

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

// Validate phone number for airtime
const validation = await monei.billsValidation.validate({
  biller: 'mtn',
  customerId: '08012345678',
  type: 'PREPAID'
});

console.log('Validation Result:');
console.log('Customer Name:', validation.customerName);
console.log('Customer ID:', validation.customerId);
console.log('Biller:', validation.billerName);

// Validate meter number for electricity
const meterValidation = await monei.billsValidation.validate({
  biller: 'ikedc-prepaid',
  customerId: '12345678901',
  type: 'PREPAID'
});

console.log('\nMeter Validation:');
console.log('Customer:', meterValidation.customerName);
console.log('Address:', meterValidation.address);
console.log('Meter Number:', meterValidation.customerId);

// Validate smartcard for cable TV
const cardValidation = await monei.billsValidation.validate({
  billerId: 'dstv-ng',
  customerId: '1234567890',
  type: 'PREPAID'
});

console.log('\nSmartcard Validation:');
console.log('Customer:', cardValidation.customerName);
console.log('Current Package:', cardValidation.currentPackage);
console.log('Due Date:', cardValidation.dueDate);
Request Parameters:
ParameterTypeRequiredDescription
billerIdstringYesBiller identifier
customerIdstringYesCustomer ID (phone, meter, smartcard)
typestringYesPREPAID or POSTPAID
Response: 
{
  "statusCode": 200,
  "message": "Customer validated successfully",
  "data": {
    "customerName": "JOHN DOE",
    "customerId": "08012345678",
    "billerName": "MTN Nigeria",
    "billerId": "mtn-ng",
    "type": "PREPAID",
    "validated": true
  }
}

​
Validation by Category

Different categories return different information:
Phone Number Validation
const validation = await monei.billsValidation.validate({
  billerId: 'mtn-ng',
  customerId: '08012345678',
  type: 'PREPAID'
});
Response Fields:
  • customerName - Account holder name
  • customerId - Phone number
  • billerName - Network name
  • validated - true/false
Customer ID Format: 11 digits (0801234567)

​
Complete Validation Flow

async function validateAndPay(billerId, customerId, amount) {
  try {
    // 1. Get biller details
    const billers = await monei.billsDiscovery.getBillers();
    const biller = billers.find(b => b.billerId === billerId);
    
    if (!biller) {
      throw new Error('Biller not found');
    }
    
    console.log('Biller:', biller.name);
    console.log('Fee:', biller.fee);
    console.log('Amount Range:', biller.minAmount, '-', biller.maxAmount);
    
    // 2. Validate customer
    console.log('\nValidating customer...');
    const validation = await monei.billsValidation.validate({
      billerId: biller.billerId,
      customerId: customerId,
      type: biller.type
    });
    
    if (!validation.validated) {
      throw new Error('Customer validation failed');
    }
    
    console.log('✓ Customer validated');
    console.log('Name:', validation.customerName);
    
    // 3. Confirm details
    console.log('\nPayment Summary:');
    console.log('Biller:', validation.billerName);
    console.log('Customer:', validation.customerName);
    console.log('Amount:', amount);
    console.log('Fee:', biller.fee);
    console.log('Total:', amount + biller.fee);
    
    // 4. Make payment (next step)
    console.log('\n✓ Ready to proceed with payment');
    
    return validation;
    
  } catch (error) {
    console.error('Error:', error.message);
    throw error;
  }
}

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

​
Error Handling

Error: Customer ID does not existCommon causes:
  • Wrong phone/meter/card number
  • Incorrect biller selected
  • Inactive account
Solution:
  • Verify customer ID with user
  • Check biller is correct
  • Try different format (with/without prefix)
Error: Customer ID format is invalidFormats by category:
  • Airtime: 11 digits (08012345678)
  • Electricity: 11-13 digits
  • Cable TV: 10 digits
  • Internet: Varies by provider
Solution:
  • Validate format before API call
  • Remove spaces and special characters
  • Check digit count
Error: Biller service temporarily unavailableCauses:
  • Biller system down
  • Maintenance window
  • Network issues
Solution:
  • Retry after a few minutes
  • Try during off-peak hours
  • Check biller status
  • Use alternative biller if available
Error: Validation request timed outSolution:
  • Retry the request
  • Check internet connection
  • Try during off-peak hours
  • Contact support if persists

​
Best Practices

Always Validate

Never skip validation - always verify before payment

Show Customer Name

Display validated name to user for confirmation

Cache Results

Cache validation for few minutes to reduce API calls

Validate Format

Validate customer ID format client-side first

Handle Errors

Provide clear error messages to users

Show Summary

Display payment summary before confirmation

​
Input Validation

Validate customer ID format before API call: 
// Validation helpers
const validators = {
  airtime: (phone) => {
    // Nigerian phone: 11 digits starting with 0
    return /^0[789][01]\d{8}$/.test(phone);
  },
  
  meterNumber: (meter) => {
    // Meter: 11-13 digits
    return /^\d{11,13}$/.test(meter);
  },
  
  smartcard: (card) => {
    // Smartcard: 10 digits
    return /^\d{10}$/.test(card);
  }
};

// Validate before API call
function validateInput(category, customerId) {
  const cleaned = customerId.replace(/\s+/g, '');
  
  switch (category) {
    case 'airtime':
    case 'data':
      if (!validators.airtime(cleaned)) {
        throw new Error('Invalid phone number format. Must be 11 digits (e.g., 08012345678)');
      }
      break;
      
    case 'electricity':
      if (!validators.meterNumber(cleaned)) {
        throw new Error('Invalid meter number. Must be 11-13 digits');
      }
      break;
      
    case 'cable_tv':
      if (!validators.smartcard(cleaned)) {
        throw new Error('Invalid smartcard number. Must be 10 digits');
      }
      break;
  }
  
  return cleaned;
}

// Usage
try {
  const phone = validateInput('airtime', '0801 234 5678');
  console.log('Valid phone:', phone); // 08012345678
  
  const validation = await monei.bills.validate({
    billerId: 'mtn-ng',
    customerId: phone,
    type: 'PREPAID'
  });
} catch (error) {
  console.error('Validation error:', error.message);
}

​
Next Steps

Overview

Bill payments introduction

Discovery

Browse available billers

Payments

Make bill payments

History

View payment history