Skip to content

M-PESA 支付与号码安全接口整理(dpis-gw / drcs-gw) ​

来源:mint-capability-hub/dpis-gw/docs(7 份)与 drcs-gw/docs(Safaricom 号码安全查询),2026-08 ~ 2026-10 版。M-PESA 通过 Safaricom Daraja 平台接入:沙箱 sandbox.safaricom.co.ke,生产 api.safaricom.co.ke。

能力全景 ​

能力资金方向 / 性质WeRPC状态
B2C 出款(放款 / 提现)商户 → 客户钱包02100005已实现(沙箱级)
B2C Pochi 转账商户 → Pochi 小微商户钱包service-ids.b2-pochi-transfer已实现
STK Push 收款客户 → 商户(弹 PIN 框)service-ids.stk-push已实现
STK 查询查询 STK 最终状态service-ids.stk-query已实现
C2B 入金(Paybill)客户 → 商户(被动回调)无主动入口回调已实现
C2B URL 注册运维操作service-ids.c2b-register-url已实现
冲正 Reversal撤销原交易service-ids.reversal-request已实现
渠道交易查单按 TransactionID 查 Safaricomservice-ids.transaction-status-query已实现
本地流水查询查 dpis-gw 落库流水02300009已实现
SWAP 换卡查询风控(无资金)未分配沙箱测试通过
Age on Network风控(无资金)未分配沙箱测试通过
B2C Hakikisha出款前收款人核身未分配沙箱测试通过
Direct Debit 自动续费——明确暂缓

WeRPC 接口要点 ​

  • 公共幂等键 bizSeqNo:全局防重,重试原值重传;回调按原始报文 SHA-256 生成 eventKey 防重。
  • 状态机:INITIATED → SUBMITTING → ACCEPTED → SUCCESS / FAILED / UNKNOWN;ACCEPTED 绝不能入账;超时 / 5xx 一律记 UNKNOWN,只查单不重发。
  • 回调端点:/callbacks/mpesa/stk/result、/b2c/result(+timeout)、/c2b/validation + /c2b/confirmation、/transaction-status/result、/reversal/result。
  • B2C 必填 sceneCode(LOAN_DISBURSEMENT / ACCOUNT_WITHDRAWAL)+ disbursementId;贷款场景条件必填 loanId。
  • 冲正:originalTransactionId + amount(≤原交易)+ reason + approvalReference(审计留痕),窗口期默认 30 天。
  • C2B 安全开关:MPESA_C2B_VALIDATION_MODE 保持 REJECT_ALL,直到银行账号校验服务接通。

号码安全三件套(Daraja 风控查询) ​

能力Safaricom 接口drcs-gw 内部接口输出
Age on Network 在网时长POST /registration/lookup/v1/checkATI/internal/v1/safaricom/network-age-checksregistrationDate / networkAgeDays;占位值 01-01-1900 = NOT_DISCLOSED,不得当真实日期
SWAP 换卡时间POST /imsi/v2/checkATI/internal/v1/safaricom/sim-swap-checkslastSwapDate(仅最近 3 个月窗口);OUTSIDE_LOOKBACK ≠ 从未换卡;查询失败不得默认"未换卡"
B2C Hakikisha 收款人姓名POST /mpesa/b2c/hakikisha/v1/hakikisha/internal/v1/safaricom/b2c-recipient-checks脱敏 firstName / middleName / lastName;查询失败不得自动放行 B2C 出款
  • 仅支持 KE,号码格式 254XXXXXXXXX;重试必须同 bizSeqNo(按次计费,防费用膨胀)。
  • 计费参考:AON KES 4.00→1.25/次(月阶梯)、SWAP KES 1.20→0.50/次(不含 VAT);Hakikisha 免费但需审批,与 C2B Hakikisha 互惠开通。

费率模型(Bouquet) ​

  • 谁出手续费由 shortcode 签约时的 Bouquet 决定(Business Tariff 客户出费 / Customer Bouquet 商户出费 / Mgao 分摊),API 无法修改;所有 API 请求 / 响应 / 回调中均无 fee 字段。
  • Send Money / B2C:≤100 免费,20,001 以上封顶 108 KSh,永远出款方承担,收款方足额到账。
  • 账户限额:最大余额 500,000、日累计 500,000、单笔 250,000 KSh。
  • 2026-08 商业费率削减最高 50%(Paybill 商业端约 -47%、B2C 约 -61%);Paybill 社区费率表未经官方验证,以合同附件为准。
  • 建议:配置中心维护费率表,回调落库时查表计算 fee,月度与 Safaricom Statement 对账。

上线前 P0 待办(摘要) ​

  • 银行侧分配正式 WeRPC serviceId;执行建表 SQL;Safaricom 产品开通与 ShortCode 绑定。
  • 凭据入密钥管理系统;公网 HTTPS 回调 + 限流。
  • C2B / B2C 接入核心记账(当前只更新渠道流水);Outbox 解耦;日终对账与人工补单;禁止对 UNKNOWN 自动重发。

文档版本说明 ​

  • 《M-PESA-入金与查询接口》(9/9 晚)为通用 B2C 出金演进版(disbursementId 必填),以此为准;《B2C放款与本地查询接口》(9/9)为贷款专用旧版。
  • Safaricom 号码安全查询存在 A/B 两版内部文档,以 B 版响应信封(result + 错误码 500001)为准,A 版字段映射与风控建议可作补充。