Payments

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

from monei import MoneiClient

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

# Make payment
payment = monei.bills_pay.buy_electricity(
    biller_id='mtn-ng',
    customer_id='08012345678',
    amount=1000,
    type='PREPAID'
)

print('Payment Successful!')
print(f'Reference: {payment.reference}')
print(f'Status: {payment.status}')
print(f'Amount: ₦{payment.amount}')
print(f'Fee: ₦{payment.fee}')
print(f'Total: ₦{payment.total_amount}')

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

Request Parameters:

Parameter	Type	Required	Description
`billerId`	string	Yes	Biller identifier
`customerId`	string	Yes	Customer ID (phone, meter, smartcard)
`amount`	number	Yes	Payment amount
`type`	string	Yes	PREPAID or POSTPAID
`reference`	string	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('\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);

async def complete_bill_payment(biller_id, customer_id, amount):
    try:
        # 1. Validate
        print('Step 1: Validating...')
        validation = monei.bills_validation.validate(
            biller_id=biller_id,
            customer_id=customer_id,
            type='PREPAID'
        )
        
        print(f'✓ Validated: {validation.customer_name}')
        
        # 2. Check balance
        print('\nStep 2: Checking balance...')
        wallet = monei.wallet.getWallet()
        balance = float(wallet.nairaBalance)
        
        if balance < amount:
            raise Exception(f'Insufficient balance')
        
        print(f'✓ Balance: ₦{balance}')
        
        # 3. Summary
        print('\nPayment Summary:')
        print(f'Biller: {validation.biller_name}')
        print(f'Customer: {validation.customer_name}')
        print(f'Amount: ₦{amount}')
        
        # 4. Pay
        print('\nStep 3: Processing...')
        payment = monei.bills_pay.buy_electricity(
            biller_id=biller_id,
            customer_id=customer_id,
            amount=amount,
            type='PREPAID'
        )
        
        print(f'\n✓ Successful!')
        print(f'Reference: {payment.reference}')
        print(f'Total: ₦{payment.total_amount}')
        
        return payment
        
    except Exception as error:
        print(f'Failed: {error}')
        raise

# Usage
await complete_bill_payment('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
`pending`	Payment initiated	Wait for processing
`processing`	Being processed	Wait for completion
`successful`	Payment completed	Service delivered
`failed`	Payment failed	Check error, retry
`reversed`	Payment 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...');
}

# Check status
status = monei.bills_Record.get_bill_by_reference('BILL-ABC123XYZ')

print(f'Status: {status.status}')

if status.status == 'successful':
    print('✓ Completed')
    if status.token:
        print(f'Token: {status.token}')
elif status.status == 'failed':
    print('✗ Failed')
    print(f'Reason: {status.failure_reason}')
else:
    print('⏳ 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);
}

# Buy electricity
payment = monei.bills_pay.buy_electricity(
    biller_id='ikedc-prepaid',
    customer_id='12345678901',
    amount=5000,
    type='PREPAID'
)

if payment.status == 'successful' and payment.token:
    print('✓ Successful!\n')
    print('Electricity Token:')
    print(f'Token: {payment.token}')
    print(f'Units: {payment.units} kWh')
    print(f'Meter: {payment.customer_id}')
    print(f'Customer: {payment.customer_name}')
    
    # Send to customer
    send_token_to_customer(payment.token)

Error Handling

Insufficient Balance

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

Payment Failed

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

Duplicate Payment

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

Service Unavailable

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

Introduction

Core Concepts

Account Management

Naira Wallet

EVM Blockchain

Solana

Offramp (Crypto to Fiat)

Bill Payments

Transactions

Security

Testing

Overview

Make Payment

Complete Payment Flow

Payment by Category

Payment Status

Electricity Token

Error Handling

Best Practices

Validate First

Check Balance

Save Reference

Show Confirmation

Handle Errors

Track Status

Next Steps

Overview

Discovery

Validation

History

​Overview

​Make Payment

​Complete Payment Flow

​Payment by Category

​Payment Status

​Electricity Token

​Error Handling

​Best Practices

Validate First

Check Balance

Save Reference

Show Confirmation

Handle Errors

Track Status

​Next Steps

Overview

Discovery

Validation

History

Overview

Make Payment

Complete Payment Flow

Payment by Category

Payment Status

Electricity Token

Error Handling

Best Practices

Next Steps