用途
flutterwave-bills 用于在应用中集成话费(airtime)、流量(data)和公共事业缴费(utility payments),并在集成过程中加入校验(validation)与对账(reconciliation)检查。它面向需要接入 Flutterwave 账单支付能力的开发者,帮助构建可靠的账单支付流程。
主要能力
该技能提供了一套 TypeScript 实现模式,核心包括:
- 环境变量配置:FLW_V3_BASE_URL、FLW_V4_BASE_URL、FLW_SECRET_KEY,其中 v3 默认指向 https://api.flutterwave.com/v3,v4 默认指向 https://developersandbox-api.flutterwave.com。
- 统一的响应类型 FlwResponse<T>,包含 status、message、data 字段。
- 自定义错误类 FlutterwaveApiError,携带 statusCode 与 payload。
- 基础 URL 切换函数 getBaseUrl,根据版本返回对应地址。
- 通用请求函数 flwRequest,自动附加 Content-Type 与 Authorization 头,并在响应非成功或 status 为 error 时抛出错误。
端点操作与参考
技能列出了以下端点操作:
| 版本 | 方法 | 路由 / 操作 | 用途 | 参考 |
|---|---|---|---|---|
| v3 | GET | /bill-categories | 列出账单类别 | https://developer.flutterwave.com/docs/telecommunications |
| v3 | POST | /bills | 创建账单支付 | https://developer.flutterwave.com/docs/telecommunications |
| v4 | GET | /payment-methods | 解析允许的支付通道 | https://developer.flutterwave.com/reference/payment_methods_list |
| v4 | POST | /orders | 创建可支付订单上下文 | https://developer.flutterwave.com/reference/orders_post |
使用方式
技能给出了一个使用示例,通过 flwRequest 调用 v4 的 /orders 端点:
export async function runBillsExample() {
return flwRequest<unknown>("v4", "/orders", {
method: "GET",
});
}
开发者需要先设置 FLW_SECRET_KEY 环境变量,然后调用 flwRequest 并传入版本、路径和请求初始化参数。
适用场景
- 尼日利亚(NG)市场:话费、流量、有线电视、电力等账单类别需求最高。
- 加纳(GH)市场:公共事业缴费与话费,需确认各账单机构特定的金额限制。
- 所有市场:建议先校验客户标识,再进行扣款。
限制与可靠性要点
- 在履约前需在服务端重新核实支付成功状态。
- 存储 provider ids、内部 ids、tx_ref 和 event ids 以便对账。
- 保持 webhook 消费者幂等,并快速返回 HTTP 200。
- 分离不同版本的请求/响应类型,避免 schema 混淆。
- v4 在公开参考中是资源中心化的,应在代码中保持路由映射和载荷类型的版本化,以确保代理生成的集成保持准确。
暂未提供的信息
资料中未提供具体的收费、价格、平台支持范围、性能效果或完整的分步使用教程。