Skip to main content

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​

#MethodPath
1POST/api/v1/lookup/bill-payment
2POST/api/v1/lookup/money-transfer
3POST/api/v1/lookup/electricity
4POST/api/v1/lookup/mobile-bundle

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"
}
FieldTypeRequiredDescription
accountNumberstringYesThe consumer's account number at the biller
productCodestringYesThe 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"
}
FieldTypeRequiredDescription
accountNumberstring✅The recipient's account number or mobile number
productCodestring✅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"
}
FieldTypeRequiredDescription
meterNumberstring✅The consumer's electricity meter number
productCodestring✅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"
}

4. Mobile Bundle Lookup​

Validate whether a mobile number is eligible for the selected mobile bundle product before purchase.

Path: POST /api/v1/lookup/mobile-bundle

Request Body:

{
  "mobileNumber": "0840012300",
  "productCode": "DAT-XXX-001"
}
FieldTypeRequiredDescription
mobileNumberstring✅Customer mobile number (local 0XXXXXXXXX and 27XXXXXXXXX formats are both supported)
productCodestring✅Pagamio product code for the target bundle
Aggregator-Agnostic Integration

Only send Pagamio productCode and customer mobileNumber. Do not send any provider-specific product IDs, vendor IDs, or endpoint details.

Success Response (200 OK) - Eligible​

{
  "successful": true,
  "message": null,
  "validationStatus": "ELIGIBLE",
  "validationReference": "0",
  "lookUpReceipt": {
    "mobileNumber": "0840012300",
    "amount": 500,
    "dateTime": "2026-08-25T10:16:30+02:00",
    "vendorReference": "0"
  }
}

Success Response (200 OK) - Not Eligible​

{
  "successful": true,
  "message": "The selected mobile number is not eligible for this bundle",
  "validationStatus": "NOT_ELIGIBLE",
  "validationReference": null,
  "lookUpReceipt": {
    "providerMessage": "Mobile number invalid."
  }
}

Success Response (200 OK) - Validation Unavailable​

{
  "successful": true,
  "message": "Pre-vend validation is not supported for this product's provider",
  "validationStatus": "VALIDATION_UNAVAILABLE",
  "validationReference": null,
  "lookUpReceipt": {
    "reason": "Lookup not supported"
  }
}

Error Response (400 Bad Request)​

{
  "timestamp": "2026-08-25T11:18:16.907999",
  "status": "BAD_REQUEST",
  "error": "INVALID_INPUT_MOBILE_NUMBER",
  "errorCode": 1008,
  "message": "Mobile number is required",
  "path": "/api/v1/lookup/mobile-bundle"
}

Response Fields​

FieldTypeDescription
successfulbooleanIndicates whether the lookup was successful
messagestring | nullOptional message, usually null on success
validationStatusstring | nullEligibility outcome for lookup operations that support status semantics (ELIGIBLE, NOT_ELIGIBLE, VALIDATION_UNAVAILABLE)
validationReferencestringA reference token to be used when submitting the purchase transaction
lookUpReceipt.amountnumberOutstanding amount due (in cents), if applicable
lookUpReceipt.billerobjectBiller details: code, name, callCentre
lookUpReceipt.consumerobjectConsumer details: name, accountNo, accountStatus, cellNumber
lookUpReceipt.responseCodenumber0 indicates success
lookUpReceipt.responseMessagestringHuman-readable response status
lookUpReceipt.referencestringLookup transaction reference
lookUpReceipt.transactionDatestringDate and time of the lookup
lookUpReceipt.transactionIdnumberUnique 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: August 2026