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
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:
Parameter Type Required Description billerIdstring Yes Biller identifier customerIdstring Yes Customer ID (phone, meter, smartcard) amountnumber Yes Payment amount typestring Yes PREPAID or POSTPAID referencestring No Custom 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 ( ' \n Step 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 ( ' \n Payment Summary:' );
console . log ( 'Biller:' , validation . billerName );
console . log ( 'Customer:' , validation . customerName );
console . log ( 'Amount: ₦' + amount );
// 4. Make payment
console . log ( ' \n Step 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
Airtime
Data
Cable TV
Electricity
// 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// Buy MTN data bundle
const payment = await monei . billsPay . buyMobileData ({
billerId: 'mtn-data-ng' ,
customerId: '08012345678' ,
amount: 1000 ,
type: 'PREPAID' ,
packageCode: 'MTN-1GB-MONTHLY'
});
Processing: Instant (< 30 seconds)
Fee: Free
Bundles: Varies by network// Renew DStv subscription
const payment = await monei . billsPay . subscribeCableTv ({
billerId: 'dstv-ng' ,
customerId: '1234567890' ,
amount: 10500 ,
type: 'PREPAID' ,
packageCode: 'dstv-compact'
});
Processing: 1-5 minutes
Fee: ₦50-₦100
Plans: Multiple packages// Buy IKEDC prepaid units
const payment = await monei . billsPay . buyElectricity ({
billerId: 'ikedc-prepaid' ,
customerId: '12345678901' ,
amount: 5000 ,
type: 'PREPAID'
});
Processing: 1-10 minutes
Fee: Free
Min: ₦1,000, Max: ₦500,000
Token: Returned in response
Payment Status
Monitor payment progress:
Status Description Action pendingPayment initiated Wait for processing processingBeing processed Wait for completion successfulPayment completed Service delivered failedPayment failed Check error, retry reversedPayment reversed Amount refunded
// Check payment status
const status = await monei . billsRecord . getBillByReference ( '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 ( ' \n Electricity 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 . account . 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 . billsPay . buyAirtime ({
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