Validate an account

The BEEP.validateAccount API function allows a third-party service to validate whether an account is valid. It is similar to the BEEP.queryBill functionality but doesn’t return fields such as bill amount and due date as it is ideal for non-cyclic billing.


countryCodestringCountry ISO code letter, i.e., KE,GH,TZyes
payload.credentials.usernamestringThe username you created on sign-inyes
payload.credentials.passwordstringThe Password you created on sign-inyes
payload.packet.serviceCodestringThis is the product code used in identifying the service the customer is consuming, e.g., TIGOAIRTIMEyes
payload.packet.MSISDNstringThe mobile number of the customer making the payment. The MSISDN should begin with a country code, e.g., 2547xxxxxxxxyes
payload.packet.accountNumberstringAccount number payment is being made. If it’s a mobile number it should begin with a country code, e.g., 2547xxxxxxxxyes
payload.packet.payerTransactionIDstringThe unique transactionIDyes
payload.packet.requestExtraDataobjectAny extra parameterno
    "countryCode": "GH",
    "payload": {
   	 "credentials": {
   		   "username": "testUser",
            "password": "testpass" 
   	 "packet": [{
   		 "serviceCode": "GH-DSTV",
   		 "accountNumber": "222222",
   		 "requestExtraData": {


This function will return a multidimensional array with two parts from the query-receiving client an authStatus section, and a results array section

authStatus.authStatusCodeIntegerStatus code indicating the authentication status of the merchantYes
authStatus.authStatusDescriptionStringA narration/ description for the status code above.Yes
results.statusCodeIntegerStatus code indicating the status of the requestYes
results.statusDescriptionStringA narration/ description for the status code aboveYes
results.serviceIDStringThis is a ​service ID used in identifying the service the customer is consuming, e.g., 101Yes
results.accountNumberStringThe customer account numberYes
results.customerNameStringCustomer’s account name as registered by the merchant/MNOYes
results.responseExtraDataStringAny extra parameter or information you need to pass in a key-value JSON formatNo
  "authStatus": {
    "authStatusCode": 131,
    "authStatusDescription": "Authentication was a success"
  "results": [
      "statusCode": 307,
      "statusDescription": "Account number provided is valid",
      "serviceID": "1650",
      "accountNumber": "260771000063",
      "active": "yes",
      "customerName": "John Doe",
      "responseExtraData": ""

Status codes returned from the BEEP.validateAccountAPI function:

Authentication status codes

131Client authenticated successfully
132Client authentication failed
174Generic failure status code matching the appropriate description

Transactional Status Codes

167Invalid service, Service access is not configured for Partner to use
200Action on the client profile account was successful. This is a success status for creating, deleting, and updating a client profile account
301Validation feature not available. Validation is not set up for this service
306Invalid Account Number. The merchant does not recognize this account number
307The account number provided is valid. The Merchant recognizes the account number provided
308Bill info available. The merchant has a bill for the account.
Click Try It! to start a request and see the response here!