虚拟账户 - Blockradar

概述
虚拟账户允许您的客户通过传统银行转账接收法币付款，这些付款会自动转换为区块链上的稳定币。您可以为每个钱包或地址创建多个虚拟账户，支持标签、分页和账户重新生成功能。

前提条件

在使用虚拟账户 API 之前，请确保您已完成以下步骤：

API 密钥

从 Blockradar 控制面板获取您的 API 密钥。导航至 Developers 生成密钥。

创建钱包

通过创建钱包 API 或控制面板创建钱包。您需要 walletId 来进行虚拟账户操作。

完成合规要求

完成尽职调查表格（请参阅下方合规要求部分）。

功能启用

合规批准后，请联系 [email protected] 或使用控制面板上的在线聊天来启用虚拟账户功能。

主网环境

虚拟账户仅在 MAINNET 上可用。测试网环境不支持虚拟账户操作。

稳定币访问权限

确保您的账户套餐包含稳定币访问权限。如需要，请从 控制面板 → 设置 → 订阅 进行升级。

工作原理

账户创建

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

收款

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

自动充值

付款会自动触发等值稳定币的铸造。

资金管理

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

自动充值流程

所有虚拟账户都使用 AUTO_FUNDING，自动将法币转换为稳定币。当客户向虚拟账户发送法币时：

1. 收款

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

2. 自动铸造

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

3. 区块链转账

铸造的稳定币会转移到虚拟账户关联的钱包或地址。成功完成后会触发 deposit.success Webhook。

合规要求

在访问虚拟账户之前，请完成合规入驻流程。

所需文件

公司注册证书
董事/股东身份证件
KYC 政策文件

提交申请

完成尽职调查表格，提供您的公司详情、合规信息和文件上传。

支持的货币

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

API 端点

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

主钱包端点

POST /wallets//virtual-accounts – 为主钱包创建虚拟账户
GET /wallets//virtual-accounts – 列出所有虚拟账户（分页）
GET /wallets//virtual-accounts/ – 检索特定虚拟账户
GET /wallets//virtual-accounts//transactions – 获取虚拟账户的交易记录
PATCH /wallets//virtual-accounts/ – 更新虚拟账户状态
POST /wallets//virtual-accounts//regenerate – 重新生成虚拟账户

子地址端点

POST /wallets//addresses//virtual-accounts – 为子地址创建虚拟账户
GET /wallets//addresses//virtual-accounts – 列出所有虚拟账户（分页）
GET /wallets//addresses//virtual-accounts/ – 检索特定虚拟账户
GET /wallets//addresses//virtual-accounts//transactions – 获取虚拟账户的交易记录
PATCH /wallets//addresses//virtual-accounts/ – 更新虚拟账户状态
POST /wallets//addresses//virtual-accounts//regenerate – 重新生成虚拟账户

创建虚拟账户

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

请求参数

参数	类型	必需	描述
`firstname`	string	是	客户名字（最多29个字符）
`lastname`	string	是	客户姓氏（最多29个字符）
`email`	string	是	客户邮箱地址（每个企业必须唯一）
`phone`	string	否	客户电话号码，格式：+234XXXXXXXXXX
`label`	string	否	自定义标签以识别此虚拟账户（最多100个字符）

请求示例

{
  "firstname": "John",
  "lastname": "Doe",
  "email": "[email protected]",
  "phone": "+2348161846125",
  "label": "主账户"
}

响应示例

{
  "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",
    "label": "主账户",
    "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
}

多个虚拟账户

您可以为每个钱包或子地址创建多个虚拟账户。这在以下情况下很有用：

客户需要用于不同目的的独立账户（例如：储蓄、付款）
您希望分别跟踪来自不同来源的付款
客户现有的虚拟账户需要更换但保留历史记录

每个客户邮箱同时只能有一个活跃的虚拟账户。为同一邮箱创建新的虚拟账户需要先停用现有账户，或使用重新生成端点。

列出虚拟账户

列表端点返回所有虚拟账户的分页列表。使用查询参数来筛选和分页结果。

查询参数

参数	类型	描述
`page`	number	页码（默认：1）
`limit`	number	每页结果数（默认：10）
`isActive`	boolean	按活跃状态筛选（`true` 或 `false`）

响应示例

{
  "message": "Virtual accounts retrieved successfully",
  "statusCode": 200,
  "data": [
    {
      "id": "597ef702-f096-4f8a-a542-29e8757ba208",
      "reference": "172",
      "accountNumber": "9012271961",
      "accountName": "John Doe",
      "bankName": "Polaris Bank",
      "bankCode": "076",
      "currency": "NGN",
      "isActive": true,
      "status": "ACTIVE",
      "type": "AUTO_FUNDING",
      "label": null,
      "createdAt": "2025-01-21T22:15:55.746Z",
      "updatedAt": "2025-01-21T22:15:55.746Z",
      "customer": {
        "id": "3082e278-557a-44f0-9205-c2639560cd5a",
        "name": "John Doe",
        "email": "[email protected]",
        "phone": "+2346112768485",
        "status": "ACTIVE",
        "network": "mainnet"
      },
      "wallet": {
        "id": "35e964a6-436a-424f-bf3a-618cc060feea",
        "name": "Base Wallet",
        "address": "0xD8582C57E56Ef45f9fe82870aDF63d9baB89e1F7"
      },
      "address": null
    }
  ],
  "meta": {
    "totalItems": 4,
    "itemCount": 4,
    "itemsPerPage": 10,
    "totalPages": 1,
    "currentPage": 1
  }
}

检索单个虚拟账户

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

响应示例

{
  "message": "Virtual account retrieved successfully",
  "statusCode": 200,
  "data": {
    "id": "597ef702-f096-4f8a-a542-29e8757ba208",
    "reference": "172",
    "accountNumber": "9012271961",
    "accountName": "John Doe",
    "bankName": "Polaris Bank",
    "bankCode": "076",
    "currency": "NGN",
    "isActive": true,
    "status": "ACTIVE",
    "type": "AUTO_FUNDING",
    "label": "主账户",
    "createdAt": "2025-01-21T22:15:55.746Z",
    "updatedAt": "2025-01-21T22:15:55.746Z",
    "customer": {
      "id": "3082e278-557a-44f0-9205-c2639560cd5a",
      "name": "John Doe",
      "email": "[email protected]",
      "phone": "+2348161846125",
      "status": "ACTIVE",
      "network": "mainnet"
    },
    "wallet": {
      "id": "35e964a6-436a-424f-bf3a-618cc060feea",
      "name": "Base Wallet",
      "address": "0xD8582C57E56Ef45f9fe82870aDF63d9baB89e1F7"
    },
    "address": null
  }
}

虚拟账户交易

您可以使用交易端点检索与特定虚拟账户关联的所有交易。

查询参数

参数	类型	描述
`page`	number	页码（默认：1）
`limit`	number	每页结果数（默认：10）

响应示例

{
  "message": "Virtual account transactions retrieved successfully",
  "statusCode": 200,
  "data": [
    {
      "id": "ad3ce9a3-3e1c-43dc-bb7f-2c570fc7bfdc",
      "reference": "auto-funding-09026725110701402449700167083590131815",
      "senderAddress": "0xD2b6be31932E0294F2ebD14a008C3f1E05B47BC4",
      "recipientAddress": "0xbaD4E4B5e6660AcD138F776a992b566e8Bf3bb15",
      "amount": "50.0",
      "amountPaid": "50.0",
      "amountUSD": "0.03382",
      "currency": "NGN",
      "status": "SUCCESS",
      "type": "DEPOSIT",
      "note": "Auto funding of 50.0 cNGN to 0xbaD4E4B5e6660AcD138F776a992b566e8Bf3bb15",
      "network": "mainnet",
      "metadata": {
        "autoFunding": {
          "narration": "NIBSS:9018927611:SULEIMAN, ABDULFATAI:Sending:090267251107014024497001670835",
          "sessionId": "09026725110701402449700167083590131815",
          "senderBankName": "KUDA MFB",
          "senderAccountName": "SULEIMAN, ABDULFATAI"
        }
      },
      "createdAt": "2025-01-22T22:29:28.679Z",
      "asset": {
        "name": "cNGN",
        "symbol": "cNGN",
        "currency": "NGN"
      },
      "blockchain": {
        "name": "base",
        "slug": "base"
      }
    }
  ],
  "meta": {
    "totalItems": 1,
    "itemCount": 1,
    "itemsPerPage": 10,
    "totalPages": 1,
    "currentPage": 1
  }
}

metadata.autoFunding 字段包含有关法币付款来源的详细信息，包括发送方银行名称、账户名称和银行转账的交易备注。

重新生成虚拟账户

重新生成端点允许您为客户创建新的虚拟账户，同时停用现有账户。这在以下情况下很有用：

客户的银行账户详情需要更改
虚拟账户已被泄露
您需要将客户迁移到其他银行

重新生成参数

参数	类型	必需	描述
`firstname`	string	是	客户名字（最多29个字符）
`lastname`	string	是	客户姓氏（最多29个字符）
`email`	string	是	客户邮箱地址
`phone`	string	否	客户电话号码，格式：+234XXXXXXXXXX
`reason`	string	是	重新生成虚拟账户的原因
`label`	string	否	新虚拟账户的自定义标签

请求示例

{
  "firstname": "John",
  "lastname": "Doe",
  "email": "[email protected]",
  "phone": "+2348161846125",
  "reason": "客户请求新账号",
  "label": "新主账户"
}

重新生成操作将停用现有虚拟账户并创建新账户。原账户的交易历史记录会保留，仍可查询。

更新虚拟账户

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

自动充值行为

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

更新参数

参数	类型	必需	描述
`isActive`	boolean	是	`true` 激活，`false` 停用

请求示例

{
  "isActive": false
}

响应示例

{
  "message": "Virtual account updated successfully",
  "statusCode": 200,
  "data": {
    "id": "597ef702-f096-4f8a-a542-29e8757ba208",
    "accountNumber": "9012271961",
    "accountName": "John Doe",
    "bankName": "Polaris Bank",
    "isActive": false,
    "status": "INACTIVE",
    "type": "AUTO_FUNDING",
    "label": "主账户"
  }
}

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

Webhooks

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

Webhook 事件

当客户向虚拟账户发送法币付款时：

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

Webhook 载荷示例

{
  "event": "deposit.success",
  "data": {
    "id": "ad3ce9a3-3e1c-43dc-bb7f-2c570fc7bfdc",
    "reference": "auto-funding-09026725110701402449700167083590131815",
    "amount": "50.0",
    "currency": "NGN",
    "status": "SUCCESS",
    "type": "DEPOSIT",
    "network": "mainnet",
    "metadata": {
      "autoFunding": {
        "sessionId": "09026725110701402449700167083590131815",
        "senderBankName": "KUDA MFB",
        "senderAccountName": "SULEIMAN, ABDULFATAI"
      }
    },
    "virtualAccount": {
      "id": "597ef702-f096-4f8a-a542-29e8757ba208",
      "accountNumber": "9012271961",
      "bankName": "Polaris Bank"
    },
    "wallet": {
      "id": "35e964a6-436a-424f-bf3a-618cc060feea",
      "name": "Base Wallet"
    }
  }
}

Webhook 仅对活跃的虚拟账户（isActive: true）触发。如果账户被停用，可能仍会收到付款，但在账户重新激活之前不会发送 Webhook 事件。

有关 Webhook 设置、载荷结构和事件处理的更多信息，请参阅 Webhooks 文档。

使用场景

电子商务支付

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

订阅服务

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

市场交易

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

汇款服务

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

后续步骤

一旦 cNGN 在您的钱包中：

Swap - 按需将 cNGN 转换为 USDT、USDC 或其他稳定币
Auto-Settlement - 每次存款时自动将 cNGN 转换为 USDT/USDC

最佳实践

账户管理

使用描述性标签：为虚拟账户添加有意义的标签（例如：“储蓄”、“付款”）以便于识别
唯一邮箱地址：确保每个客户的每个活跃账户有唯一的邮箱地址
电话号码格式：始终使用正确的尼日利亚电话号码格式（+234XXXXXXXXXX）
账户激活：仅在准备好处理付款时激活账户
监控账户状态：定期检查账户状态并适当处理非活跃账户
记录重新生成原因：重新生成账户时始终提供清晰的原因以便审计

多账户管理

规划账户结构：提前决定每个客户可能需要多少个账户
统一使用标签：在您的应用程序中建立标签命名约定
跟踪账户历史：重新生成时，保留对先前账户 ID 的引用以进行交易对账

安全

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

错误处理

API 返回标准 HTTP 状态码和错误响应。常见错误包括：

状态码	错误	描述
`400`	Bad Request	无效的请求参数（例如：邮箱格式无效、名字超过29个字符）
`401`	Unauthorized	API 密钥缺失或无效
`404`	Not Found	虚拟账户或钱包未找到
`409`	Conflict	该邮箱已存在活跃的虚拟账户
`422`	Unprocessable Entity	验证失败（例如：缺少必填字段）

错误响应示例

{
  "message": "A virtual account with this email already exists",
  "statusCode": 409,
  "error": "Conflict"
}

当您收到 409 邮箱重复错误时，请先停用现有虚拟账户或使用重新生成端点为同一客户创建新账户。

支持

邮箱：[email protected]
在线聊天：控制面板上可用
API 参考：虚拟账户 API

需要更多稳定币或货币支持？请联系 [email protected]。

开始使用

核心功能

​前提条件

​工作原理

账户创建

收款

自动充值

资金管理

​自动充值流程

​1. 收款

​2. 自动铸造

​3. 区块链转账

​合规要求

​所需文件

​提交申请

​支持的货币

​API 端点

​主钱包端点

​子地址端点

​创建虚拟账户

​请求参数

​请求示例

​响应示例

​多个虚拟账户

​列出虚拟账户

​查询参数

​响应示例

​检索单个虚拟账户

​响应示例

​虚拟账户交易

​查询参数

​响应示例

​重新生成虚拟账户

​重新生成参数

​请求示例

​更新虚拟账户

​自动充值行为

​更新参数

​请求示例

​响应示例

​Webhooks

​Webhook 事件

​Webhook 载荷示例

​使用场景

​电子商务支付

​订阅服务

​市场交易

​汇款服务

​后续步骤

​最佳实践

​账户管理

​多账户管理

​安全

​错误处理

​错误响应示例

​支持

前提条件

工作原理

自动充值流程

1. 收款

2. 自动铸造

3. 区块链转账

合规要求

所需文件

提交申请

支持的货币

API 端点

主钱包端点

子地址端点

创建虚拟账户

请求参数

请求示例

响应示例

多个虚拟账户

列出虚拟账户

查询参数

响应示例

检索单个虚拟账户

响应示例

虚拟账户交易

查询参数

响应示例

重新生成虚拟账户

重新生成参数

请求示例

更新虚拟账户

自动充值行为

更新参数

请求示例

响应示例

Webhooks

Webhook 事件

Webhook 载荷示例

使用场景

电子商务支付

订阅服务

市场交易

汇款服务

后续步骤

最佳实践

账户管理

多账户管理

安全

错误处理

错误响应示例

支持