SuperAPI AI 工具集

flutterwave-bills

编程与开发

查看项目

更新于 11-05 16:19

技能介绍

用途

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 在公开参考中是资源中心化的,应在代码中保持路由映射和载荷类型的版本化,以确保代理生成的集成保持准确。

暂未提供的信息

资料中未提供具体的收费、价格、平台支持范围、性能效果或完整的分步使用教程。