用途 flutterwave-virtual-accounts 用于创建和管理专用虚拟账户,从而通过银行转账的方式完成收款。资料将其定位为一项围绕 Flutterwave 虚拟账户能力的集成技能。
主要能力
- 提供 TypeScript 实现模式,包含 v3 与 v4 两个基础地址的读取方式(FLW_V3_BASE_URL、FLW_V4_BASE_URL),默认值分别为 https://api.flutterwave.com/v3 与 https://developersandbox-api.flutterwave.com。
- 通过环境变量 FLW_SECRET_KEY 读取密钥;缺失时抛出错误。
- 统一请求函数 flwRequest 负责拼接地址、设置 Content-Type 为 application/json、使用 Bearer 密钥进行认证,并把响应解析为 FlwResponse;当响应非成功或状态为 error 时抛出 FlutterwaveApiError,其中携带消息、状态码与响应载荷。
- 端点操作表:v3 提供 POST /virtual-account-numbers 创建专用账户;v4 提供 POST /virtual-accounts 创建虚拟账户、GET /virtual-accounts 列出虚拟账户、GET /virtual-accounts/{id} 查询账户、PUT /virtual-accounts/{id} 更新账户。
- 国家与通道矩阵:NGN 面向高并发的转账收款场景;KES/GHS 提供区域性虚拟账户支持,需按商户资料确认产品可用性;ZAR 用于本地转账收款,建议按账户 reference 与 tx_ref 对账。
- 可靠性清单:履约前在服务端重新核验支付成功状态;存储提供方 id、内部 id、tx_ref 与事件 id 以便对账;保证 webhook 消费幂等并快速返回 HTTP 200;按版本区分请求与响应类型,避免 schema 混淆。
使用方式 资料给出一个示例函数 runVirtualAccountsExample,它调用 flwRequest("v4", "/virtual-accounts", { method: "GET" }),即获取 v4 虚拟账户列表。集成时可按端点表替换路径与请求方法,并按需选择 v3 或 v4。资料还附带 v4 的说明:公开参考文档以资源为中心,因此代码中应保留带版本的请求路由映射与载荷类型。
适用场景 适合需要在后端或全栈项目中接入 Flutterwave 虚拟账户收款的开发者,尤其是涉及 NGN、KES/GHS、ZAR 市场银行转账收款的集成场景,以及对账、支付状态复核与 webhook 处理相关的工程实现。
限制与暂未提供 资料未提供具体的收费与价格、账户开通条件、完整请求参数与响应字段定义、各市场的实际可用性保证,以及完整的错误码列表。KES/GHS 的可用性需按商户资料验证。以上未提及的细节均暂未提供。