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",
      "billerId": "biller_mtn_001",
      "productCount": 0,
      "transactions": 0,
      "tradeRevenue": 0,
      "tradeVolume": 0,
      "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",
      "billerId": "biller_airtel_002",
      "productCount": 0,
      "transactions": 0,
      "tradeRevenue": 0,
      "tradeVolume": 0,
      "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,
      "itemId": "item_mtn_data_1gb_001",
      "billerName": "MTN Nigeria",
      "consumerField": "phone",
      "billerType": "telco",
      "itemFee": 0,
      "itemAmount": 0,
      "categoryId": "cat_airtime",
      "pictureId": "pic_mtn_data_1gb_001",
      "ussdShortCode": "",
      "amountType": 0,
      "canPayAnyAmount": true,
      "minimumAmount": "1000",
      "maximumAmount": "10000",
      "expectedAmount": "1000",
      "formattedDescription": "MTN 1GB Data Plan",
      "lastUpdated": "1689251260",
      "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,
      "itemId": "item_mtn_data_2gb_002",
      "billerName": "MTN Nigeria",
      "consumerField": "phone",
      "billerType": "telco",
      "itemFee": 0,
      "itemAmount": 0,
      "categoryId": "cat_airtime",
      "pictureId": "pic_mtn_data_1gb_001",
      "ussdShortCode": "",
      "amountType": 0,
      "canPayAnyAmount": true,
      "minimumAmount": "1000",
      "maximumAmount": "10000",
      "expectedAmount": "1000",
      "formattedDescription": "MTN 1GB Data Plan",
      "lastUpdated": "1689251260",
      "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.

Note: This operation is not available for test accounts.

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
billerIdstringYesUnique identifier for the biller/service provider
categorystringYesCategory tag for the service type
billerNamestringYesName of the biller/service provider
billerItemstringYesSpecific item/package offered by the biller
rechargeTypestringNoType of recharge, either "vtu" (default) or "epin"
itemIdstringNoSpecific identifier for the item if different from billerItem

Request Example

POST /service_airtime_purchase

Body:

{
  "amount": 500,
  "phone": "08012345678",
  "provider": "MTN",
  "billerId": "BIL122",
  "category": "airtime",
  "billerName": "MTN Nigeria",
  "billerItem": "MTN VTU",
  "rechargeType": "vtu",
  "itemId": "AIR001"
}

Success Response

{
  "REQUEST": {
    "VERSION": "1.0",
    "ACTION": "service_airtime_purchase",
    "STATUS": "OK"
  },
  "DATA": {
    "orderId": "3dd676456f7576",
    "COMMENT": "Airtime purchase initiated successfully!"
  }
}

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 (MPS271625293627182)"
  }
}
{
  "REQUEST": {
    "VERSION": "1.0",
    "ACTION": "service_airtime_purchase",
    "STATUS": "FAILED"
  },
  "ERRORS": {
    "ID": "phone_required",
    "CODE": 400,
    "DETAILS": "Phone number is required for airtime purchase (MPS291026292716225)"
  }
}
{
  "REQUEST": {
    "VERSION": "1.0",
    "ACTION": "service_airtime_purchase",
    "STATUS": "FAILED"
  },
  "ERRORS": {
    "ID": "billerId_required",
    "CODE": 400,
    "DETAILS": "Biller ID is required for airtime purchase (MPS216616192918262)"
  }
}
{
  "REQUEST": {
    "VERSION": "1.0",
    "ACTION": "service_airtime_purchase",
    "STATUS": "FAILED"
  },
  "ERRORS": {
    "ID": "category_required",
    "CODE": 400,
    "DETAILS": "Category Tag is required for airtime purchase (MPS271646292819203)"
  }
}
{
  "REQUEST": {
    "VERSION": "1.0",
    "ACTION": "service_airtime_purchase",
    "STATUS": "FAILED"
  },
  "ERRORS": {
    "ID": "billerName_required",
    "CODE": 400,
    "DETAILS": "Biller Name is required for airtime purchase (MPS216252692817262)"
  }
}
{
  "REQUEST": {
    "VERSION": "1.0",
    "ACTION": "service_airtime_purchase",
    "STATUS": "FAILED"
  },
  "ERRORS": {
    "ID": "billerItem_required",
    "CODE": 400,
    "DETAILS": "Biller Item is required for airtime purchase (MPS216272899732526)"
  }
}
{
  "REQUEST": {
    "VERSION": "1.0",
    "ACTION": "service_airtime_purchase",
    "STATUS": "FAILED"
  },
  "ERRORS": {
    "CODE": 400,
    "DETAILS": "Oops, this operation is not available for test accounts (MPS218453912217654)"
  }
}
{
  "REQUEST": {
    "VERSION": "1.0",
    "ACTION": "service_airtime_purchase",
    "STATUS": "FAILED"
  },
  "ERRORS": {
    "CODE": 400,
    "DETAILS": "Insufficient funds to complete this transfer (MPS291627232516272)"
  }
}
{
  "REQUEST": {
    "VERSION": "1.0",
    "ACTION": "service_airtime_purchase",
    "STATUS": "FAILED"
  },
  "ERRORS": {
    "CODE": 500,
    "DETAILS": "Could not process your request (MPS2617252927182922)"
  }
}

Implementation Notes

  • All biller information (billerId, category, billerName, billerItem) can be retrieved from the service_biller_item_fetch endpoint
  • The amount must be within the allowed range for the specific network provider
  • The phone number should follow the format specific to the country (e.g., "08012345678" for Nigeria)
  • This endpoint is not available for test accounts

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.

Note: This operation is not available for test accounts.

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
itemIdstringYesUnique identifier for the specific service item
billerIdstringYesUnique identifier for the biller/service provider
categorystringYesCategory tag for the service type
billerNamestringYesName of the biller for record-keeping
billerItemstringYesName of the biller item for record-keeping
customerAddressstringNoCustomer service address which is provided via the service_customer_verify endpoint
customerMobilestringNoCustomer mobile number
customerNamestringNoCustomer name provided via the service_customer_verify endpoint

Request Example

POST /service_bill_payment

Body:

{
  "amount": 5000,
  "customerId": "45721934752",
  "paymentCode": "ikeja_electric_prepaid",
  "itemId": "IKJ001",
  "billerId": "BIL456",
  "category": "electricity",
  "billerName": "Ikeja Electric",
  "billerItem": "Prepaid Meter Recharge",
  "customerAddress": "123 Main St, Anytown, USA",
  "customerMobile": "08012345678",
  "customerName": "John Doe"
}

Success Response

{
  "REQUEST": {
    "VERSION": "1.0",
    "ACTION": "service_bill_payment",
    "STATUS": "OK"
  },
  "DATA": {
    "orderId": "3dd676456f7576",
    "COMMENT": "Bill service payment initiated successfully!"
  }
}

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": "Amount is required for bill payment (MPS291026292716272)"
  }
}
{
  "REQUEST": {
    "VERSION": "1.0",
    "ACTION": "service_bill_payment",
    "STATUS": "FAILED"
  },
  "ERRORS": {
    "ID": "customer_id_required",
    "CODE": 400,
    "DETAILS": "Customer ID is required for bill payment (MPS282261592728291)"
  }
}
{
  "REQUEST": {
    "VERSION": "1.0",
    "ACTION": "service_bill_payment",
    "STATUS": "FAILED"
  },
  "ERRORS": {
    "ID": "itemId_required",
    "CODE": 400,
    "DETAILS": "Item ID is required for bill payment (MPS2716293725162)"
  }
}
{
  "REQUEST": {
    "VERSION": "1.0",
    "ACTION": "service_bill_payment",
    "STATUS": "FAILED"
  },
  "ERRORS": {
    "ID": "billerId_required",
    "CODE": 400,
    "DETAILS": "Biller ID is required for bill payment (MPS281926562182725)"
  }
}
{
  "REQUEST": {
    "VERSION": "1.0",
    "ACTION": "service_bill_payment",
    "STATUS": "FAILED"
  },
  "ERRORS": {
    "ID": "category_required",
    "CODE": 400,
    "DETAILS": "Category Tag is required for bill payment (MPS217265299218265)"
  }
}
{
  "REQUEST": {
    "VERSION": "1.0",
    "ACTION": "service_bill_payment",
    "STATUS": "FAILED"
  },
  "ERRORS": {
    "ID": "billerName_required",
    "CODE": 400,
    "DETAILS": "Biller Name is required for bill payment (MPS271822292216252)"
  }
}
{
  "REQUEST": {
    "VERSION": "1.0",
    "ACTION": "service_bill_payment",
    "STATUS": "FAILED"
  },
  "ERRORS": {
    "ID": "billerItem_required",
    "CODE": 400,
    "DETAILS": "Biller Item is required for bill payment (MPS217226899832236)"
  }
}
{
  "REQUEST": {
    "VERSION": "1.0",
    "ACTION": "service_bill_payment",
    "STATUS": "FAILED"
  },
  "ERRORS": {
    "CODE": 400,
    "DETAILS": "Oops, this operation is not available for test accounts (MPS201753913726145)"
  }
}
{
  "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": "Could not process your request (MPS172262262928111)"
  }
}

Implementation Notes

  • All biller information (billerId, category, billerName, billerItem, itemId) can be retrieved from the service_biller_item_fetch endpoint
  • It's recommended to verify the customer ID using the service_customer_verify endpoint before making a payment
  • The amount must match the expected payment amount for the service
  • The customer's email defaults to the logged-in user's email if not provided
  • This endpoint is not available for test accounts

Service Transactions

Retrieve the transaction history of a user's service payments

GET

Description

This endpoint fetches the user's service transaction history including airtime purchases, bill payments, and other service transactions. Results can be filtered by user ID or marker ID.

Each transaction record includes details such as transaction type, amount, reference ID, biller information, customer information, and transaction status. This information is useful for building transaction history views and for service transaction reconciliation.

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 service transactions to fetch (user, user_full, mk)
rqvlstringYesSearch value corresponding to the rqtp (user ID or marker ID)
pagestringNoPagination marker for fetching next set of records (default: "false")
pnumnumberNoNumber of records to return per page (default: 10)

Request Example

GET /service_transaction_fetch?rqtp=user&rqvl=usr_12345abcde&pnum=10

Body:

{}

Success Response

{
  "REQUEST": {
    "VERSION": "1.0",
    "ACTION": "service_transaction_fetch",
    "STATUS": "OK"
  },
  "DATA": [
    {
      "marker": "svc_12345abcde",
      "userid": "usr_12345abcde",
      "tx_type": "airtime",
      "tx_amount": 500,
      "tx_reference": "REF123456789",
      "payment_code": "PAY123456789",
      "customer_id": "0801234567",
      "customer_email": "user@example.com",
      "customer_mobile": "08012345678",
      "itemId": "itm_12345abcde",
      "billerId": "BIL123",
      "categoryTag": "TELECOM",
      "biller_name": "MTN Nigeria",
      "biller_item": "MTN Airtime",
      "response_code": "00",
      "response_message": "Successful",
      "recharge_pin": "",
      "misc_data": "{}",
      "status": "completed",
      "recorded": "1686744645"
    },
    {
      "marker": "svc_67890fghij",
      "userid": "usr_12345abcde",
      "tx_type": "electricity",
      "tx_amount": 5000,
      "tx_reference": "REF987654321",
      "payment_code": "PAY987654321",
      "customer_id": "1234567890",
      "customer_email": "user@example.com",
      "customer_mobile": "08012345678",
      "itemId": "itm_67890fghij",
      "billerId": "BIL456",
      "categoryTag": "UTILITY",
      "biller_name": "IKEDC",
      "biller_item": "IKEDC Prepaid",
      "response_code": "00",
      "response_message": "Successful",
      "recharge_pin": "12345678901234567890",
      "misc_data": "{\"token\":\"1234-5678-9012-3456\"}",
      "status": "completed",
      "recorded": "1686833450"
    }
  ]
}

Possible Error Responses

{
  "REQUEST": {
    "VERSION": "1.0",
    "ACTION": "service_transaction_fetch",
    "STATUS": "FAILED"
  },
  "ERRORS": {
    "CODE": 401,
    "DETAILS": "Access Denied (MPS308033155841273)"
  }
}
{
  "REQUEST": {
    "VERSION": "1.0",
    "ACTION": "service_transaction_fetch",
    "STATUS": "FAILED"
  },
  "ERRORS": {
    "ID": "rqtp_required",
    "CODE": 400,
    "DETAILS": "Query type is required (MPS289932752617259)"
  }
}
{
  "REQUEST": {
    "VERSION": "1.0",
    "ACTION": "service_transaction_fetch",
    "STATUS": "FAILED"
  },
  "ERRORS": {
    "ID": "rqvl_required",
    "CODE": 400,
    "DETAILS": "Query value is required (MPS282754754383754)"
  }
}
{
  "REQUEST": {
    "VERSION": "1.0",
    "ACTION": "service_transaction_fetch",
    "STATUS": "FAILED"
  },
  "ERRORS": {
    "ID": "rqtp_required",
    "CODE": 400,
    "DETAILS": "Unsupported query type (MPS281726252526272)"
  }
}
{
  "REQUEST": {
    "VERSION": "1.0",
    "ACTION": "service_transaction_fetch",
    "STATUS": "FAILED"
  },
  "ERRORS": {
    "CODE": 404,
    "DETAILS": "Could not process your request (MPS251625193252652)"
  }
}