API Reference

Subscriber Lookup

API REFERENCE

Subscriber Lookup

Verify the account holder's name on an M-Pesa number or bank account before sending. Lookups are asynchronous: the result arrives at your callback_url.

Get Mobile Subscriber Details

Verify the account holder's name on an M-Pesa number. The response confirms receipt only. The name and a tracking_id arrive at your callback_url.

Warning: logMobileTranscation requires the tracking_id from the callback.

If statusCode is 400, the provider rejected the lookup. statusDescription gives the reason.

POST/getSubscriberDetailssubscriber@getMobileSubscriberDetailsasync

Request Body

FieldTypeRequiredDescription

paramsobjectYesParameters for the operation. Send {} if there are none.

request_idstringYesYour unique ID for this lookup. Returned in the callback.

msisdnstringYesRecipient phone, international format

callback_urlstringYesHTTPS URL that receives the result

remarkstringYesFree-text note

Request Body Example

json

{
  "jsonrpc": "2.0",
  "method": "subscriber@getMobileSubscriberDetails",
  "params": {
    "request_id": "LKP-20261012-0001",
    "msisdn": "254712345678",
    "callback_url": "https://partner.example.com/afrisend/lookup",
    "remark": "Recipient verification"
  },
  "id": "1"
}

It confirms receipt only. The outcome arrives at your callback_url.

Response Fields

FieldTypeDescription

resultobjectOperation result

result.statusCodeinteger200 accepted, 400 not accepted

result.statusDescriptionstringReason the request was not accepted, when statusCode is 400

Example Response

json

{
  "jsonrpc": "2.0",
  "result": {
    "statusCode": 200,
    "statusDescription": "Service request has been received"
  },
  "id": "1"
}

The bearer token is missing, invalid or expired. The response is plain JSON with HTTP 401, not a JSON-RPC envelope. Log in again and retry once.

Response Fields

FieldTypeDescription

statusstringAlways 401.

messagestringError message

Example Response

json

{
  "status": 401,
  "message": "Failed, Not authorized"
}

Callback — Mobile Lookup Result

Sent as POST to your callback_url.

Callback Fields

FieldTypeDescription

request_idstringYour request_id

tracking_idstringPass this to logMobileTranscation

statusstringOutcome of the lookup One of: success, error.

status_messagestringDetails of the outcome

recipient_data.CreditPartyNamestring"<msisdn> - <registered name>" (empty on error)

Callback Example

json

{
  "request_id": "LKP-20261012-0001",
  "tracking_id": "AG_20261012_2030166ee8992ece3dc4",
  "status": "success",
  "status_message": "The service request is processed successfully.",
  "recipient_data": {
    "CreditPartyName": "254712345678 - Wanjiru Kamau"
  }
}

Get Bank Subscriber Details

Verify the account holder's name on a bank account. The result arrives at your callback_url.

POST/getSubscriberDetailssubscriber@getBankSubscriberDetailsasync

Request Body

FieldTypeRequiredDescription

paramsobjectYesParameters for the operation. Send {} if there are none.

request_idstringYesYour unique ID for this lookup

msisdnstringYesRecipient phone, international format

destination_bank_codestringYesBank code from getAllBanks

destination_bank_accountstringYesRecipient account number

callback_urlstringYesHTTPS URL that receives the result

remarkstringYesFree-text note

Request Body Example

json

{
  "jsonrpc": "2.0",
  "method": "subscriber@getBankSubscriberDetails",
  "params": {
    "request_id": "LKP-20261012-0002",
    "msisdn": "254722334455",
    "destination_bank_code": "40401000",
    "destination_bank_account": "1182736450",
    "callback_url": "https://partner.example.com/afrisend/lookup",
    "remark": "Recipient verification"
  },
  "id": "1"
}

It confirms receipt only. The outcome arrives at your callback_url.

Response Fields

FieldTypeDescription

resultobjectOperation result

result.statusCodeinteger200 accepted, 400 not accepted

result.statusDescriptionstringReason the request was not accepted, when statusCode is 400

Example Response

json

{
  "jsonrpc": "2.0",
  "result": {
    "statusCode": 200,
    "statusDescription": "Service request has been received"
  },
  "id": "1"
}

The bearer token is missing, invalid or expired. The response is plain JSON with HTTP 401, not a JSON-RPC envelope. Log in again and retry once.

Response Fields

FieldTypeDescription

statusstringAlways 401.

messagestringError message

Example Response

json

{
  "status": 401,
  "message": "Failed, Not authorized"
}

Callback — Bank Lookup Result

Sent as POST to your callback_url.

Callback Fields

FieldTypeDescription

request_idstringYour request_id

transaction_idstring

tracking_idstringAfrisend tracking reference

statusstringOutcome of the lookup One of: SUCCESS, ERROR.

status_messagestringDetails, e.g. Invalid account

recipient_data.firstNamestringAccount holder name (empty on error)

Callback Example

json

{
  "request_id": "LKP-20261012-0002",
  "transaction_id": "YB34R6FY3Z7U",
  "tracking_id": "YB34R6FY3Z7U",
  "status": "SUCCESS",
  "status_message": "SUCCESS",
  "recipient_data": {
    "firstName": "OTIENO BRIAN ODHIAMBO"
  }
}

Previous← Rates and Banks NextTransactions →