BVN 认证流程
1. 业务目标
BVN 认证用于确认用户填写的 BVN 与其银行账户归属一致，并为后续 Google 人脸、客户建档、绑卡和放款账户归档提供可信身份基础。
BVN + 银行账户验证由 BNS 发起，PMT 负责封装并调用三方支付 / 验证供应商接口。MVP 优先使用 Monnify；Paystack 后续再考虑，不作为本期主链路。
2. 页面流程
- 在 add account name 页面选择
name of your bank。 - 输入
bank account number。 - 下一步输入 11 位 BVN。
- 用户点击提交后，开始服务端验证。
3. 本期系统时序
sequenceDiagram participant App as App participant BNS as BNS participant PMT as PMT participant Monnify as Monnify App->>BNS: 提交 bankCode + accountNumber + bvn + deviceId BNS->>BNS: 校验登录态、字段格式、实名状态、重复提交 BNS->>PMT: verifyBvnBankAccount(uid, bankCode, accountNumber, bvn, scene) PMT->>Monnify: GET /api/v1/disbursements/account/validate Monnify-->>PMT: accountName + bankCode + accountNumber PMT->>Monnify: POST /api/v1/vas/bvn-account-match Monnify-->>PMT: matchStatus / responseCode / responseMessage PMT->>PMT: 记录供应商请求、原始响应、标准化验证结果 PMT-->>BNS: verified + accountName + matchStatus + providerTraceId BNS->>BNS: 更新 BVN 验证流水和客户账户快照 BNS-->>App: 通过则进入 Google 人脸；失败则提示修改 BVN/银行/账号
4. 调用口径
- 用户提交 BVN 后，需要立即发起服务端验证。
- App 提交给 BNS，不直接调用三方。
- BNS 做登录态、字段格式、实名状态、重复提交等基础业务校验。
- BNS 调用 PMT 的内部验证能力，PMT 负责对接 Monnify。
- 本期只把 Monnify 作为主路径；Paystack 后续再考虑。
- 验证通过后，BNS 才允许进入 Google 人脸流程或继续绑卡 / 放款账户归档。
- 验证失败时，不进入人脸流程，不创建客户，不写实名通过状态。
5. Monnify 接口说明（本期优先）
参考文档：
- Monnify Verification APIs：https://developers.monnify.com/api#tag/verification-apis/
- Monnify Verifying your Customers：https://monnify-docs.playground.monnify.com/docs/verification-api/verifying-your-customers
5.1 Access Token
调用 Monnify 业务接口前，PMT 需要先取得 OAuth Bearer Token。
| 项目 | 内容 |
|---|---|
| 接口名 | Login / Generate Access Token |
| Method | POST |
| Endpoint | /api/v1/auth/login |
| 用途 | 使用 Monnify API Key / Secret 获取 Bearer Token |
| 本期处理 | PMT 缓存 token，并处理过期重取 |
5.2 Name Enquiry / Validate Bank Account
第一步先校验银行账号是否存在，并解析供应商登记户名。
| 项目 | 内容 |
|---|---|
| 接口名 | Name Enquiry / Validate Bank Account |
| Method | GET |
| Endpoint | /api/v1/disbursements/account/validate |
| Query | accountNumber、bankCode |
| 用途 | 查询 bankCode + accountNumber 对应的账户户名 |
| 关键出参 | requestSuccessful、responseCode、responseMessage、responseBody.accountName、responseBody.accountNumber、responseBody.bankCode |
| 通过口径 | requestSuccessful=true 且 responseCode=0，并返回有效 accountName |
| 失败口径 | 账号不存在、bankCode 无效、银行暂不可用、Monnify 服务异常 |
5.3 BVN and Account Name Match
第二步校验 BVN 与银行账户是否匹配。本期核心通过条件来自该接口。
| 项目 | 内容 |
|---|---|
| 接口名 | BVN and Account Name Match / BVN and Account Name Validation |
| Method | POST |
| Endpoint | /api/v1/vas/bvn-account-match |
| Body | bvn、bankCode、accountNumber |
| 用途 | 验证 BVN 是否与该银行账户归属匹配 |
| 关键出参 | requestSuccessful、responseCode、responseMessage、responseBody.matchStatus |
| 通过口径 | requestSuccessful=true、responseCode=0，且 matchStatus=MATCHED |
| 失败口径 | matchStatus=NO_MATCH / PARTIAL_MATCH、BVN 无效、账户不匹配、服务不可用 |
| 环境限制 | Monnify 文档说明 Name Enquiry 可用于 Sandbox / Live，其余验证接口通常仅 Live 可用；上线前需确认商户权限和余额 |
6. Paystack 接口说明（后续考虑，本期不考虑）
参考文档：
- Paystack Verification API：https://paystack.com/docs/api/verification/
- Paystack Verify Account Number：https://paystack.com/docs/identity-verification/verify-account-number/
Paystack 不作为本期 BVN 认证主链路。当前可明确用于尼日利亚账户的是账户号解析；是否能完成 BVN 与银行账户归属关系验证，需要后续联调确认。
6.1 Resolve Account Number
| 项目 | 内容 |
|---|---|
| 接口名 | Resolve Account Number / Resolve Account |
| Method | GET |
| Endpoint | /bank/resolve |
| Query | account_number、bank_code |
| 用途 | 查询银行账户户名，确认账号与银行代码能解析成功 |
| 关键出参 | status、message、data.account_number、data.account_name |
| 可用性 | Paystack 文档说明 Nigeria / Ghana 可用 |
| 本期处理 | 作为账户姓名核验 |
6.2 Validate Account
| 项目 | 内容 |
|---|---|
| 接口名 | Validate Account |
| Method | POST |
| Endpoint | /bank/validate |
| Body | account_name、account_number、account_type、bank_code、country_code、document_type、document_number |
| 用途 | 验证账户真实性和账户持有人信息 |
| 文档限制 | Paystack Verify Account Number 文档提示该能力当前用于 South Africa 场景；API 文档中的示例 country_code=ZA |
| 本期处理 | 不进入 MVP 主链路；后续如要使用，必须先确认 Nigeria + BVN 的支持口径 |