Back to API Reference

Services & Billers Endpoints

These endpoints allow you to interact with various services available on the Mopay platform, including fetching service categories, billers, bill payment options, and processing payments. Users can check available services, verify customer information, and make payments for various services such as airtime, internet, utilities, and more.

Get Service Categories

Retrieve available service categories

GET

Description

This endpoint retrieves all available service categories supported by the Mopay platform. Categories represent the different types of services that users can pay for, such as airtime, data, electricity, cable TV, and more.

Each category contains an ID that can be used in subsequent calls to fetch billers within that category. Categories also include display information like name, description, and icon URL for UI representation.

This endpoint is typically used to populate the initial service selection screen in the application, allowing users to browse available service types.

Authentication is required for this endpoint. You must include the required HMAC-based authentication headers as described in the Authentication section.

Headers

NameValueRequiredDescription
MPY-SECUREKEY{public_key}YesYour public key obtained during login/registration
MPY-TIMESTAMP{unix_timestamp}YesCurrent unix timestamp in seconds
MPY-REQSIGNAL{request_signature}YesHMAC-SHA512 signature of the request
Content-Typeapplication/jsonYesFormat of the request body

Request Example

GET /service_category_fetch

Body:

{}

Success Response

{
  "REQUEST": {
    "VERSION": "1.0",
    "ACTION": "service_category_fetch",
    "STATUS": "OK"
  },
  "DATA": [
    {
      "marker": "cat_airtime_001",
      "name": "Airtime",
      "description": "Mobile airtime top-up services",
      "categoryId": "cat_airtime",
      "iconUrl": "https://mopay-ng.com/icons/airtime.png",
      "status": "active",
      "recorded": "1689251247"
    },
    {
      "marker": "cat_data_002",
      "name": "Mobile Data",
      "description": "Mobile data bundle subscriptions",
      "categoryId": "cat_data",
      "iconUrl": "https://mopay-ng.com/icons/data.png",
      "status": "active",
      "recorded": "1689251248"
    },
    {
      "marker": "cat_electricity_003",
      "name": "Electricity",
      "description": "Electricity bill payments",
      "categoryId": "cat_electricity",
      "iconUrl": "https://mopay-ng.com/icons/electricity.png",
      "status": "active",
      "recorded": "1689251249"
    }
  ]
}

Possible Error Responses

{
  "REQUEST": {
    "VERSION": "1.0",
    "ACTION": "service_category_fetch",
    "STATUS": "FAILED"
  },
  "ERRORS": {
    "CODE": 401,
    "DETAILS": "Access Denied (MPS308033155841273)"
  }
}
{
  "REQUEST": {
    "VERSION": "1.0",
    "ACTION": "service_category_fetch",
    "STATUS": "FAILED"
  },
  "ERRORS": {
    "CODE": 500,
    "DETAILS": "Failed to fetch Service Category list (MPS262526042726272)"
  }
}

Get Service Billers

Retrieve available billers for a service category

GET

Description

This endpoint retrieves the list of available billers (service providers) within a specified service category. For example, when the category is "electricity", this will return a list of electricity providers like IKEDC, EKEDC, etc.

The response includes details about each biller such as their name, logo, and unique identifier. The biller ID obtained from this endpoint is required for subsequent API calls like fetching biller items or making payments.

You must provide a valid category ID in the request parameters, which can be obtained from the Get Service Categories endpoint.

Authentication is required for this endpoint. You must include the required HMAC-based authentication headers as described in the Authentication section.

Headers

NameValueRequiredDescription
MPY-SECUREKEY{public_key}YesYour public key obtained during login/registration
MPY-TIMESTAMP{unix_timestamp}YesCurrent unix timestamp in seconds
MPY-REQSIGNAL{request_signature}YesHMAC-SHA512 signature of the request
Content-Typeapplication/jsonYesFormat of the request body

Query Parameters

NameTypeRequiredDescription
rqtpstringYesThe type of billers to fetch (transaction, owner, mk, all)
rqvlstringNoSearch value corresponding to the rqtp (marker ID, category ID, or product code). Default: "false"

Request Example

GET /service_biller_fetch?rqtp=owner&rqvl=cat_airtime

Body:

{}

Success Response

{
  "REQUEST": {
    "VERSION": "1.0",
    "ACTION": "service_biller_fetch",
    "STATUS": "OK"
  },
  "DATA": [
    {
      "marker": "biller_mtn_001",
      "billerType": "telco",
      "payProductId": "1001",
      "billerName": "MTN Nigeria",
      "shortName": "MTN",
      "narration": "MTN Nigeria Airtime and Data",
      "networkId": "MTN-NG",
      "productCode": "MTN-AIRTIME",
      "customField1": "",
      "customField2": "",
      "billerLogo": "https://mopay-ng.com/logos/mtn.png",
      "surcharge": 0,
      "currencyCode": "NGN",
      "currencySymbol": "₦",
      "supportEmail": "support@mtn.com.ng",
      "categoryId": "cat_airtime",
      "categoryName": "Airtime",
      "status": "active",
      "recorded": "1689251250"
    },
    {
      "marker": "biller_airtel_002",
      "billerType": "telco",
      "payProductId": "1002",
      "billerName": "Airtel Nigeria",
      "shortName": "Airtel",
      "narration": "Airtel Nigeria Airtime and Data",
      "networkId": "AIRTEL-NG",
      "productCode": "AIRTEL-AIRTIME",
      "customField1": "",
      "customField2": "",
      "billerLogo": "https://mopay-ng.com/logos/airtel.png",
      "surcharge": 0,
      "currencyCode": "NGN",
      "currencySymbol": "₦",
      "supportEmail": "support@airtel.com.ng",
      "categoryId": "cat_airtime",
      "categoryName": "Airtime",
      "status": "active",
      "recorded": "1689251251"
    }
  ]
}

Possible Error Responses

{
  "REQUEST": {
    "VERSION": "1.0",
    "ACTION": "service_biller_fetch",
    "STATUS": "FAILED"
  },
  "ERRORS": {
    "CODE": 401,
    "DETAILS": "Access Denied (MPS308033155841273)"
  }
}
{
  "REQUEST": {
    "VERSION": "1.0",
    "ACTION": "service_biller_fetch",
    "STATUS": "FAILED"
  },
  "ERRORS": {
    "ID": "rqtp_required",
    "CODE": 400,
    "DETAILS": "Request type is required (MPS216252952615282)"
  }
}
{
  "REQUEST": {
    "VERSION": "1.0",
    "ACTION": "service_biller_fetch",
    "STATUS": "FAILED"
  },
  "ERRORS": {
    "ID": "rqtp_required",
    "CODE": 400,
    "DETAILS": "Unsupported request type (MPS261522288725262)"
  }
}
{
  "REQUEST": {
    "VERSION": "1.0",
    "ACTION": "service_biller_fetch",
    "STATUS": "FAILED"
  },
  "ERRORS": {
    "CODE": 404,
    "DETAILS": "We are unable to find data matching your request (MPS262718047262555)"
  }
}

Get Biller Items

Retrieve available items/packages for a specific biller

GET

Description

This endpoint retrieves the list of available items (packages or products) offered by a specific biller. For example, for a TV subscription biller, it would return the different subscription packages available.

Each item includes details such as name, price, description, and a unique identifier. The item ID obtained from this endpoint is required when making a bill payment through the Service Bill Payment endpoint.

You must provide a valid biller ID in the request parameters, which can be obtained from the Get Service Billers endpoint.

Authentication is required for this endpoint. You must include the required HMAC-based authentication headers as described in the Authentication section.

Headers

NameValueRequiredDescription
MPY-SECUREKEY{public_key}YesYour public key obtained during login/registration
MPY-TIMESTAMP{unix_timestamp}YesCurrent unix timestamp in seconds
MPY-REQSIGNAL{request_signature}YesHMAC-SHA512 signature of the request
Content-Typeapplication/jsonYesFormat of the request body

Query Parameters

NameTypeRequiredDescription
rqtpstringYesThe type of biller item to fetch (code, owner, mk, all)
rqvlstringNoSearch value corresponding to the rqtp (item ID, biller ID, or item code). Default: "false"

Request Example

GET /service_biller_item_fetch?rqtp=owner&rqvl=biller_dstv

Body:

{}

Success Response

{
  "REQUEST": {
    "VERSION": "1.0",
    "ACTION": "service_biller_item_fetch",
    "STATUS": "OK"
  },
  "DATA": [
    {
      "marker": "item_mtn_data_1gb_001",
      "billerId": "biller_mtn_001",
      "itemName": "MTN 1GB Data Plan",
      "itemCode": "MTN-DATA-1GB",
      "amount": 1000,
      "isAmountFixed": true,
      "paymentCode": "mtn_data_1gb",
      "commissionType": "percentage",
      "commissionValue": 1.5,
      "validationType": "phone",
      "validationParams": "required|numeric|min:11|max:11",
      "currencyCode": "NGN",
      "currencySymbol": "₦",
      "paymentItemId": "PI_MTN_DATA_1GB",
      "sortOrder": 1,
      "status": "active",
      "recorded": "1689251260"
    },
    {
      "marker": "item_mtn_data_2gb_002",
      "billerId": "biller_mtn_001",
      "itemName": "MTN 2GB Data Plan",
      "itemCode": "MTN-DATA-2GB",
      "amount": 2000,
      "isAmountFixed": true,
      "paymentCode": "mtn_data_2gb",
      "commissionType": "percentage",
      "commissionValue": 1.5,
      "validationType": "phone",
      "validationParams": "required|numeric|min:11|max:11",
      "currencyCode": "NGN",
      "currencySymbol": "₦",
      "paymentItemId": "PI_MTN_DATA_2GB",
      "sortOrder": 2,
      "status": "active",
      "recorded": "1689251261"
    }
  ]
}

Possible Error Responses

{
  "REQUEST": {
    "VERSION": "1.0",
    "ACTION": "service_biller_item_fetch",
    "STATUS": "FAILED"
  },
  "ERRORS": {
    "CODE": 401,
    "DETAILS": "Access Denied (MPS308033155841273)"
  }
}
{
  "REQUEST": {
    "VERSION": "1.0",
    "ACTION": "service_biller_item_fetch",
    "STATUS": "FAILED"
  },
  "ERRORS": {
    "ID": "rqtp_required",
    "CODE": 400,
    "DETAILS": "Request type is required (MPS624250952615262)"
  }
}
{
  "REQUEST": {
    "VERSION": "1.0",
    "ACTION": "service_biller_item_fetch",
    "STATUS": "FAILED"
  },
  "ERRORS": {
    "ID": "rqtp_required",
    "CODE": 400,
    "DETAILS": "Unsupported request type (MPS251728282526272)"
  }
}
{
  "REQUEST": {
    "VERSION": "1.0",
    "ACTION": "service_biller_item_fetch",
    "STATUS": "FAILED"
  },
  "ERRORS": {
    "CODE": 404,
    "DETAILS": "We are unable to find data matching your request (MPS262526242526272)"
  }
}

Verify Customer

Verify customer information before bill payment

POST

Description

This endpoint verifies a customer's details with a service provider before processing a bill payment. It helps to confirm that the account or customer number provided is valid and returns customer information registered with the service provider.

For some services, verification is mandatory before payment to ensure the payment is directed to the correct account. The verification process also helps to reduce errors and failed transactions.

The response includes customer details such as name, account status, and any outstanding balance where applicable. For some services, it may also include additional information specific to that service.

Authentication is required for this endpoint. You must include the required HMAC-based authentication headers as described in the Authentication section.

Headers

NameValueRequiredDescription
MPY-SECUREKEY{public_key}YesYour public key obtained during login/registration
MPY-TIMESTAMP{unix_timestamp}YesCurrent unix timestamp in seconds
MPY-REQSIGNAL{request_signature}YesHMAC-SHA512 signature of the request
Content-Typeapplication/jsonYesFormat of the request body

Request Body Parameters

NameTypeRequiredDescription
pcodestringYesPayment code for the service
ctmidstringYesCustomer ID to verify (e.g., meter number, account number, phone number)

Request Example

POST /service_customer_verify

Body:

{
  "pcode": "ikeja_electric_prepaid",
  "ctmid": "45721934752"
}

Success Response

{
  "REQUEST": {
    "VERSION": "1.0",
    "ACTION": "service_customer_verify",
    "STATUS": "OK"
  },
  "DATA": {
    "status": "SUCCESSFUL",
    "responseCode": "00",
    "responseDescription": "Success",
    "customerId": "45721934752",
    "customerName": "John Doe",
    "customerAddress": "123 Lagos Street, Ikeja",
    "customerEmail": "john.doe@example.com",
    "customerMobile": "08012345678",
    "dueDate": "2023-07-30",
    "amount": 0,
    "exchangeReference": "ver_1234567890abcdef",
    "miscData": {
      "accountType": "Prepaid",
      "meterNumber": "45721934752"
    }
  }
}

Possible Error Responses

{
  "REQUEST": {
    "VERSION": "1.0",
    "ACTION": "service_customer_verify",
    "STATUS": "FAILED"
  },
  "ERRORS": {
    "CODE": 401,
    "DETAILS": "Access Denied (MPS308033155841273)"
  }
}
{
  "REQUEST": {
    "VERSION": "1.0",
    "ACTION": "service_customer_verify",
    "STATUS": "FAILED"
  },
  "ERRORS": {
    "ID": "pcode_required",
    "CODE": 400,
    "DETAILS": "Payment code is required for customer verification (MPS725162854725162)"
  }
}
{
  "REQUEST": {
    "VERSION": "1.0",
    "ACTION": "service_customer_verify",
    "STATUS": "FAILED"
  },
  "ERRORS": {
    "ID": "ctmid_required",
    "CODE": 400,
    "DETAILS": "Customer ID is required for verification (MPS829361527381920)"
  }
}
{
  "REQUEST": {
    "VERSION": "1.0",
    "ACTION": "service_customer_verify",
    "STATUS": "FAILED"
  },
  "ERRORS": {
    "CODE": 404,
    "DETAILS": "Unable to verify customer ID. Please try again later. (MPS623417582918275)"
  }
}

Airtime Purchase

Purchase airtime for mobile phones

POST

Description

This endpoint allows users to purchase airtime for mobile phones across different network providers. The payment is deducted from the user's wallet balance.

Upon successful request, the system processes the airtime purchase and returns a transaction ID and status. The status can be "completed" or "pending" depending on the processing time of the telecom provider.

Users must have sufficient balance in their wallet to complete the transaction, and the phone number should be in the correct format including the country code.

Authentication is required for this endpoint. You must include the required HMAC-based authentication headers as described in the Authentication section.

Headers

NameValueRequiredDescription
MPY-SECUREKEY{public_key}YesYour public key obtained during login/registration
MPY-TIMESTAMP{unix_timestamp}YesCurrent unix timestamp in seconds
MPY-REQSIGNAL{request_signature}YesHMAC-SHA512 signature of the request
Content-Typeapplication/jsonYesFormat of the request body

Request Body Parameters

NameTypeRequiredDescription
amountnumberYesAmount of airtime to purchase
phonestringYesPhone number to recharge
providerstringYesNetwork provider code
rechargeTypestringNoType of recharge, either "vtu" (default) or "epin"

Request Example

POST /service_airtime_purchase

Body:

{
  "amount": 500,
  "phone": "08012345678",
  "provider": "MTN",
  "rechargeType": "vtu"
}

Success Response

{
  "REQUEST": {
    "VERSION": "1.0",
    "ACTION": "service_airtime_purchase",
    "STATUS": "OK"
  },
  "DATA": {
    "status": "SUCCESSFUL",
    "responseCode": "00",
    "responseDescription": "Success",
    "requestReference": "MOPAY-AT-12345678",
    "exchangeReference": "TP-REF-98765432",
    "miscData": {
      "transactionId": "trx_abcdef123456",
      "provider": "MTN",
      "phoneNumber": "08012345678",
      "amount": 500
    }
  }
}

Possible Error Responses

{
  "REQUEST": {
    "VERSION": "1.0",
    "ACTION": "service_airtime_purchase",
    "STATUS": "FAILED"
  },
  "ERRORS": {
    "CODE": 401,
    "DETAILS": "Access Denied (MPS308033155841273)"
  }
}
{
  "REQUEST": {
    "VERSION": "1.0",
    "ACTION": "service_airtime_purchase",
    "STATUS": "FAILED"
  },
  "ERRORS": {
    "ID": "amount_required",
    "CODE": 400,
    "DETAILS": "Amount is required for airtime purchase"
  }
}
{
  "REQUEST": {
    "VERSION": "1.0",
    "ACTION": "service_airtime_purchase",
    "STATUS": "FAILED"
  },
  "ERRORS": {
    "ID": "phone_required",
    "CODE": 400,
    "DETAILS": "Phone number is required for airtime purchase"
  }
}
{
  "REQUEST": {
    "VERSION": "1.0",
    "ACTION": "service_airtime_purchase",
    "STATUS": "FAILED"
  },
  "ERRORS": {
    "ID": "provider_required",
    "CODE": 400,
    "DETAILS": "Provider is required for airtime purchase"
  }
}
{
  "REQUEST": {
    "VERSION": "1.0",
    "ACTION": "service_airtime_purchase",
    "STATUS": "FAILED"
  },
  "ERRORS": {
    "CODE": 400,
    "DETAILS": "Insufficient funds to complete this transfer (MPS291627232516272)"
  }
}

Service Bill Payment

Pay bills for various service providers using wallet funds

POST

Description

This endpoint allows users to pay bills for various service providers such as electricity, water, internet, TV subscriptions, and more. The payment is deducted directly from the user's wallet balance.

Upon successful payment, the system returns a transaction ID, receipt number, and any tokens or vouchers provided by the service provider (if applicable). For prepaid services like electricity, the token will be included in the response.

The user must have sufficient balance in their wallet to complete the transaction. Service categories and billers can be retrieved using the respective endpoints.

Authentication is required for this endpoint. You must include the required HMAC-based authentication headers as described in the Authentication section.

Headers

NameValueRequiredDescription
MPY-SECUREKEY{public_key}YesYour public key obtained during login/registration
MPY-TIMESTAMP{unix_timestamp}YesCurrent unix timestamp in seconds
MPY-REQSIGNAL{request_signature}YesHMAC-SHA512 signature of the request
Content-Typeapplication/jsonYesFormat of the request body

Request Body Parameters

NameTypeRequiredDescription
amountnumberYesAmount to pay
customerIdstringYesCustomer ID or account number
paymentCodestringYesService payment code
customerEmailstringNoCustomer email address
customerMobilestringNoCustomer mobile number
billerNamestringNoName of the biller for record-keeping
billerItemstringNoName of the biller item for record-keeping

Request Example

POST /service_bill_payment

Body:

{
  "amount": 5000,
  "customerId": "45721934752",
  "paymentCode": "ikeja_electric_prepaid",
  "customerEmail": "customer@example.com",
  "customerMobile": "08012345678",
  "billerName": "Ikeja Electric",
  "billerItem": "Prepaid Meter Recharge"
}

Success Response

{
  "REQUEST": {
    "VERSION": "1.0",
    "ACTION": "service_bill_payment",
    "STATUS": "OK"
  },
  "DATA": {
    "status": "SUCCESSFUL",
    "responseCode": "00",
    "responseDescription": "Success",
    "miscData": {
      "receiptNo": "MOPAY-BP-12345678",
      "token": "1234-5678-9012-3456-7890",
      "units": "106.35 kWh",
      "exchangeReference": "TP-REF-87654321"
    }
  }
}

Possible Error Responses

{
  "REQUEST": {
    "VERSION": "1.0",
    "ACTION": "service_bill_payment",
    "STATUS": "FAILED"
  },
  "ERRORS": {
    "CODE": 401,
    "DETAILS": "Access Denied (MPS308033155841273)"
  }
}
{
  "REQUEST": {
    "VERSION": "1.0",
    "ACTION": "service_bill_payment",
    "STATUS": "FAILED"
  },
  "ERRORS": {
    "ID": "amount_required",
    "CODE": 400,
    "DETAILS": "Missing required parameters for bill payment"
  }
}
{
  "REQUEST": {
    "VERSION": "1.0",
    "ACTION": "service_bill_payment",
    "STATUS": "FAILED"
  },
  "ERRORS": {
    "ID": "customerId_required",
    "CODE": 400,
    "DETAILS": "Missing required parameters for bill payment"
  }
}
{
  "REQUEST": {
    "VERSION": "1.0",
    "ACTION": "service_bill_payment",
    "STATUS": "FAILED"
  },
  "ERRORS": {
    "ID": "paymentCode_required",
    "CODE": 400,
    "DETAILS": "Missing required parameters for bill payment"
  }
}
{
  "REQUEST": {
    "VERSION": "1.0",
    "ACTION": "service_bill_payment",
    "STATUS": "FAILED"
  },
  "ERRORS": {
    "CODE": 400,
    "DETAILS": "Insufficient funds to complete this transfer (MPS261526228252612)"
  }
}
{
  "REQUEST": {
    "VERSION": "1.0",
    "ACTION": "service_bill_payment",
    "STATUS": "FAILED"
  },
  "ERRORS": {
    "CODE": 500,
    "DETAILS": "Failed to process bill payment"
  }
}