Monnify 各支付方式对 NIN 的支持情况

结论：Monnify Card Tokenization 与 WebPay 不要求、也不消费客户 NIN，因此 NIN 客户可兼容使用，但不能据此认定 NIN 已核验。Monnify 业务指南宣称 Reserved Account 可关联 BVN 或 NIN，但 2026-08-24 的 API Reference 仍将创建账户的 bvn 标为必传，并将 KYC 更新的 bvn、nin 同时标为必传。因此当前只能确认 BVN-only 和 BVN+NIN 路径；NIN-only 开户/更新在取得 Monnify 书面说明和真实成功样例前不得上线。

1. 目标与适用范围

本文用于明确已完成 NIN KYC 的尼日利亚客户，在以下 Monnify 支付方式中的准入和处理规则：

银行卡首次支付、Token 生成及后续 Token 扣款；
Customer Reserved Account / Invoice Reserved Account；
WebPay / Hosted Checkout，以及其中一次性动态转账账户；
支付方式展示、身份资料使用、失败降级、埋点和验收。

本文不把支付成功当作 KYC 成功，不展开接口、报文、SDK 或代码实现。NIN 的采集、核验和保存仍归属 KYC / 风控体系。

2. 支持口径

口径	定义
原生支持 NIN	供应商明确允许该支付能力关联或使用 NIN
兼容 NIN 客户	该支付方式不需要 BVN/NIN，NIN 客户可使用，但供应商不消费或核验 NIN
有条件支持	NIN 可满足基础准入，但额度、来源限制或商户配置仍有附加条件
待商务确认	公开能力存在，但当前商户号权限、限额、费率、银行覆盖或生产开通状态尚未确认

3. 能力结论

支付方式	Monnify 模式	对 NIN 的结论	NIN 客户能否使用	关键边界
绑卡	首次成功卡支付后生成 Card Token	兼容 NIN 客户，不原生消费 NIN	可以	商户需开通 Tokenization；是否产出 Token 以供应商实际结果为准
后续扣款	使用 Card Token 扣款	兼容 NIN 客户，不原生消费 NIN	可以	Token 与原客户信息、商户和卡归属保持一致；支付结果不代表 NIN 已核验
Customer Reserved Account	为客户保留长期虚拟账户	指南支持 NIN，但接口模型冲突	BVN+NIN 可以；NIN-only 待确认	当前 API Reference 创建模型要求 `bvn`，`nin` 为可选；最高交易限额按指南需同时关联二者
Invoice Reserved Account	为重复开票客户保留账户，激活发票期间收款	指南支持 NIN，但接口模型冲突	BVN+NIN 可以；NIN-only 待确认	当前 API Reference 同样要求 `bvn`；账户是否可收款还取决于有效发票状态
WebPay	Hosted Checkout / Redirect	兼容 NIN 客户，不原生消费 NIN	可以	WebPay 初始化和支付结果不依赖 NIN；一次性动态转账账户不是 Reserved Account

4. 接口传参规则（API Reference 2026-08-24）

4.1 统一认证

除获取访问令牌外，下列接口均在请求头传递 Authorization: Bearer {accessToken}。NIN/BVN 只允许放在明确声明对应字段的 JSON 请求体中，不得放入 URL、Header、metadata、支付备注或日志。

4.2 NIN Verification

项目	当前 API Reference	业务指南	处理结论
请求路径	`POST /api/v1/vas/nin-details`	示例使用 `POST /api/v1/vas/nin-verification`	官方资料冲突；生产接入前由 Monnify 书面确认当前商户应使用的路径
请求体	`nin` 必传	`nin` 必传	只传 11 位 NIN，不附带 BVN
环境	仅 Live Mode	仅 Live Mode	Sandbox 不能完成真实 NIN 验证
成功结果	API Reference 返回身份详情	指南示例另含 `ninInformationMatch`	不预设字段；以商户 Live 响应样例确认最终成功判定

候选请求体：

{
  "nin": "{VERIFIED_11_DIGIT_NIN}"
}

在路径和成功响应未确认前，该接口状态只能记为“待验证”，不得把 HTTP 200、requestSuccessful=true 或返回姓名单独视为 NIN 归属核验成功。

4.3 创建 General Reserved Account

接口：POST /api/v2/bank-transfer/reserved-accounts

当前 API Reference 必传字段：

字段	当前必传	NIN 场景规则
`accountReference`	是	使用我方唯一、不可重复的客户账户引用
`accountName`	是	使用已核验客户姓名生成，不使用 NIN 原文
`currencyCode`	是	尼日利亚场景传 `NGN`
`contractCode`	是	使用当前 Monnify 商户合同号
`customerEmail`	是	使用该客户在当前商户下的稳定邮箱
`customerName`	是	使用已核验客户姓名
`bvn`	是	当前模型不允许 NIN-only 省略；只能传真实、已核验 BVN
`nin`	否	需要关联 NIN 时传真实、已核验的 11 位 NIN
`getAllAvailableBanks`	是	按账号池方案传布尔值
`preferredBanks`	是	传银行代码数组；即使 `getAllAvailableBanks=true`，当前模型仍标记必传，需联调确认实际约束

当前可安全执行的 BVN-only 请求：

{
  "accountReference": "{UNIQUE_ACCOUNT_REFERENCE}",
  "accountName": "{CUSTOMER_ACCOUNT_NAME}",
  "currencyCode": "NGN",
  "contractCode": "{CONTRACT_CODE}",
  "customerEmail": "{CUSTOMER_EMAIL}",
  "customerName": "{VERIFIED_CUSTOMER_NAME}",
  "bvn": "{VERIFIED_11_DIGIT_BVN}",
  "getAllAvailableBanks": true,
  "preferredBanks": ["50515"]
}

需要关联 BVN+NIN 时，在上述请求中增加：

{
  "nin": "{VERIFIED_11_DIGIT_NIN}"
}

NIN-only 请求当前不允许落地：不得省略 bvn 后直接调用，不得传 "bvn": ""、null、占位值，也不得把 NIN 写入 bvn。只有 Monnify 明确修改必填规则或提供其他正式接口，并给出成功请求/响应后，才能启用 NIN-only。

4.4 创建 Invoice Reserved Account

接口：POST /api/v1/bank-transfer/reserved-accounts

当前必传字段为 contractCode、accountName、currencyCode、accountReference、customerEmail、customerName、reservedAccountType 和 bvn；nin 为可选。reservedAccountType 固定传 INVOICE。

{
  "contractCode": "{CONTRACT_CODE}",
  "accountName": "{CUSTOMER_ACCOUNT_NAME}",
  "currencyCode": "NGN",
  "accountReference": "{UNIQUE_ACCOUNT_REFERENCE}",
  "customerEmail": "{CUSTOMER_EMAIL}",
  "customerName": "{VERIFIED_CUSTOMER_NAME}",
  "reservedAccountType": "INVOICE",
  "bvn": "{VERIFIED_11_DIGIT_BVN}",
  "nin": "{VERIFIED_11_DIGIT_NIN}"
}

按当前模型，Invoice Reserved Account 同样不能用 NIN 替代必传 bvn。仅创建 Dynamic Invoice 时不需要 BVN/NIN，但动态发票账户是单笔临时账户，不得当作长期 Reserved Account。

4.5 更新 Reserved Account KYC

接口：PUT /api/v1/bank-transfer/reserved-accounts/{accountReference}/kyc-info

当前 API Reference 把 bvn 和 nin 都列为必传，与业务指南所述“可传 BVN、NIN 或两者”不一致。当前只能按以下完整请求联调：

{
  "bvn": "{VERIFIED_11_DIGIT_BVN}",
  "nin": "{VERIFIED_11_DIGIT_NIN}"
}

在 Monnify 确认前，不得用该接口执行 NIN-only 更新。旧接口 PUT /api/v1/bank-transfer/reserved-accounts/update-customer-bvn/{reservedAccountReference} 只更新 BVN，不具备 NIN 语义。

4.6 其他支付接口

接口/能力	是否传 NIN	规则
初始化 WebPay：`POST /api/v1/merchant/transactions/init-transaction`	否	按金额、客户邮箱、支付参考、币种、合同号等支付字段初始化；不得把 NIN 放入 `metadata`
单次动态转账账户	否	使用初始化交易后的交易引用生成；该账户不是长期 Reserved Account
Card Token 扣款：`POST /api/v1/merchant/cards/charge-card-token`	否	传 Card Token、金额、首次支付使用的客户邮箱、支付参考、合同号和 API Key 等；NIN 不参与 Token 匹配
Add Linked Accounts	否	仅对已创建的 Reserved Account 增加合作银行账号，沿用原账户 KYC，不重复传 NIN
Reserve Account with Limit	当前模型无 BVN/NIN 字段	不作为 NIN 开户绕过路径；须先让 Monnify 澄清其与 KYC 规则的关系
Allowed Payment Sources	不传 NIN	只按 BVN、账户名或银行账号限制资金来源，NIN 不能用于来款匹配

5. 产品决策

5.1 绑卡与 Card Token 扣款

用户 KYC 身份类型为 NIN 时，不因缺少 BVN 而隐藏或阻断 Monnify 绑卡入口。
首次卡支付前应取得用户对保存支付凭证并用于后续扣款的明确授权。
只有首次卡支付成功且供应商实际返回可用 Token 时，才把银行卡标记为“已绑定、可后续扣款”。
页面支付成功但未返回 Token、卡不支持 Tokenization、Token 无效或已过期时，不得保存为可扣款卡。
Token 仅在原商户、原客户和约定业务范围内使用；不得因 NIN 相同而跨客户、跨业务线或跨商户复用。
NIN 不发送到卡支付备注、扩展信息、跳转地址或前端页面。

5.2 Customer Reserved Account

仅使用 KYC 已采集、已保存、格式有效且通过既定核验的 NIN；不得临时从支付页面重新采集或要求用户通过客服提供。
NIN-only 客户在业务目标上可申请有限额度 Reserved Account，但当前接口模型仍要求 bvn；取得 Monnify 书面确认和真实成功样例前，不发起账户创建，不展示可收款账号。
需要最高交易限额的客户必须同时具备有效 BVN 与 NIN。只有 NIN 时，不得展示或承诺最高额度。
已有 Reserved Account 可按供应商支持的 KYC 更新能力补充 NIN/BVN；更新成功前沿用原额度与状态。
账户收款来源限制仍按供应商支持的 BVN、账户名或账户号规则处理。NIN 已关联不等于可以按 NIN 识别来款账户，也不等于来款人一定是账户持有人。
同一客户的 Reserved Account 和多个银行账号分配规则继续遵循 19-Monnify虚拟账号按bizCode归属管理；不得为绕过限制伪造邮箱、身份信息或重复客户。
Invoice Reserved Account 只有在关联有效发票时才可收款；NIN 只解决预留账户 KYC 条件，不改变发票激活规则。

5.3 WebPay 与一次性动态转账账户

NIN 客户可正常进入 Monnify WebPay，不新增 NIN 输入项。
WebPay 中按单次交易生成的动态转账账户属于一次性支付能力，不得当作客户长期 Reserved Account 保存或展示。
用户从 Monnify 页面返回仅表示流程返回；订单支付结果以服务端确认的交易状态和金额为准。
WebPay 成功不更新 NIN 核验状态；NIN 核验成功也不预判 WebPay 一定成功。
支付失败、取消、处理中或未知结果时，保留原订单和原支付参考，先查询原交易，再决定是否允许重试或切换通道。

6. 前置条件与状态规则

KYC 已输出可信的身份类型和核验状态；支付系统只在 Reserved Account 场景按授权使用已保存身份资料。
当前业务线和商户号已启用对应 Monnify 能力，且用户、订单、金额和支付方式均满足既有支付准入条件。
绑卡按“未发起—处理中—已绑定/失败”管理；只有实际获得可用 Token 后进入“已绑定”。
Reserved Account 按“未申请—校验中—创建/更新中—有限额度可用/最高额度可用/失败”管理，额度状态由实际关联的身份资料和供应商结果决定。
WebPay 按“待支付—处理中—成功/失败/取消/未知”管理；未知结果必须查询原交易，不得直接按失败重开。
任一支付或账户状态都不得覆盖 KYC 状态；任一 KYC 状态也不得伪造支付、Token 或账户创建成功。

7. 角色与责任边界

责任方	责任
KYC / 风控	采集、核验并保存 NIN/BVN；输出身份类型、核验状态和可使用范围；决定有限额度或最高额度资格
支付中台	按 KYC 结果申请或更新 Reserved Account；保存 Token、账户和支付真实状态；不将支付成功反写为 KYC 成功
App / H5	展示可用支付方式、账户额度档位和最终结果；不重复采集或展示完整 NIN
运营 / 客服	使用稳定失败分类处理补件和重试；不得在工单、聊天、截图或日志中留存完整 NIN、Token 或账户信息

8. 异常与边界场景

场景	处理规则
NIN 缺失、格式无效或未核验	不传 `nin`，不申请依赖 NIN 的账户能力；绑卡和 WebPay 可按各自条件继续
NIN-only 客户申请 Reserved Account	当前不调用创建/更新接口；进入“供应商能力待确认”，提供 WebPay、卡支付或其他可用方式
仅有 NIN，用户要求最高额度	明确提示需补充并核验 BVN；不得先按最高额度开通
Reserved Account 创建处理中或超时	不展示账号；保留处理中并查询原申请结果，禁止重复创建
NIN 与供应商校验不一致	保持账户未开通/未升级，返回稳定错误分类并引导回 KYC 处理
首次卡支付成功但无 Token	支付可按真实结果入账；绑卡仍失败或不可用于后续扣款
Token 过期或失效	停止后续扣款并引导用户重新完成一次卡支付和授权
WebPay 生成动态账户	仅用于当前交易和有效期，不写入客户长期虚拟账户资产
已有关联 BVN 的历史账户补 NIN	仅在更新成功后提升对应额度资格；失败不影响原有已确认账户状态

9. 前端埋点要求

页面/场景与 owner	关键事件	唯一触发时机	核心属性及来源	指标/漏斗
还款方式页，App/H5	`payment_method_view`	可用支付方式列表首次完整展示	`provider`、`payment_method`、`kyc_id_type`、`eligibility_result`，来自服务端资格结果	各身份类型支付方式可见率
绑卡页，App/H5	`bind_card_submit`	用户确认提交绑卡且请求实际发出一次	`provider=monnify`、`kyc_id_type`、`session_id`	绑卡提交率
绑卡结果页，App/H5	`bind_card_result`	收到可信业务结果并首次展示	`provider=monnify`、`status`、`error_code`、`tokenization_supported`，来自服务端结果	绑卡成功率、Token 产出率
虚拟账户页，App/H5	`virtual_account_result`	服务端返回最终创建/更新结果并首次展示	`provider=monnify`、`kyc_id_type`、`limit_tier`、`status`、`error_code`	NIN 开户成功率、额度升级成功率
支付结果页，App/H5	`payment_result`	服务端确认结果并首次展示	`provider=monnify`、`payment_method`、`status`、`error_code`、真实 `trace_id`	WebPay 成功率、未知结果率

埋点不得包含 NIN 原文、BVN、卡号、账户号、OTP、姓名、原始错误文本、Card Token 或供应商原始响应。event_name、event_page 均使用稳定值；支付和虚拟账户成功/失败必须来自可信业务结果，不能用按钮点击或页面跳回代替。

10. 验收标准

NIN-only 客户可完成 Monnify 绑卡并在实际产出 Token 后获得可后续扣款状态。
NIN-only 客户可使用 Monnify WebPay，页面和支付链路不新增 NIN 输入或透传。
已核验 NIN 但无 BVN 的客户不会向当前创建接口发送空、伪造或错位的 bvn；在供应商确认前不触发账户创建。
只有同时具备有效 NIN 与 BVN 的客户才能获得最高额度资格。
NIN 关联不被用于来款来源匹配；来源限制继续按供应商支持的规则执行。
一次性动态转账账户与长期 Reserved Account 在展示、保存、有效期和入账匹配上完全区分。
绑卡、WebPay、虚拟账户和 KYC 状态相互独立，任何支付成功都不会被当作 NIN 核验成功。
所有前端事件满足稳定命名、单次触发、属性来源明确和敏感信息不采集要求。
上线前已取得 NIN Verification 的正式路径与成功响应样例，并用当前商户号确认 Tokenization、Reserved Account、KYC 更新、额度档位、支持银行和 WebPay 的生产权限。
NIN-only 创建和更新只有在 Monnify 明确传参契约、成功条件且完成真实环境验证后才能验收通过。

11. 官方依据与待确认项

官方资料核对日期：2026-08-24。

上线前仍需 Monnify 书面确认：① NIN Verification 应使用 /nin-details 还是 /nin-verification；② General/Invoice Reserved Account 是否真的允许 NIN-only，以及 bvn 如何从必传调整；③ Update KYC 是否允许只传一个身份字段；④ getAllAvailableBanks=true 时 preferredBanks 是否仍必传；⑤ 当前商户主体的 Tokenization 和 NIN Reserved Account 是否已开通；⑥ 有限额度与最高额度实际数值、支持银行、费率和处理时效。Monnify 公开资料说明身份验证能力为 Live Mode，且 Sandbox 不返回真实 Card Token，因此测试环境结果不能代替生产权限和完整链路确认。未确认前按本文保守边界执行。

袋鼠金融蓝图

探索

File History