KYC Check

Use this endpoint before issuing a voucher. It tells you two things about a recipient mobile number: the first name the account is registered under, so the sender can confirm they are paying the right person, and whether the account is active and can receive a voucher.

Voucher issuance enforces the same check. A request for a recipient whose status is not ACTIVE is rejected with 422, so calling this endpoint first lets you stop the sender before they commit.

Flow

Endpoint

POST /kyc/check

Headers

Header	Required	Description
X-API-Key	Yes	Partner API key.
X-Timestamp	Yes	ISO timestamp used in signature verification.
X-Signature	Yes	Base64 Ed25519 signature for the request.
Idempotency-Key	No	Optional key recorded with the request log.
User-Agent	No	Optional client identifier.

Request Body

Field	Type	Required	Rules
msisdn	string	Yes	Recipient mobile number, max 32 chars. Accepts 09XXXXXXXX, 2519XXXXXXXX, or +2519XXXXXXXX.

Example Request

curl -X POST "$API_BASE_URL/kyc/check" \
  -H "Content-Type: application/json" \
  -H "X-API-Key: $PARTNER_API_KEY" \
  -H "X-Timestamp: 2026-04-29T12:00:00.000Z" \
  -H "X-Signature: $PARTNER_SIGNATURE" \
  -d '{
    "msisdn": "+251911234567"
  }'

Example Responses

Active account

{
  "firstName": "Abebe",
  "status": "ACTIVE"
}

Inactive account

{
  "firstName": null,
  "status": "INACTIVE"
}

Field	Type	Description
firstName	string or null	Recipient first name as registered for the account. null when no name is available.
status	ACTIVE or INACTIVE	Whether the account can receive a voucher.

Interpreting the result

Gate on status, and show firstName to the sender.

status	Meaning	What to do
ACTIVE	The number belongs to an active account.	Show firstName to the sender to confirm the recipient, then proceed to issuance.
INACTIVE	The number has no account, or the account cannot transact.	Do not proceed. Issuance will reject the request. Tell the sender the number cannot receive a voucher.

An INACTIVE result does not say why. An unregistered number and a registered account that cannot transact are the same answer for your purposes, and separating them would disclose more about the number than the transaction needs.

firstName can be null on an ACTIVE account when no name is held for it. That is not a reason to stop; status is the field that decides.

Response Codes

Code	Meaning
200	Check completed. status and firstName carry the result.
400	Invalid request body or headers.
401	Missing or invalid API key, timestamp, or signature.
403	Access is forbidden.
422	msisdn is not a valid Ethiopian mobile number.
502	The account lookup is temporarily unavailable.

Integration Notes

• An INACTIVE account is a successful check: the endpoint returns 200, not an error status. Only a lookup fault is an error.
• Treat 502 as a transient condition and retry after a short delay. It means the lookup could not be completed, never that the number itself is bad.
• Check just before issuance rather than caching the result. Account status can change, and issuance re-checks it regardless.
• firstName is personal data. Use it only to confirm the recipient with the sender before the transaction, and do not persist or display it beyond that purpose.
• Requests are signed the same way as other partner endpoints; see Request Authentication.