API Usage Notes for Mpesa Lookup

1. Case Sensitivity on MMO ID

The :mmoId path parameter (e.g., "Mpesa") is case-sensitive.
If you pass MPESA or mpesa, the request will fail with the E422022 error ("not supported at the moment").

2. Shortcodes / Till Numbers

Ensure you use the correct endpoint for the correct type of number:

merchants → Buy Goods or Merchant Tills
businesses → Paybills

3. JWT Renewal

Your JWT expires after a certain period (e.g., 3600 seconds).
If you encounter an authentication error (Invalid or expired JWT), request a fresh token before retrying.

4. UAT vs Production

The examples provided target the UAT environment:
api-v3-uat.tanda.africa

For production, make sure to:

Switch to the production host
Use the correct credentials and tokens

Summary

Endpoints

Merchant Till Name Lookup
GET /v3/countries/KE/mmos/Mpesa/merchants/{merchantTillNumber}
Business Paybill Name Lookup
GET /v3/countries/KE/mmos/Mpesa/businesses/{businessShortcode}

Headers

Authorization: Bearer <YOUR_JWT_TOKEN>
accept: application/json
content-type: application/json

Successful Response

{
  "name": "<NAME>",
  "status": "S000000",
  "message": "Lookup Success"
}

Use these endpoints to verify or display the account holder names for Mpesa Tills or Paybill shortcodes before making payments.