非洲第三方知识库

Appearance

M-Pesa 手机号验证（Mobile Number Validation）接口整理 ​

文档信息 ​

1. 功能定位 ​

实时校验服务：用 手机号（MSISDN）+ 证件类型 + 证件号码 三要素，验证该手机号是否真实注册在 Safaricom 数据库中、且注册信息与提交证件一致。

项目说明
验证方式MSISDN + idType + idNumber 三重匹配
返回结果布尔 true / false，不返回任何个人敏感数据
同步/异步同步，实时返回
是否收费商业 API，按调用量阶梯计费（不含 VAT），仅成功调用（4000/4001）计费
隐私仅 True/False，符合肯尼亚《数据保护法 2019》
运营商限制仅限 Safaricom 号码，不覆盖 Airtel / Telkom

典型场景：数字开户（手机号与身份信息匹配核验）、OTP 之外的二次身份核验、冒名注册识别、联系人数据清洗、营销对象有效性校验。

2. 接入前提 ​

  1. 注册 Daraja 开发者账号：https://developer.safaricom.co.ke
  2. 创建 Sandbox 应用，获取 Consumer Key / Consumer Secret。
  3. 在 Simulator 区域获取沙盒测试手机号、证件号。
  4. 正式使用前联系 apisupport@safaricom.co.ke 签署商业协议。
  5. Go Live：绑定真实 Paybill / Till 号码，OTP 验证后获取生产凭证。

3. 认证：OAuth 2.0 client_credentials ​

http
GET https://sandbox.safaricom.co.ke/oauth/v1/generate?grant_type=client_credentials
Authorization: Basic Base64(ConsumerKey:ConsumerSecret)

成功响应：

json
{
  "access_token": "SGWcJPtNtYNPGm1DqBNqZZZZZZ",
  "expires_in": "3599"
}
  • Token 有效期约 3600 秒，建议服务端缓存、50 分钟左右自动刷新，避免每请求取新 Token。
  • 生产环境域名换成 api.safaricom.co.ke。

4. 验证接口 ​

项目值
路径POST /v1/KYC-validation/validateID
沙盒https://sandbox.safaricom.co.ke/v1/KYC-validation/validateID
生产https://api.safaricom.co.ke/v1/KYC-validation/validateID
Content-Typeapplication/json
认证Authorization: Bearer {access_token}

入参 ​

json
{
  "requestRefID": "83a2-4b44-aaffcb3f93",
  "shortCode": "12345",
  "msisdn": "254710860780",
  "idType": "01",
  "idNumber": "454353453"
}
参数类型必填说明
requestRefIDString是商户生成的唯一请求标识，用于幂等与追踪，建议 UUID 或时间戳+随机数
shortCodeString是组织关联的 Paybill / Till 号码
msisdnString是手机号，必须 254 开头 12 位纯数字，不支持 +254 / 07xx
idTypeString是证件类型编码，见枚举
idNumberString是证件号码

idType 枚举：

编码证件类型
01National ID（肯尼亚国民身份证）
02Military ID（军人证）
05Passport（护照）

响应 ​

匹配（HTTP 200）：

json
{
  "responseRefID": "1771929697",
  "responseCode": "4000",
  "responseMessage": "Details match successfully",
  "status": "true"
}

不匹配（HTTP 200）：

json
{
  "responseRefID": "1771929733",
  "responseCode": "4001",
  "responseMessage": "Details do not match",
  "status": "false"
}
字段说明
responseRefIDAPI 网关生成的请求标识
responseCode4000 匹配 / 4001 不匹配
responseMessage描述信息
status核心结果："true" / "false"（字符串，注意非布尔类型）

错误码 ​

HTTPerrorCode含义排查
403403.001 subscription_not_available订阅不可用检查商业协议签署与上线状态
400400 Invalid MSISDN手机号格式非法必须 2547 开头、纯数字
401401.001 Invalid access tokenToken 无效/过期重新获取 Token，核对 Key/Secret
500500 Invalid parameter input参数无效检查必填字段完整性

错误体示例：

json
{
  "responseId": "83a2-aa8bfffcb3f939",
  "errorCode": "403.001",
  "errorMessage": "subscription_not_available"
}

5. 沙盒测试数据 ​

场景msisdnidTypeidNumber预期
匹配25471086078001454353453status:"true", code 4000
不匹配25471086078001999999999status:"false", code 4001
非法手机号071234567801454353453HTTP 400
Token 过期25471086078001454353453HTTP 401

沙盒不查真实库，按预置规则返回固定结果。

6. 调用示例（cURL） ​

bash
# Step 1: 获取 Access Token
curl -X GET \
  "https://sandbox.safaricom.co.ke/oauth/v1/generate?grant_type=client_credentials" \
  -H "Authorization: Basic Base64(YourConsumerKey:YourConsumerSecret)"

# Step 2: 三要素核验
curl -X POST \
  https://sandbox.safaricom.co.ke/v1/KYC-validation/validateID \
  -H "Authorization: Bearer SGWcJPtNtYNPGm1DqBNqZZZZZZ" \
  -H "Content-Type: application/json" \
  -d "{\"requestRefID\":\"req-001\",\"shortCode\":\"12345\",\"msisdn\":\"254710860780\",\"idType\":\"01\",\"idNumber\":\"454353453\"}"

7. 生产上线清单 ​

步骤事项
1签署商业协议（apisupport@safaricom.co.ke）
2准备活跃的 Paybill / Till 收款号码
3联系 M-PESABusiness@Safaricom.co.ke 创建 Business Administrator
4Daraja 门户 Go Live：填组织短码、组织名称、M-Pesa 用户名
5OTP 验证（发送至 Safaricom 安全手机号）
6邮件接收生产 Consumer Key / Secret
7URL 由 sandbox.safaricom.co.ke 换成 api.safaricom.co.ke
8小额真实交易端到端验证

8. 资费（不含 VAT，仅成功调用计费） ​

月调用量单价（KES/次）
0 – 200,0004.50
200,001 – 500,0004.28
500,001 – 1,000,0003.94
1,000,001 – 5,000,0003.60
5,000,000 以上3.15

9. 最佳实践 ​

  1. 手机号入库前统一转 254xxxxxxxxx，拒绝 +254 / 07xx。
  2. Token 服务端缓存，约 50 分钟自动刷新。
  3. requestRefID 保证唯一（UUID），用于幂等与对账追踪。
  4. status 是字符串 "true"/"false"，解析时勿按布尔强转。
  5. 对 401（刷新 Token 后重试）、403（订阅告警）、500（参数排查）分类处理。
  6. HTTP 超时建议 10–30 秒，避免阻塞开户主流程。
  7. 非 Safaricom 号码走兜底渠道（如 SmileID 手机号验证）。

接入待确认 ​

  • 商业协议进度与生产凭证；组织短码（shortCode）申请值。
  • 与 SmileID / Softnet / YesID 等 KYC 源的编排顺序与降级策略。
  • 肯尼亚之外市场的同类运营商源（如坦桑尼亚见 通信能力 厂商）。