用途
flutterwave-mobile-money 用于通过 Flutterwave 发起移动货币(Mobile Money)收款,核心目标是实现运营商感知的路由(operator-aware routing)以及延迟状态处理(delayed status handling)。它面向需要在非洲多个市场集成移动货币支付的开发者,提供可复用的 TypeScript 实现模式。
主要能力
- 统一封装 Flutterwave v3 与 v4 两个版本的 API 请求,通过 getBaseUrl 按版本选择基础 URL。
- 提供 flwRequest 泛型请求函数,自动附加 Content-Type 与 Authorization: Bearer 头,并解析 FlwResponse 结构。
- 定义 FlutterwaveApiError 错误类,携带 statusCode 与 payload,便于错误处理。
- 列出关键端点操作:
- v3 POST /charges?type=mobile_money:发起移动货币扣款。
- v3 GET /transactions/{id}/verify:验证交易完成。
- v4 GET /mobile-networks:获取支持的运营商。
- v4 POST /charges:创建移动货币扣款。
- 提供国家/通道矩阵,说明不同市场的集成注意事项:
- 肯尼亚(KE):M-Pesa,许多消费者场景的主要通道。
- 加纳(GH):MTN/Vodafone,需根据客户手机号前缀选择运营商。
- 乌干达/卢旺达/坦桑尼亚/赞比亚(UG/RW/TZ/ZM):Airtel/MTN 变体,需通过 Webhook 加轮询处理延迟完成。
使用方式
技能以 TypeScript 代码形式给出实现模式。使用前需配置环境变量:FLW_V3_BASE_URL(默认 https://api.flutterwave.com/v3)、FLW_V4_BASE_URL(默认 https://developersandbox-api.flutterwave.com)、FLW_SECRET_KEY。通过 flwRequest 函数发起请求,例如示例中调用 v4 的 /charges。代码中保留了原始实现,包括类型定义、错误类与请求封装。
适用场景
适用于需要在 Flutterwave 覆盖的非洲市场(如肯尼亚、加纳、乌干达、卢旺达、坦桑尼亚、赞比亚)集成移动货币收款的场景,尤其是需要按运营商路由、处理异步延迟状态、并进行交易对账与 Webhook 幂等处理的支付集成。
限制与注意事项
- 资料未提供具体的收费、价格、平台支持范围或效果数据。
- 可靠性清单要求:在履约前于服务端重新验证成功支付状态;存储 provider ids、内部 ids、tx_ref 与 event ids 用于对账;保持 Webhook 消费者幂等并快速返回 HTTP 200;按版本隔离请求/响应类型以避免 schema 混淆。
- v4 在公开参考中是资源中心化的(resource-centric),建议在代码中按版本维护路由映射与载荷类型,以确保生成的集成保持准确。
- 资料未提供完整的错误码列表、速率限制或认证细节,需参考官方文档。