> ## Documentation Index > Fetch the complete documentation index at: https://docs.blockradar.co/llms.txt > Use this file to discover all available pages before exploring further. # 虚拟账户 > 创建和管理与主钱包或子地址关联的虚拟银行账户，实现无缝的法币转稳定币支付 概述
虚拟账户允许您的客户通过传统银行转账接收法币付款，这些付款会自动转换为区块链上的稳定币。您可以为每个钱包或地址创建多个虚拟账户，支持标签、分页和账户重新生成功能。 虚拟账户 ## 前提条件 在使用虚拟账户 API 之前，请确保您已完成以下步骤： 从 [Blockradar 控制面板](https://dashboard.blockradar.co) 获取您的 API 密钥。导航至 **Developers** 生成密钥。 通过 [创建钱包 API](/zh/api-reference/wallets/create-wallet) 或控制面板创建钱包。您需要 `walletId` 来进行虚拟账户操作。 完成[尽职调查表格](https://airtable.com/appsn5KFgmZhzQ9lh/pag8ytSkiF9k5w590/form)（请参阅下方[合规要求](#合规要求)部分）。 合规批准后，请联系 [support@blockradar.co](mailto:support@blockradar.co) 或使用控制面板上的在线聊天来启用虚拟账户功能。 虚拟账户仅在 **MAINNET** 上可用。测试网环境不支持虚拟账户操作。 确保您的账户套餐包含稳定币访问权限。如需要，请从 **控制面板 → 设置 → 订阅** 进行升级。 ## 工作原理 创建与主钱包或子地址关联的虚拟账户，并包含客户信息。 客户使用传统银行转账向虚拟账户发送法币付款。 付款会自动触发等值稳定币的铸造。 铸造的稳定币会转移到关联的钱包或地址以供即时使用。 ## 自动充值流程 所有虚拟账户都使用 `AUTO_FUNDING`，自动将法币转换为稳定币。当客户向虚拟账户发送法币时： ### **1. 收款** 付款通过传统银行转账进入虚拟账户。此阶段会触发 `deposit.processing` Webhook。 ### **2. 自动铸造** 系统在区块链上自动铸造等值的稳定币。 ### **3. 区块链转账** 铸造的稳定币会转移到虚拟账户关联的钱包或地址。成功完成后会触发 `deposit.success` Webhook。 ## 合规要求 在访问虚拟账户之前，请完成合规入驻流程。 ### **所需文件** * 公司注册证书 * 董事/股东身份证件 * KYC 政策文件 ### **提交申请** 完成[尽职调查表格](https://airtable.com/appsn5KFgmZhzQ9lh/pag8ytSkiF9k5w590/form)，提供您的公司详情、合规信息和文件上传。 ## 支持的货币 * **法币**：NGN（尼日利亚奈拉）- 传统银行转账 * **稳定币**：cNGN - 在区块链上自动铸造 ## API 端点 以下是虚拟账户操作的核心 API 端点： ### **主钱包端点** * [POST /wallets/{walletId}/virtual-accounts](/zh/api-reference/virtual-accounts/master-wallet-create) – 为主钱包创建虚拟账户 * [GET /wallets/{walletId}/virtual-accounts](/zh/api-reference/virtual-accounts/master-wallet-get-all) – 列出所有虚拟账户（分页） * [GET /wallets/{walletId}/virtual-accounts/{virtualAccountId}](/zh/api-reference/virtual-accounts/master-wallet-get-one) – 检索特定虚拟账户 * [GET /wallets/{walletId}/virtual-accounts/{virtualAccountId}/transactions](/zh/api-reference/virtual-accounts/master-wallet-transactions) – 获取虚拟账户的交易记录 * [PATCH /wallets/{walletId}/virtual-accounts/{virtualAccountId}](/zh/api-reference/virtual-accounts/master-wallet-update) – 更新虚拟账户状态 * [POST /wallets/{walletId}/virtual-accounts/{virtualAccountId}/regenerate](/zh/api-reference/virtual-accounts/master-wallet-regenerate) – 重新生成虚拟账户 ### **子地址端点** * [POST /wallets/{walletId}/addresses/{addressId}/virtual-accounts](/zh/api-reference/virtual-accounts/child-address-create) – 为子地址创建虚拟账户 * [GET /wallets/{walletId}/addresses/{addressId}/virtual-accounts](/zh/api-reference/virtual-accounts/child-address-get-all) – 列出所有虚拟账户（分页） * [GET /wallets/{walletId}/addresses/{addressId}/virtual-accounts/{virtualAccountId}](/zh/api-reference/virtual-accounts/child-address-get-one) – 检索特定虚拟账户 * [GET /wallets/{walletId}/addresses/{addressId}/virtual-accounts/{virtualAccountId}/transactions](/zh/api-reference/virtual-accounts/child-address-transactions) – 获取虚拟账户的交易记录 * [PATCH /wallets/{walletId}/addresses/{addressId}/virtual-accounts/{virtualAccountId}](/zh/api-reference/virtual-accounts/child-address-update) – 更新虚拟账户状态 * [POST /wallets/{walletId}/addresses/{addressId}/virtual-accounts/{virtualAccountId}/regenerate](/zh/api-reference/virtual-accounts/child-address-regenerate) – 重新生成虚拟账户 ## 创建虚拟账户 您可以为主钱包和子地址创建虚拟账户，具体取决于您的使用场景。使用[创建虚拟账户 API](/zh/api-reference/virtual-accounts/master-wallet-create)（主钱包）或[子地址创建虚拟账户 API](/zh/api-reference/virtual-accounts/child-address-create)。 ### **请求参数** ### **主钱包请求参数** | 参数 | 类型 | 必需 | 描述 | | ------------- | ------ | -- | ---------------------------- | | `firstname` | string | 是 | 客户名字（最多29个字符） | | `lastname` | string | 是 | 客户姓氏（最多29个字符） | | `email` | string | 是 | 客户邮箱地址（每个企业必须唯一） | | `phone` | string | 否 | 客户电话号码，格式：+234XXXXXXXXXX | | `bvn` | string | 是 | 客户的 Bank Verification Number | | `dateOfBirth` | string | 是 | 客户出生日期，格式为 `yyyy-MM-dd` | ### **主钱包请求示例** ```json theme={null} { "firstname": "John", "lastname": "Doe", "email": "john.doe@example.com", "phone": "+2348161846125", "bvn": "22345678901", "dateOfBirth": "1992-08-14" } ``` ### **子地址请求参数** | 参数 | 类型 | 必需 | 描述 | | ------------- | ------ | -- | ---------------------------- | | `firstname` | string | 是 | 客户名字（最多29个字符） | | `lastname` | string | 是 | 客户姓氏（最多29个字符） | | `email` | string | 是 | 客户邮箱地址（每个企业必须唯一） | | `phone` | string | 否 | 客户电话号码，格式：+234XXXXXXXXXX | | `bvn` | string | 是 | 客户的 Bank Verification Number | | `dateOfBirth` | string | 是 | 客户出生日期，格式为 `yyyy-MM-dd` | ### **子地址请求示例** ```json theme={null} { "firstname": "John", "lastname": "Doe", "email": "john.doe@example.com", "phone": "+2348161846125", "bvn": "22345678901", "dateOfBirth": "1992-08-14" } ``` ### **响应示例** ```json theme={null} { "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": "john.doe@example.com", "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`） | ### **响应示例** ```json theme={null} { "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": "john.doe@example.com", "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（主钱包）](/zh/api-reference/virtual-accounts/master-wallet-get-one)或[获取虚拟账户 API（子地址）](/zh/api-reference/virtual-accounts/child-address-get-one)。 ### **响应示例** ```json theme={null} { "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": "john.doe@example.com", "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） | ### **响应示例** ```json theme={null} { "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 | 否 | 新虚拟账户的自定义标签 | ### **请求示例** ```json theme={null} { "firstname": "John", "lastname": "Doe", "email": "john.doe@example.com", "phone": "+2348161846125", "reason": "客户请求新账号", "label": "新主账户" } ``` 重新生成操作将停用现有虚拟账户并创建新账户。原账户的交易历史记录会保留，仍可查询。 ## 更新虚拟账户 您可以激活或停用虚拟账户以控制自动充值行为。使用[更新虚拟账户 API（主钱包）](/zh/api-reference/virtual-accounts/master-wallet-update)或[更新虚拟账户 API（子地址）](/zh/api-reference/virtual-accounts/child-address-update)。 ### **自动充值行为** * **活跃账户**：收到付款触发自动稳定币铸造 * **非活跃账户**：可以收款但自动充值被禁用 ### **更新参数** | 参数 | 类型 | 必需 | 描述 | | ---------- | ------- | -- | -------------------- | | `isActive` | boolean | 是 | `true` 激活，`false` 停用 | ### **请求示例** ```json theme={null} { "isActive": false } ``` ### **响应示例** ```json theme={null} { "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 事件** 当客户向虚拟账户发送法币付款时： 1. **`deposit.processing`** - 当虚拟账户收到法币付款时立即触发。这表示付款已被检测到，铸造过程即将开始。 2. **`deposit.success`** - 当稳定币成功铸造并转移到关联的钱包或地址时触发。这确认整个自动充值流程已完成。 3. **`deposit.failed`** - 如果铸造或转账过程在任何环节失败时触发。 4. **`deposit.cancelled`** - 如果交易在完成前被取消时触发。 ### **Webhook 载荷示例** ```json theme={null} { "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 文档](/zh/essentials/webhooks)。 ## 使用场景 ### **电子商务支付** 为客户创建虚拟账户以接收产品或服务付款。自动转换为稳定币使其能够与您基于区块链的支付系统无缝集成。 ### **订阅服务** 将虚拟账户链接到客户订阅，允许通过传统银行转账进行定期付款，这些付款会自动转换为稳定币。 ### **市场交易** 启用点对点交易，客户可以发送法币付款，这些付款会立即转换为稳定币并记入其钱包。 ### **汇款服务** 为客户提供虚拟账户以接收 NGN 汇款，这些汇款会自动转换为稳定币以便于跨境转账。 ## 后续步骤 一旦 cNGN 在您的钱包中： * **[Swap](/zh/essentials/swap)** - 按需将 cNGN 转换为 USDT、USDC 或其他稳定币 * **[Auto-Settlement](/zh/essentials/auto-settlements)** - 每次存款时自动将 cNGN 转换为 USDT/USDC ## 最佳实践 ### **账户管理** * **使用描述性标签**：为虚拟账户添加有意义的标签（例如："储蓄"、"付款"）以便于识别 * **唯一邮箱地址**：确保每个客户的每个活跃账户有唯一的邮箱地址 * **电话号码格式**：始终使用正确的尼日利亚电话号码格式（+234XXXXXXXXXX） * **账户激活**：仅在准备好处理付款时激活账户 * **监控账户状态**：定期检查账户状态并适当处理非活跃账户 * **记录重新生成原因**：重新生成账户时始终提供清晰的原因以便审计 ### **多账户管理** * **规划账户结构**：提前决定每个客户可能需要多少个账户 * **统一使用标签**：在您的应用程序中建立标签命名约定 * **跟踪账户历史**：重新生成时，保留对先前账户 ID 的引用以进行交易对账 ### **安全** * **客户验证**：在创建虚拟账户之前验证客户信息 * **账户验证**：在处理付款之前验证账户详情 * **访问控制**：对虚拟账户管理实施适当的访问控制 ## 错误处理 API 返回标准 HTTP 状态码和错误响应。常见错误包括： | 状态码 | 错误 | 描述 | | ----- | -------------------- | ---------------------------- | | `400` | Bad Request | 无效的请求参数（例如：邮箱格式无效、名字超过29个字符） | | `401` | Unauthorized | API 密钥缺失或无效 | | `404` | Not Found | 虚拟账户或钱包未找到 | | `409` | Conflict | 该邮箱已存在活跃的虚拟账户 | | `422` | Unprocessable Entity | 验证失败（例如：缺少必填字段） | ### **错误响应示例** ```json theme={null} { "message": "A virtual account with this email already exists", "statusCode": 409, "error": "Conflict" } ``` 当您收到 `409` 邮箱重复错误时，请先停用现有虚拟账户或使用重新生成端点为同一客户创建新账户。 ## 支持 * **邮箱**：[support@blockradar.co](mailto:support@blockradar.co) * **在线聊天**：控制面板上可用 * **API 参考**：[虚拟账户 API](/zh/api-reference/virtual-accounts/master-wallet-get-all) 需要更多稳定币或货币支持？请联系 [support@blockradar.co](mailto:support@blockradar.co)。