Validation

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);

from monei import MoneiClient

monei = MoneiClient(
    api_key=os.getenv('MONEI_API_KEY')
)

# Validate phone number
validation = monei.billsValidation.validate(
    biller_id='mtn-ng',
    customer_id='08012345678',
    type='PREPAID'
)

print('Validation Result:')
print(f'Customer: {validation.customer_name}')
print(f'ID: {validation.customer_id}')
print(f'Biller: {validation.biller_name}')

# Validate meter number
meter_validation = monei.bills_validation.validate(
    biller_id='ikedc-prepaid',
    customer_id='12345678901',
    type='PREPAID'
)

print(f'\nMeter Validation:')
print(f'Customer: {meter_validation.customer_name}')
print(f'Address: {meter_validation.address}')

# Validate smartcard
card_validation = monei.bills_validation.validate(
    biller_id='dstv-ng',
    customer_id='1234567890',
    type='PREPAID'
)

print(f'\nSmartcard:')
print(f'Customer: {card_validation.customer_name}')
print(f'Package: {card_validation.current_package}')

curl -X POST https://api.monei.cc/api/v1/bills/validate \
  -H "x-api-key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "billerId": "mtn-ng",
    "customerId": "08012345678",
    "type": "PREPAID"
  }'

Request Parameters:

Parameter	Type	Required	Description
`billerId`	string	Yes	Biller identifier
`customerId`	string	Yes	Customer ID (phone, meter, smartcard)
`type`	string	Yes	PREPAID 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:

Airtime & Data
Cable TV
Electricity

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)

Smartcard Validation

const validation = await monei.billsValidation.validate({
  billerId: 'dstv-ng',
  customerId: '1234567890',
  type: 'PREPAID'
});

Response Fields:

customerName - Account holder
customerId - Smartcard number
currentPackage - Active package
dueDate - Renewal date
balance - Outstanding balance

Customer ID Format: 10 digits

Meter Number Validation

const validation = await monei.billsValidation.validate({
  billerId: 'ikedc-prepaid',
  customerId: '12345678901',
  type: 'PREPAID'
});

Response Fields:

customerName - Meter owner
customerId - Meter number
address - Service address
accountNumber - Account number
meterType - Meter type
outstandingBalance - Balance (postpaid)

Customer ID Format: 11-13 digits

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);

async def validate_and_pay(biller_id, customer_id, amount):
    try:
        # 1. Get biller
        billers = monei.bills_discovery.get_billers()
        biller = next((b for b in billers if b.biller_id == biller_id), None)
        
        if not biller:
            raise Exception('Biller not found')
        
        print(f'Biller: {biller.name}')
        print(f'Fee: ₦{biller.fee}')
        
        # 2. Validate
        print('\nValidating...')
        validation = monei.bills_validation.validate(
            biller_id=biller.biller_id,
            customer_id=customer_id,
            type=biller.type
        )
        
        if not validation.validated:
            raise Exception('Validation failed')
        
        print('✓ Validated')
        print(f'Name: {validation.customer_name}')
        
        # 3. Summary
        print('\nPayment Summary:')
        print(f'Biller: {validation.biller_name}')
        print(f'Customer: {validation.customer_name}')
        print(f'Amount: ₦{amount}')
        print(f'Fee: ₦{biller.fee}')
        print(f'Total: ₦{amount + biller.fee}')
        
        print('\n✓ Ready to pay')
        
        return validation
        
    except Exception as error:
        print(f'Error: {error}')
        raise

# Usage
await validate_and_pay('mtn-ng', '08012345678', 1000)

Error Handling

Customer Not Found

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)

Invalid Customer ID Format

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

Service Unavailable

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

Validation Timeout

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);
}

import re

# Validators
class CustomerIdValidator:
    @staticmethod
    def airtime(phone):
        # 11 digits starting with 0
        return bool(re.match(r'^0[789][01]\d{8}$', phone))
    
    @staticmethod
    def meter_number(meter):
        # 11-13 digits
        return bool(re.match(r'^\d{11,13}$', meter))
    
    @staticmethod
    def smartcard(card):
        # 10 digits
        return bool(re.match(r'^\d{10}$', card))

# Validate input
def validate_input(category, customer_id):
    # Remove spaces
    cleaned = customer_id.replace(' ', '')
    
    if category in ['airtime', 'data']:
        if not CustomerIdValidator.airtime(cleaned):
            raise ValueError('Invalid phone number')
    
    elif category == 'electricity':
        if not CustomerIdValidator.meter_number(cleaned):
            raise ValueError('Invalid meter number')
    
    elif category == 'cable_tv':
        if not CustomerIdValidator.smartcard(cleaned):
            raise ValueError('Invalid smartcard number')
    
    return cleaned

# Usage
try:
    phone = validate_input('airtime', '0801 234 5678')
    print(f'Valid phone: {phone}')
    
    validation = monei.bills.validate(
        biller_id='mtn-ng',
        customer_id=phone,
        type='PREPAID'
    )
except ValueError as error:
    print(f'Error: {error}')

Next Steps

Overview

Bill payments introduction

Discovery

Browse available billers

Payments

Make bill payments

History

View payment history

Introduction

Core Concepts

Account Management

Naira Wallet

EVM Blockchain

Solana

Offramp (Crypto to Fiat)

Bill Payments

Transactions

Security

Testing

Overview

Why Validate?

Confirm Customer

See Details

Prevent Errors

Check Balance

Validate Customer

Validation by Category

Complete Validation Flow

Error Handling

Best Practices

Always Validate

Show Customer Name

Cache Results

Validate Format

Handle Errors

Show Summary

Input Validation

Next Steps

Overview

Discovery

Payments

History

​Overview

​Why Validate?

Confirm Customer

See Details

Prevent Errors

Check Balance

​Validate Customer

​Validation by Category

​Complete Validation Flow

​Error Handling

​Best Practices

Always Validate

Show Customer Name

Cache Results

Validate Format

Handle Errors

Show Summary

​Input Validation

​Next Steps

Overview

Discovery

Payments

History

Overview

Why Validate?

Validate Customer

Validation by Category

Complete Validation Flow

Error Handling

Best Practices

Input Validation

Next Steps