Account Lookup

Before processing certain transactions, you may need to validate and retrieve details about an account. The Account Lookup endpoints allow you to verify a consumer's account and retrieve relevant information prior to completing a payment or transfer.

Authentication Required: ✅

All requests must include a valid Bearer token in the Authorization header:

Authorization: Bearer <YOUR_BEARER_TOKEN>
Content-Type: application/json

---

Endpoints

#	Method	Path
1	POST	/api/v1/lookup/bill-payment
2	POST	/api/v1/lookup/money-transfer
3	POST	/api/v1/lookup/electricity

---

1. Bill Payment Lookup

Validate a consumer account for a bill payment product before processing the transaction.

Path: POST /api/v1/lookup/bill-payment

Request Body:

{
  "accountNumber": "10000001",
  "productCode": "BIL-XXX-001"
}

Field	Type	Required	Description
accountNumber	string	✅	The consumer's account number at the biller
productCode	string	✅	The product code for the bill payment product

Success Response (200 OK):

{
  "successful": true,
  "message": null,
  "validationReference": "BAL-0000000000001",
  "lookUpReceipt": {
    "amount": 10000,
    "biller": {
      "code": "1001",
      "name": "Example Biller",
      "callCentre": "000 000 0000"
    },
    "consumer": {
      "name": "JANE Smith",
      "accountNo": "10000001",
      "accountStatus": "",
      "cellNumber": ""
    },
    "responseCode": 0,
    "responseMessage": "Success",
    "accountNumber": "0000-0000-0000-0001",
    "reference": "BAL-0000000000001",
    "transactionDate": "01/01/2026 00:00:00 +02:00",
    "transactionId": 1000000001,
    "metadata": {
      "additionalProp1": "string"
    }
  }
}

Error Response (400 Bad Request):

{
  "timestamp": "2026-01-01T00:00:00.000000000",
  "status": "BAD_REQUEST",
  "error": "INVALID_ACCOUNT",
  "errorCode": 1100,
  "message": "The Account is invalid",
  "path": "/api/v1/lookup/bill-payment"
}

---

2. Money Transfer Lookup

Validate a recipient account for a money transfer product before processing the transaction.

Path: POST /api/v1/lookup/money-transfer

Request Body:

{
  "accountNumber": "27821234567",
  "productCode": "MT-EFT-001"
}

Field	Type	Required	Description
accountNumber	string	✅	The recipient's account number or mobile number
productCode	string	✅	The product code for the money transfer product

Success Response (200 OK):

{
  "successful": true,
  "message": null,
  "validationReference": "BAL-0000000000002",
  "lookUpReceipt": {
    "amount": 0,
    "consumer": {
      "name": "JOHN Doe",
      "accountNo": "27821234567",
      "accountStatus": "ACTIVE",
      "cellNumber": "27821234567"
    },
    "responseCode": 0,
    "responseMessage": "Success",
    "accountNumber": "27821234567",
    "reference": "BAL-0000000000002",
    "transactionDate": "01/01/2026 00:00:00 +02:00",
    "transactionId": 1000000002,
    "metadata": {}
  }
}

Error Response (400 Bad Request):

{
  "timestamp": "2026-01-01T00:00:00.000000000",
  "status": "BAD_REQUEST",
  "error": "INVALID_ACCOUNT",
  "errorCode": 1100,
  "message": "The Account is invalid",
  "path": "/api/v1/lookup/money-transfer"
}

---

3. Electricity Lookup

Validate a meter number for an electricity product before purchasing a token.

Path: POST /api/v1/lookup/electricity

Request Body:

{
  "meterNumber": "00000000000",
  "productCode": "ELC-XXX-001"
}

Field	Type	Required	Description
meterNumber	string	✅	The consumer's electricity meter number
productCode	string	✅	The product code for the electricity product

Success Response (200 OK):

{
  "successful": true,
  "message": null,
  "validationReference": "BAL-0000000000003",
  "lookUpReceipt": {
    "amount": 0,
    "biller": {
      "code": "2001",
      "name": "Example Utility",
      "callCentre": "000 000 0000"
    },
    "consumer": {
      "name": "JANE Smith",
      "accountNo": "00000000000",
      "accountStatus": "ACTIVE",
      "cellNumber": ""
    },
    "responseCode": 0,
    "responseMessage": "Success",
    "accountNumber": "00000000000",
    "reference": "BAL-0000000000003",
    "transactionDate": "01/01/2026 00:00:00 +02:00",
    "transactionId": 1000000003,
    "metadata": {}
  }
}

Error Response (400 Bad Request):

{
  "timestamp": "2026-03-31T13:01:13.354121525",
  "status": "BAD_REQUEST",
  "error": "INVALID_METER",
  "errorCode": 1101,
  "message": "The Meter number is invalid",
  "path": "/api/v1/lookup/electricity"
}

---

Response Fields

Field	Type	Description
successful	boolean	Indicates whether the lookup was successful
message	string | null	Optional message, usually null on success
validationReference	string	A reference token to be used when submitting the purchase transaction
lookUpReceipt.amount	number	Outstanding amount due (in cents), if applicable
lookUpReceipt.biller	object	Biller details: code, name, callCentre
lookUpReceipt.consumer	object	Consumer details: name, accountNo, accountStatus, cellNumber
lookUpReceipt.responseCode	number	0 indicates success
lookUpReceipt.responseMessage	string	Human-readable response status
lookUpReceipt.reference	string	Lookup transaction reference
lookUpReceipt.transactionDate	string	Date and time of the lookup
lookUpReceipt.transactionId	number	Unique identifier for the lookup transaction

Use the validationReference

After a successful lookup, pass the returned validationReference as part of your purchase request body (under the additionalInfo field) to link the validation to the transaction.

---

Last updated: March 2026