Appearance
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 查 Safaricom | service-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-checks | registrationDate / networkAgeDays;占位值 01-01-1900 = NOT_DISCLOSED,不得当真实日期 |
| SWAP 换卡时间 | POST /imsi/v2/checkATI | /internal/v1/safaricom/sim-swap-checks | lastSwapDate(仅最近 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 版字段映射与风控建议可作补充。