Appearance
Selcom Wakala 现金支付与 API 能力整理
1. 文档目的
本文用于整理 Selcom 公开官网与开发者文档中可确认的能力，重点关注：
- Selcom 公司与支付网络背景
- Wakala / Agent / Huduma 现金通道能力
- 现金存入、现金取出、C2B 收款、Push USSD 等接口
- 当前接入仍需向 Selcom 确认的资料
2. 资料来源
| 类型 | 地址 | 说明 |
|---|---|---|
| Selcom 官网 | https://www.selcom.net/ | 公司与产品总览 |
| About Us | https://www.selcom.net/about-us | 公司背景、牌照、代理网络与商户规模 |
| Selcom Pay | https://www.selcom.net/selcom-pay- | Till / TanQR / Pay-by-link / Push USSD / 卡支付 |
| Selcom Developers | https://developers.selcommobile.com/ | 官方开发者 API 文档 |
| Selcom Pesa | https://www.selcompesa.app/english | Selcom Pesa 面向用户的钱包与代理存取能力说明 |
| Downloads | https://www.selcom.net/downloads | 合规政策、品牌资料、Huduma Wakala 标识资料 |
3. Selcom 公司与网络能力
Selcom 是 Tanzania 本地支付与金融科技服务商，官网描述其为 Pan African cross-segment financial and payment services provider。
公开资料可确认：
- 成立于 2001 年
- Tanzania Communications Regulatory Authority 许可方
- Bank of Tanzania 许可方
- 连接超过 40 家银行到 mobile banking
- 拥有超过 25,000 个 Selcom Huduma agents
- 服务超过 100,000 个 Selcom Pay card / cardless payment merchants
- 提供 digital、card、card-less processing 服务
- 覆盖银行、代理、商户、政府、企业等支付场景
4. Wakala / Agent / Huduma 能力判断
Selcom 官网没有总是使用 Wakala 这个词作为 API 产品名，但其能力对应关系比较明确：
- Wakala 在 Tanzania 场景通常指代理点 / 代理银行 / 现金服务网点。
- Selcom 官网对应能力主要叫
Selcom Huduma agents、Huduma+ agents、Agency Banking、POS agents。 - 开发者文档中的接口名则使用
POS/Agent Cashout、hudumacashin、C2B/Collection Services。
因此，当前可以把 Selcom 的 Wakala 现金通道理解为：
基于 Selcom Huduma / Huduma+ 代理网络，为银行、金融机构或商户提供现金存入、现金取出、账单支付、C2B 收款、代理付款等能力。
5. 现金支付相关官网能力
5.1 Billers cash assisted payment
官网说明该能力用于替代人工收款和排队缴费，覆盖：
- utility payments
- airtime
- TV subscriptions
- insurance
- government payments
- ticketing
- betting
可集成渠道：
- mobile wallets
- mobile banking
- e-commerce platforms
- POS agents
代理可通过：
- POS
- app
- USSD code
完成支付。
5.2 Agency Banking
官网将 Agency Banking 定位为：
- Deposit Mobilization
- Access to Cash
Selcom Huduma agents 可提供：
- cash deposit
- cash withdrawal
- bank statements
- 基础金融服务
这说明 Selcom 确实具备 Wakala 代理现金服务能力，不只是线上支付网关。
5.3 Selcom Pay
Selcom Pay / Selcom Lipa 支持：
- Till / TanQR payment
- Pay-by-link
- Card payment
- Push USSD payment
- mobile wallet / mobile banking / card payment
Pay-by-link 页面说明客户可通过 Till/TanQR、debit card 和 push USSD 完成支付。
6. 开发者文档中已确认的相关 API
6.1 POS / Agent Cashout
开发者文档中存在 POS/Agent Cashout 模块，用于第三方业务向客户发放资金，客户可到 Selcom Huduma agent 完成现金取出。
接口路径：
http
POST /v1/hudumacashin/process接口含义：
- 第三方业务调用 API 后，Selcom 从业务方 float balance 扣款
- Selcom 为客户创建临时钱包 / token / voucher
- 客户通过
*150*50#进入 Selcom 菜单，选择Huduma Cashout - 客户到 Selcom Huduma agent，输入 agent code 和金额完成取现
- 代理向客户发放现金
请求字段：
| 字段 | 必填 | 示例 | 说明 |
|---|---|---|---|
transid | 是 | XYZ123444 | 唯一交易 ID |
utilitycode | 是 | HUDUMACI | Agent cashout 固定使用 HUDUMACI |
utilityref | 是 | 075XXXXXXX | 客户手机号，用于发送 token / voucher |
amount | 是 | 1000 | 交易金额 |
vendor | 是 | VENDORXYZ | Float account identifier |
pin | 是 | 3122 | Float account PIN |
name | 否 | John Mushi | 客户姓名 |
交易状态查询：
http
GET /v1/hudumacashin/query?transid=XYZ123444Agent Cashout utility code：
| Utilitycode | Category | Ref Label | Ref Type | Description |
|---|---|---|---|---|
HUDUMACI | Agent | Mobile No | Numeric(10,12) | POS / Agent cashout |
6.2 Float Account Balance
用于查询业务方 float account 可用余额。
接口路径：
http
POST /v1/vendor/balance请求字段：
| 字段 | 必填 | 说明 |
|---|---|---|
vendor | 是 | Float account identifier |
pin | 是 | Float account PIN |
transid | 是 | 唯一交易 ID |
6.3 C2B / Collection Services
开发者文档中存在 C2B/Collection Services 模块，用于 Selcom Gateway 在收到来自渠道的付款后，实时通知第三方系统。
支持渠道包括：
- mobile wallets
- bank accounts
- POS Selcom Huduma / Huduma+ agents
- non-POS Selcom Huduma / Huduma+ agents
这与 Wakala 现金收款场景强相关。
6.4 Payment Lookup
接口路径：
http
POST /lookup用途：
- 校验金额
- 校验 payment reference
- 校验手机号
- 校验业务侧账户或订单
请求字段：
| 字段 | 说明 |
|---|---|
operator | 渠道名称，例如 AIRTELMONEY、MPESA-TZ、TIGOPESATZ、HALOPESATZ、TTCLMOBILE、ZANTELEZPESA |
transid | Selcom Gateway 交易 ID |
reference | Selcom Gateway 唯一交易标识 |
utilityref | 业务方 payment reference 或账户号 |
msisdn | 用户手机号 |
期望返回字段：
| 字段 | 说明 |
|---|---|
reference | 回传请求中的 reference |
resultcode | 错误码 |
result | 交易状态，SUCCESS 或 FAILED |
message | 错误描述 |
name | 客户名，可选 |
amount | 固定金额场景可返回应付金额，可选 |
6.5 Payment Validation / Notification
Payment Validation：
- 用于支付前校验金额、付款 reference、手机号等
- 如果超时或失败，源渠道交易会失败并自动 reverse funds
Payment Notification：
- 支付成功后的通知
- payload 与 validate API 相同
- 如果通知超时或无响应，不会自动 reverse funds
- 交易会进入 ambiguous status，等待人工 reconciliation
6.6 Wallet Pull Funds / Push USSD
接口路径：
http
POST /v1/wallet/pushussd用途：
- 触发客户钱包侧的 USSD 菜单
- 让客户通过 PIN 完成钱包认证
- 成功响应只代表钱包提供方成功接收 push request，不代表客户钱包已扣款
- 最终交易完成结果通过 C2B notification 通知业务方
请求字段：
| 字段 | 必填 | 示例 | 说明 |
|---|---|---|---|
transid | 是 | XYZ123444 | 唯一交易 ID |
utilityref | 是 | AB12345 | 业务方收款 reference 或账户号 |
amount | 是 | 1000 | 交易金额 |
vendor | 是 | 01234567891 | Float account identifier |
msisdn | 是 | 06534567891 | 触发 push USSD 的钱包手机号 |
交易状态查询：
http
GET /v1/c2b/query-status查询字段：
| 字段 | 说明 |
|---|---|
transid | Selcom Gateway 交易 ID，可与 reference 二选一 |
reference | Selcom Gateway 唯一 reference，可与 transid 二选一 |
7. Wakala 现金支付 / 建联方案判断
7.1 是否有 Wakala 通道方案
当前公开资料可以确认 Selcom 有 Wakala / 代理网络相关能力，主要体现在：
- Selcom Huduma / Huduma+ agents
- Agency Banking
- POS / Agent Cashout API
- C2B Collection Services
- POS / non-POS agent 收款渠道
- Billers cash assisted payment
因此，Selcom 是可以作为 Wakala 现金支付 / 代理现金服务通道候选的。
7.2 可支持的业务方向
| 业务方向 | Selcom 公开资料支撑 | 说明 |
|---|---|---|
| 现金取出 | 明确支持 | POS/Agent Cashout，客户到 Selcom Huduma agent 完成取现 |
| 现金存入 / 现金收款 | 明确支持 | C2B/Collection Services 支持 POS / non-POS Selcom Huduma agents |
| 账单缴费 | 明确支持 | Billers cash assisted payment |
| 商户收款 | 明确支持 | Selcom Pay / Till / TanQR / card |
| Push USSD 收款 | 明确支持 | POST /v1/wallet/pushussd |
| 代理银行 | 明确支持 | Agency Banking，现金存取、bank statements 等 |
7.3 建议接入模型
现金取出
- 我方业务系统生成提现订单。
- 调用 Selcom
POST /v1/hudumacashin/process。 - Selcom 从我方 float account 扣款。
- Selcom 给客户手机号发 token / voucher 或生成可用凭证。
- 客户到 Selcom Huduma agent。
- 客户通过
*150*50#菜单完成 Huduma Cashout。 - agent 发放现金。
- 我方通过 transaction status query 或回调完成状态同步。
现金存入 / 现金收款
- 客户到 Selcom Huduma / Huduma+ agent。
- agent 选择业务或收款项目。
- Selcom Gateway 调用我方
Payment Lookup/Payment Validation。 - 我方校验账户、订单、金额。
- 客户完成现金支付。
- Selcom Gateway 调用我方
Payment Notification。 - 我方入账并更新订单状态。
Push USSD 收款
- 我方业务系统发起收款订单。
- 调用 Selcom
POST /v1/wallet/pushussd。 - 客户手机收到 USSD / PIN 认证请求。
- 客户确认付款。
- 我方通过 C2B notification 或 query-status 获取最终结果。
8. 当前仍需向 Selcom 确认的信息
8.1 商务与合规
text
1. 我方 fintech 技术公司是否可以直接签约 Wakala / Huduma agent 服务？
2. 如果涉及现金存取，是否必须由银行实体或持牌金融机构签约？
3. 是否需要 Bank of Tanzania 或其他监管审批？
4. Agent cashout / cash collection 是否有单笔、单日、单客户限额？
5. 手续费结构、结算周期、对账文件格式是什么？
6. 代理网络覆盖清单是否可以提供？
7. 是否支持 Tanzania 全境，还是只覆盖指定区域？8.2 技术接入
text
1. 正式 base URL 和 sandbox base URL
2. API key / API secret / token 获取方式
3. Authorization、Digest、Timestamp、Signed-Fields 签名规则完整文档
4. Agent Cashout webhook / callback 是否支持
5. Cash collection 的 lookup、validation、notification 完整 payload 示例
6. 对账 API 或批量对账文件
7. 错误码完整列表
8. timeout / ambiguous / reversal 处理规则
9. 测试 agent、测试手机号、测试 vendor 账号
10. 生产上线 checklist9. 初步接入风险
| 风险 | 说明 | 建议 |
|---|---|---|
| 牌照归属 | Wakala 现金服务可能涉及金融监管 | 先确认签约主体和牌照要求 |
| 对账复杂 | 现金存取涉及 agent、Selcom、我方系统多方状态 | 必须设计 reconciliation 流程 |
| ambiguous 状态 | 文档明确存在 ambiguous / manual recon 场景 | 我方订单状态需要支持处理中和人工核对 |
| 资金池管理 | Agent Cashout 会扣减 float account | 需要余额监控和补款机制 |
| 客户体验 | 取现需要客户到 agent 并通过 USSD 操作 | 产品侧需明确操作流程和失败兜底 |
10. 结论
Selcom 公开资料显示其具备较强的 Wakala / Huduma agent 现金服务能力，并且开发者文档中已经公开了与现金取出、现金收款、Push USSD、C2B 通知相关的接口。
当前可以判断：
- Selcom 适合作为 Wakala 现金支付 / 代理现金服务通道候选。
- 现金取出可重点评估
POS/Agent Cashout。 - 现金存入或现金收款可重点评估
C2B/Collection Services。 - Push USSD 可作为远程钱包扣款方案。
- 真正建联前，需要向 Selcom 获取正式商务资料、签约主体要求、sandbox 凭证、签名规则、回调规范、费用和对账方案。
11. 银行侧典型业务场景与 Selcom 接口映射
本节按银行 App / 银行后台常见业务场景整理 Selcom 可用接口。接口路径仅填写当前 Selcom 官方开发者文档中已识别到的真实 API；未找到公开路径的能力以“需 Selcom 确认”标注。
11.1 用户贷款后到 Wakala / Agent 提现现金
场景说明：用户在我方银行 App 申请贷款，贷款资金已进入我方银行账户或内部贷款账户，用户希望去线下代理点提取现金。
| 场景 | Selcom 接口 / 能力 | 作用 |
|---|---|---|
| 提现前检查 Selcom 资金池 | POST /v1/vendor/balance | 查询我方在 Selcom 的 float account 可用余额，避免创建取现任务后资金不足 |
| 创建现金取出任务 | POST /v1/hudumacashin/process | 创建 Agent Cashout / Huduma Cashout 交易，Selcom 从 float account 扣款并为客户生成 token / voucher |
| 用户到代理点取现 | Selcom Huduma / Huduma+ agent + USSD 菜单 | 用户到代理点后，通过 Selcom 流程完成取现；文档中提到用户可通过 *150*50# 进入 Selcom 菜单选择 Huduma Cashout |
| 查询取现状态 | GET /v1/hudumacashin/query?transid={transid} | 按我方交易号查询 agent cashout 状态 |
| 接收取现结果通知 | 需 Selcom 确认 | 当前公开资料中已看到交易状态查询接口，但未确认 Agent Cashout 是否支持 webhook / callback |
| 日终对账 | 需 Selcom 确认 | 需确认是否提供 reconciliation API、对账文件或商户后台导出 |
建议我方内部状态：
text
CREATED -> BALANCE_CHECKED -> CASHOUT_CREATED -> WAITING_CUSTOMER_CASHOUT -> SUCCESS / FAILED / EXPIRED / MANUAL_RECON11.2 用户到代理点现金存入 / 现金还款
场景说明：用户到 Selcom Huduma / Huduma+ agent 交现金，用于银行账户充值、贷款还款、账单支付或机构收款。
| 场景 | Selcom 接口 / 能力 | 作用 |
|---|---|---|
| 代理点发起收款 | C2B/Collection Services | Selcom 通过 mobile wallet、bank account、POS agent、non-POS agent 等渠道受理用户付款 |
| 支付前查询业务信息 | POST /lookup | Selcom Gateway 调用我方系统，校验 payment reference、账户号、手机号、金额等信息 |
| 支付前校验 | Payment Validation，具体 URL 需 Selcom 确认 | 用于校验金额、付款 reference、手机号等；公开文档说明了 validation 机制，但我方需要确认正式 callback URL 配置方式 |
| 支付成功通知 | Payment Notification，具体 URL 需 Selcom 确认 | Selcom 支付成功后通知我方系统；公开文档说明 payload 与 validation API 相同 |
| 查询收款状态 | GET /v1/c2b/query-status | 按 transid 或 reference 查询 C2B 交易状态 |
| 日终对账 | 需 Selcom 确认 | 需确认是否提供 C2B 对账文件、结算报表或 API |
建议我方内部状态：
text
CREATED -> WAITING_PAYMENT -> VALIDATING -> PAID -> POSTED / FAILED / AMBIGUOUS11.3 用户通过 Mobile Money / Push USSD 向我方还款
场景说明：用户在银行 App 发起还款或充值，我方通过 Selcom 触发用户手机上的钱包 USSD / PIN 确认流程。
| 场景 | Selcom 接口 / 能力 | 作用 |
|---|---|---|
| 发起 Push USSD 收款 | POST /v1/wallet/pushussd | 触发客户钱包侧的 USSD / PIN 认证流程 |
| 用户手机确认付款 | Mobile wallet / USSD provider flow | 用户在手机侧输入 PIN 或完成钱包确认 |
| 获取最终支付结果 | C2B Notification，具体 URL 需 Selcom 确认 | pushussd 成功响应只代表钱包提供方收到请求，不代表最终扣款成功；最终结果通过 C2B notification 通知 |
| 主动查询状态 | GET /v1/c2b/query-status | 在未收到通知或状态不明确时，按 transid 或 reference 查询最终状态 |
| 支付前业务校验 | POST /lookup 或 Payment Validation，需按配置确认 | 可用于校验订单号、手机号、金额和用户账户 |
建议我方内部状态：
text
CREATED -> PUSH_SENT -> WAITING_CUSTOMER_CONFIRM -> PAID / FAILED / TIMEOUT / AMBIGUOUS11.4 用户之间转账 / Mobile Money 之间转账
场景说明：用户 A 希望通过我方银行 App 把钱转给用户 B 的手机号或 mobile money 钱包。
当前公开资料中，Selcom 文档明确展示了 Wallet Pull Funds / Push USSD，用于从客户钱包侧拉起付款；但“由我方直接向某个 mobile money 钱包出款”的 B2C payout 接口路径未在本文已识别资料中确认。
| 场景 | Selcom 接口 / 能力 | 作用 |
|---|---|---|
| 从付款方钱包扣款 | POST /v1/wallet/pushussd | 触发付款方 mobile money / USSD 确认付款 |
| 收款方入账到我方业务账户后再处理 | C2B/Collection Services | 将付款方资金先收至我方，再由我方内部清分或走另一条出款通道 |
| 直接转入收款方 mobile money 钱包 | 需 Selcom 确认 | 需确认 Selcom 是否提供 B2C wallet payout / wallet transfer API，以及正式路径、字段和费用 |
| 查询转账状态 | GET /v1/c2b/query-status | 适用于 C2B / Push USSD 侧状态查询；B2C 出款查询接口需另行确认 |
| 失败退款 / 冲正 | 需 Selcom 确认 | 需确认 reversal、refund、ambiguous 状态处理规则 |
建议判断：
- 如果是“用户向机构付款”，使用 C2B / Push USSD。
- 如果是“机构向用户钱包出款”，需要 Selcom 明确提供 B2C payout API。
- 如果是“用户 A 直接转给用户 B”，要确认 Selcom 是否支持 wallet-to-wallet transfer，或者是否需要拆成 C2B 收款 + B2C 出款两段。
11.5 银行侧商户 / 机构收款
场景说明：银行或平台为商户、账单、服务费、贷款还款生成收款 reference，用户通过代理点、mobile wallet、银行账户等方式付款。
| 场景 | Selcom 接口 / 能力 | 作用 |
|---|---|---|
| 生成或识别收款 reference | 我方系统生成，Selcom 通过 POST /lookup 校验 | 当前资料中未看到 Selcom 生成 control number 的明确接口，建议由我方生成业务 reference |
| 用户付款前校验 | POST /lookup | Selcom 调用我方系统，确认 reference 是否有效、金额是否正确 |
| 支付成功通知 | Payment Notification，具体 URL 需 Selcom 确认 | 用户付款成功后，Selcom 通知我方入账 |
| 查询状态 | GET /v1/c2b/query-status | 未收到通知或状态异常时主动查询 |
| 对账 | 需 Selcom 确认 | 需确认结算周期、对账文件、商户后台导出方式 |
11.6 银行侧需要重点确认的接口与资料
| 类别 | 需要 Selcom 确认的内容 |
|---|---|
| Agent Cashout | 是否支持结果 callback、token 有效期、用户取现失败或超时后的资金退回规则 |
| C2B Collection | Payment Validation / Notification 的正式 URL 配置方式、payload、签名校验和重试规则 |
| B2C Payout | 是否支持向 mobile money 钱包、银行账户或 Selcom Pesa 出款，接口路径和费用 |
| Wallet Transfer | 是否支持用户 A 到用户 B 的 wallet-to-wallet transfer |
| 对账 | 是否提供 reconciliation API、文件下载、商户后台导出、结算明细 |
| 风控限额 | 单笔、单日、单用户、单代理点限额 |
| 签名鉴权 | API key、PIN、Digest、Timestamp、Signed-Fields、IP whitelist 的完整规则 |
| 测试环境 | sandbox base URL、测试 vendor、测试 agent、测试手机号和测试交易流程 |