跳转到主要内容
虚拟账户 API 提供用于管理与主钱包或子地址关联的虚拟银行账户的端点。此 API 使企业能够为客户创建虚拟账户以接收付款、检索虚拟账户详情以及激活/停用虚拟账户。

​
简介

虚拟账户允许您的客户通过传统银行转账接收法币付款，这些付款会自动转换为区块链上的稳定币。这在传统银行业务和稳定币支付之间架起了桥梁，为您的业务提供无缝的支付处理能力。 当客户向虚拟账户发送法币时，系统可以自动铸造等值的稳定币并将其转移到关联的钱包或地址，提供实时支付处理能力。

​
虚拟账户工作原理

账户创建

创建与主钱包或子地址关联的虚拟账户，并包含客户信息。

收款

客户使用传统银行转账向虚拟账户发送法币付款。

自动充值

对于 AUTO_FUNDING 类型的账户，付款会自动触发稳定币铸造。

资金管理

铸造的稳定币会转移到关联的钱包或地址以供即时使用。

​
虚拟账户类型

虚拟账户支持不同类型，具有不同的行为：

​
AUTO_FUNDING（默认）

  • 收到法币付款时自动铸造稳定币
  • 立即将稳定币转移到关联的钱包/地址
  • 最适合实时支付处理
  • 提供从法币到稳定币的即时转换
自动充值流程仅适用于 AUTO_FUNDING 类型的虚拟账户。其他类型具有不同的处理行为。

​
工作原理 - 自动充值流程

当客户向类型为 AUTO_FUNDING 的虚拟账户发送法币时：

​
1. 收款

付款通过传统银行转账进入虚拟账户。此阶段会触发 deposit.processing Webhook。

​
2. 自动铸造

系统在区块链上自动铸造等值的稳定币。

​
3. 区块链转账

铸造的稳定币会转移到虚拟账户关联的钱包或地址。成功完成后会触发 deposit.success Webhook。
自动充值流程仅适用于 AUTO_FUNDING 类型的虚拟账户。其他类型具有不同的处理行为。

​
前提条件

创建虚拟账户之前，请确保：
  • 必须完成合规要求（请参阅下方合规要求部分）
  • 必须为您的企业启用虚拟账户功能（合规批准后，请联系 [email protected] 或使用控制面板上的在线聊天来启用该功能）
  • 仅在主网环境中可用（测试网不可用）
  • 主钱包必须支持稳定币资产 - 您的账户套餐必须包含稳定币访问权限（如需要，请从控制面板 → 设置 → 订阅进行升级）
环境：虚拟账户仅在主网环境中可用。测试网环境不支持虚拟账户的创建或操作。

​
合规要求

在申请访问虚拟账户功能之前，您必须完成合规入驻流程。需要以下文件和信息：

​
所需文件

  1. 您企业的公司注册证书和股东名单（例如，尼日利亚 CAC 的 MEMART 文件）
  2. 近期水电费账单以确认企业地址
  3. 最终受益所有人（UBO）和董事的身份证件
  4. 税务证明/TIN
  5. 公司 KYC 政策
  6. 公司 AML/CFT/CPF 政策
  7. 最终受益所有人和董事的近期水电费账单

​
提交合规文件

通过电子邮件将所有必需文件和信息提交给合规团队：
合规审核流程必须完成后，才能为您的企业启用虚拟账户。请确保所有文件是最新的且格式正确后再提交。

​
支持的货币

  • 法币：NGN（尼日利亚奈拉）- 传统银行转账
  • 稳定币：cNGN - 在区块链上自动铸造（适用于 AUTO_FUNDING 类型）

​
API 端点

以下是虚拟账户操作的核心 API 端点：

​
主钱包端点

​
子地址端点

​
创建虚拟账户

您可以为主钱包和子地址创建虚拟账户，具体取决于您的使用场景。使用创建虚拟账户 API（主钱包）或子地址创建虚拟账户 API。

​
请求参数

参数类型必需描述
firstnamestring是客户名字
lastnamestring是客户姓氏
emailstring是客户邮箱地址（每个企业必须唯一）
phonestring是客户电话号码，格式：+234XXXXXXXXXX

​
响应示例

{
  "data": {
    "id": "8180309e-1ead-4a72-a013-b5674600ce4c",
    "accountName": "John Doe",
    "accountNumber": "9018927611",
    "bankName": "Polaris Bank",
    "bankCode": "076",
    "currency": "NGN",
    "type": "AUTO_FUNDING",
    "isActive": true,
    "status": "ACTIVE",
    "reference": "20",
    "customer": {
      "id": "caa17eb8-4da8-45b4-a866-81dd0a1df613",
      "name": "John Doe",
      "email": "[email protected]",
      "phone": "+2348161846125",
      "status": "ACTIVE",
      "network": "mainnet"
    },
    "wallet": {
      "id": "35e964a6-436a-424f-bf3a-618cc060feea",
      "name": "Base Wallet",
      "address": "0xD8582C57E56Ef45f9fe82870aDF63d9baB89e1F7"
    },
    "createdAt": "2025-11-06T18:30:34.286Z",
    "updatedAt": "2025-11-06T18:30:34.286Z"
  },
  "message": "Virtual account created successfully",
  "statusCode": 201
}

​
检索虚拟账户

要检索虚拟账户详情，请使用获取虚拟账户 API（主钱包）或获取虚拟账户 API（子地址）。

​
更新虚拟账户

您可以激活或停用虚拟账户以控制自动充值行为。使用更新虚拟账户 API（主钱包）或更新虚拟账户 API（子地址）。

​
自动充值行为

  • 活跃账户：收到付款触发自动稳定币铸造
  • 非活跃账户：可以收款但自动充值被禁用

​
更新参数

参数类型必需描述
isActiveboolean是true 激活，false 停用
当虚拟账户被停用（isActive: false）时，仍可以收款，但自动稳定币铸造和转账过程被禁用。您可以随时重新激活账户以恢复自动充值。

​
Webhooks

虚拟账户在收到和处理付款时触发 Webhook 事件。对于 AUTO_FUNDING 类型的账户，您将在付款处理流程的每个阶段收到 Webhook 通知。

​
Webhook 事件

当客户向类型为 AUTO_FUNDING 的虚拟账户发送法币付款时：
  1. deposit.processing - 当虚拟账户收到法币付款时立即触发。这表示付款已被检测到，铸造过程即将开始。
  2. deposit.success - 当稳定币成功铸造并转移到关联的钱包或地址时触发。这确认整个自动充值流程已完成。
  3. deposit.failed - 如果铸造或转账过程在任何环节失败时触发。
  4. deposit.cancelled - 如果交易在完成前被取消时触发。

​
Webhook 载荷

Webhook 载荷遵循标准充值 Webhook 格式。交易 type 为 DEPOSIT，status 字段反映当前状态（PROCESSING、SUCCESS、FAILED 或 CANCELLED）。
Webhook 仅对活跃的虚拟账户（isActive: true）触发。如果账户被停用，可能仍会收到付款，但在账户重新激活之前不会发送 Webhook 事件。
有关 Webhook 设置、载荷结构和事件处理的更多信息，请参阅 Webhooks 文档。

​
使用场景

​
电子商务支付

为客户创建虚拟账户以接收产品或服务付款。自动转换为稳定币使其能够与您基于区块链的支付系统无缝集成。

​
订阅服务

将虚拟账户链接到客户订阅，允许通过传统银行转账进行定期付款，这些付款会自动转换为稳定币。

​
市场交易

启用点对点交易，客户可以发送法币付款，这些付款会立即转换为稳定币并记入其钱包。

​
汇款服务

为客户提供虚拟账户以接收 NGN 汇款，这些汇款会自动转换为稳定币以便于跨境转账。

​
最佳实践

​
账户管理

  • 唯一邮箱地址：确保每个客户有唯一的邮箱地址
  • 电话号码格式：始终使用正确的尼日利亚电话号码格式（+234XXXXXXXXXX）
  • 账户激活：仅在准备好处理付款时激活账户
  • 监控账户状态：定期检查账户状态并适当处理非活跃账户

​
安全

  • 客户验证：在创建虚拟账户之前验证客户信息
  • 账户验证：在处理付款之前验证账户详情
  • 访问控制：对虚拟账户管理实施适当的访问控制

​
支持与资源

​
获取帮助

虚拟账户提供了一种强大的方式来连接传统银行业务和区块链支付。首先为您的主钱包创建账户，然后根据使用场景需要扩展到子地址。始终确保您的钱包支持稳定币以使用 AUTO_FUNDING 类型账户。


祝您开发愉快！