POST /account-lookup

POST /api/v1/remittance/account-lookup

Mandatory pre-flight before /inbound. Returns the telco subscriber name for a beneficiary MSISDN so you can:

1. Confirm the beneficiary name with your end-user
2. Pass the confirmed name back to /inbound as expected_receiver_name

Auth: Basic merchant_code:merchant_secret

Request

{
  "customer_number": "243812345678",
  "operator":        "mpesa"
}

Field	Type	Required	Description
customer_number	string	yes	Beneficiary MSISDN (243…).
operator	string	no	If omitted, auto-detected from the 243… prefix.

Response (200 OK)

{
  "status": "success",
  "data": {
    "customer_number": "243812345678",
    "operator":        "mpesa",
    "subscriber_name": "MARIE KABILA",
    "active":          true
  },
  "timestamp": "2026-08-14T14:00:00.000000"
}

Errors

Code	HTTP	Meaning
IMT-1002	400	Unknown DRC prefix (not a mpesa / airtel / orange / afrimoney number).
RMT-2004	403	IP not whitelisted for your account.
RMT-5003	502	Telco temporarily unavailable — retry after ~30s.

Rate

Free — no wallet debit, no fee. Call it as many times as you want before /inbound.