Skip to main content

​
Bills

All merchant bill endpoints use API keys for server-to-server requests. Include businessId in the request body when using x-api-key.

​
Test vs Production Behavior

  • Production key -> uses the live merchant wallet and live provider flow.
  • Test key -> uses the sandbox merchant wallet and simulated provider flow.
In test mode:
  • verification endpoints return simulated success responses
  • purchase endpoints complete without vending real services
  • no real provider outbox jobs are queued

​
Verify Electricity Meter

POST /business/bills/verify-meter

​
Request Body

{
  "electricity": "ikeja-electric",
  "meterNumber": "12345678901",
  "type": "prepaid"
}

​
Response (Production)

{
  "success": true,
  "code": "020",
  "msg": "METER NUMBER CONFIRMED",
  "accountName": "JOHN DOE"
}

​
Response (Test Key)

{
  "success": true,
  "code": "020",
  "msg": "Meter number confirmed",
  "simulated": true,
  "environment": "test",
  "accountName": "TEST 12345678901"
}

​
Verify TV Smart Card

POST /business/bills/verify-smart-card

​
Response (Test Key)

{
  "success": true,
  "code": "020",
  "msg": "BILLER CONFIRMED",
  "simulated": true,
  "environment": "test",
  "smartCardInfo": {
    "customerName": "TEST 1234567890",
    "renewalAmount": null
  }
}

​
Verify Betting Account

POST /business/bills/verify-bet

​
Response (Test Key)

{
  "success": true,
  "msg": "Validation Successful",
  "simulated": true,
  "environment": "test",
  "data": {
    "status": "00",
    "customerId": "12345678",
    "bettingPlatform": "sportybet",
    "customerName": "TEST 12345678"
  }
}

​
Buy Airtime

POST /business/bills/airtime

​
Response (Production)

{
  "success": true,
  "msg": "Airtime purchase queued successfully",
  "transactionId": "NEXA-...",
  "environment": "prod",
  "simulated": false
}

​
Response (Test Key)

{
  "success": true,
  "msg": "Test airtime purchase completed successfully",
  "transactionId": "NEXA-...",
  "environment": "test",
  "simulated": true
}

​
Buy Data

POST /business/bills/data

​
Response (Test Key)

{
  "success": true,
  "msg": "Test data purchase completed successfully",
  "transactionId": "NEXA-...",
  "environment": "test",
  "simulated": true
}

​
Buy Electricity

POST /business/bills/electricity

​
Response (Test Key)

{
  "success": true,
  "msg": "Test electricity purchase completed successfully",
  "transactionId": "NEXA-...",
  "environment": "test",
  "simulated": true
}

​
Renew TV Subscription

POST /business/bills/tv

​
Response (Test Key)

{
  "success": true,
  "msg": "Test TV subscription completed successfully",
  "transactionId": "NEXA-...",
  "environment": "test",
  "simulated": true
}

​
Fund Betting Wallet

POST /business/bills/bet

​
Response (Test Key)

{
  "success": true,
  "msg": "Test bet funding completed successfully",
  "transactionId": "NEXA-...",
  "environment": "test",
  "simulated": true
}

​
Common Error Example

{
  "success": false,
  "msg": "Insufficient balance or concurrent operation"
}