用途
flutterwave-virtual-cards 用于在安全的内部抽象层中建模 Flutterwave 虚拟卡的发行与生命周期控制。它面向需要集成 Flutterwave 虚拟卡能力的开发者,提供一套 TypeScript 实现模式,将 Flutterwave API 调用封装为可复用的请求函数,并强调版本隔离、错误处理与对账可靠性。
主要能力
该技能提供以下能力:
- 配置 Flutterwave v3 与 v4 的基础 URL,支持通过环境变量覆盖默认值。
- 校验 FLW_SECRET_KEY 环境变量,缺失时抛出错误。
- 定义统一的 FlwResponse 响应类型,包含 status、message 和 data 字段。
- 定义 FlutterwaveApiError 错误类,携带状态码和原始响应负载。
- 提供 flwRequest 异步函数,根据版本选择基础 URL,自动附加 Content-Type 与 Authorization 请求头,并在响应非成功或 status 为 error 时抛出 FlutterwaveApiError。
- 列出虚拟卡相关端点操作,包括 v3 的创建虚拟卡(POST /virtual-cards)、充值卡(POST /virtual-cards/{id}/fund),以及 v4 的创建可复用支付方式对象(POST /payment-methods)和追踪卡相关扣费活动(GET /charges)。
- 提供国家/通道矩阵,涵盖 USD 卡跨境消费、尼日利亚卡充值来源以及所有市场的卡状态控制(通过策略检查进行封禁/解封)。
- 提供可靠性检查清单,包括服务端重新验证支付状态、存储提供方 ID、内部 ID、tx_ref 和事件 ID 用于对账、保持 webhook 消费者幂等并快速返回 HTTP 200、分离版本特定的请求/响应类型以避免模式混淆。
- 提供 v4 差异说明,指出 v4 在公开参考中是资源中心化的,建议在代码中保持路由映射和负载类型的版本化。
使用方式
该技能以 TypeScript 代码模式呈现。开发者需要设置环境变量 FLW_V3_BASE_URL、FLW_V4_BASE_URL 和 FLW_SECRET_KEY。默认 v3 基础 URL 为 https://api.flutterwave.com/v3,v4 基础 URL 为 https://developersandbox-api.flutterwave.com。通过调用 flwRequest 函数并传入版本、路径和可选的 RequestInit 参数来发起请求。示例用法展示了如何调用 v4 的 /payment-methods 端点。
适用场景
适用于需要在内部系统中安全集成 Flutterwave 虚拟卡发行、充值、支付方式管理和扣费追踪的开发者。特别适合需要处理多版本 API、要求对账可靠性和 webhook 幂等性的支付集成场景。
限制
资料中未提供具体的收费、价格、平台支持范围或实际使用效果信息。该技能主要提供实现模式和端点参考,不包含完整的业务逻辑实现。使用前需自行确保符合 Flutterwave 的 API 使用条款和合规要求。