用途
flutterwave-verification 用于在支付或打款操作之前执行账户与身份校验。其目标是在实际发起付款或转账前完成预检,从而降低支付与转账的失败率。
主要能力
该技能围绕 Flutterwave API 提供以下端点操作:
| 版本 | 方法 | 路由 / 操作 | 用途 |
|---|---|---|---|
| v3 | GET | /accounts/resolve | 解析银行账户 |
| v4 | POST | /bank-account-resolve | 解析银行账户详情 |
| v4 | POST | /wallet-account-resolve | 解析钱包账户 |
| v4 | GET | /banks | 获取银行列表 |
使用方式
该技能以 TypeScript 实现,核心是一个统一的请求函数 flwRequest,负责拼接基础 URL、注入鉴权头、解析响应并在出错时抛出 FlutterwaveApiError。
基础 URL 通过环境变量配置:
- FLW_V3_BASE_URL,默认 "https://api.flutterwave.com/v3"
- FLW_V4_BASE_URL,默认 "https://developersandbox-api.flutterwave.com"
- FLW_SECRET_KEY,用于 Authorization 头
请求函数签名如下:
async function flwRequest(
version: "v3" | "v4",
path: string,
init: RequestInit = {},
): Promise<FlwResponse>
若缺少 FLW_SECRET_KEY,会抛出 "Missing FLW_SECRET_KEY" 错误。请求会带上 Content-Type: application/json 与 Authorization: Bearer ${FLW_SECRET_KEY}。当响应非 OK 或 body.status 为 "error" 时,抛出 FlutterwaveApiError,包含消息、状态码与原始 payload。
使用示例:
export async function runVerificationExample() {
return flwRequest<unknown>("v4", "/bank-account-resolve", {
method: "GET",
});
}
适用场景
根据国家 / 通道矩阵:
| 市场 | 通道 | 集成说明 |
|---|---|---|
| NG | 账户解析 | 打款前必须执行。 |
| KE/GH | 钱包查询 | 用于 MoMo 收款人校验。 |
| 全部 | 预检 | 降低支付与转账失败率。 |
可靠性清单
- 在履约前,服务端重新校验支付成功状态。
- 存储 provider ids、内部 ids、tx_ref 与 event ids 以便对账。
- 保持 webhook 消费者幂等,并快速返回 HTTP 200。
- 分离不同版本的请求 / 响应类型,避免 schema 混淆。
v4 差异说明
v4 在公开参考中是资源导向的。应在代码中为路由映射与 payload 类型保留版本信息,以确保代理生成的集成保持准确。
限制
资料未提供该技能的收费、价格、平台支持范围、具体效果指标或完整安装步骤,这些信息暂未提供。