用途
flutterwave-payment-plans 用于支持基于套餐(plan)驱动的周期性收款,并提供订阅状态控制能力。它面向需要在 Flutterwave 平台上实现订阅制或定期扣款业务的开发者,帮助组织支付计划创建、订阅取消、周期性扣款尝试以及订阅者身份解析等操作。
主要能力
该技能以 TypeScript 实现,封装了 Flutterwave v3 与 v4 两个版本的 API 调用模式,主要包含以下内容:
- 统一请求封装:通过 flwRequest 函数按版本(v3 或 v4)选择基础 URL,并自动附加 Content-Type 与 Authorization 请求头。
- 环境变量配置:使用 FLW_V3_BASE_URL、FLW_V4_BASE_URL 与 FLW_SECRET_KEY 三个环境变量,其中 v3 默认指向 https://api.flutterwave.com/v3,v4 默认指向 https://developersandbox-api.flutterwave.com。
- 错误处理:定义 FlutterwaveApiError 错误类,携带 statusCode 与 payload,便于定位 API 失败原因。
- 端点操作覆盖:
- v3 POST /payment-plans:创建支付计划。
- v3 POST /subscriptions/{id}/cancel:取消订阅。
- v4 POST /charges:执行周期性扣款尝试。
- v4 GET /customers:解析订阅者身份。
- 市场与通道参考:提供国家/通道矩阵,例如尼日利亚(NG)以卡类周期扣款为主,肯尼亚(KE)采用移动货币加卡备份的降级策略,并建议按市场规则调整重试节奏。
使用方式
使用前需配置 FLW_SECRET_KEY 等环境变量。核心调用通过 flwRequest 函数完成,传入版本号、路径与可选的 RequestInit 参数。示例中展示了以 v4 版本调用 /charges 端点的用法。开发者可参照端点操作表,按业务需要调用创建支付计划、取消订阅、执行扣款或查询客户等接口。
适用场景
适用于需要在 Flutterwave 上构建订阅制收费、定期扣款、套餐管理等业务的集成场景,尤其涉及多市场(如尼日利亚、肯尼亚)的周期性收款与订阅状态管理。
限制与注意事项
- 需自行提供 FLW_SECRET_KEY,缺失时会抛出错误。
- 可靠性检查清单要求:在履约前于服务端重新校验支付成功状态;存储 provider ids、内部 ids、tx_ref 与事件 ids 以便对账;保持 webhook 消费者幂等并快速返回 HTTP 200;按版本隔离请求/响应类型以避免 schema 混淆。
- v4 在公开参考中以资源为中心,建议在代码中保持路由映射与载荷类型的版本化,以确保集成准确。
- 关于具体收费、价格、平台支持范围等事实,资料中暂未提供。