> ## 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 Dashboard](https://dashboard.blockradar.co) 获取您的 API 密钥。前往 **Developers** 生成密钥。
通过 [创建钱包 API](/en/api-reference/wallets/create-wallet) 或 dashboard 创建钱包。您将需要 `walletId` 用于虚拟账户操作。
填写 [尽职调查表](https://airtable.com/appsn5KFgmZhzQ9lh/pag8ytSkiF9k5w590/form)（请参阅下文的 [合规要求](#compliance-requirements)）。
合规审批通过后，请申请启用虚拟账户功能。请联系 [support@blockradar.co](mailto:support@blockradar.co) 或使用 dashboard 上的实时聊天。
虚拟账户仅在 **MAINNET** 上可用。测试网环境不支持虚拟账户操作。
存入法币并将其转换为稳定币是付费功能。请确保您的账户套餐包含稳定币访问权限。请从 **Dashboard → 设置 → 订阅** 升级。
## 工作原理
使用客户信息创建与主钱包或子地址关联的虚拟账户。
客户通过传统银行转账向虚拟账户发送法币付款。
付款会自动触发等额稳定币的铸造。
铸造的稳定币会被转入关联的钱包或地址，可立即使用。
## 自动注资流程
所有虚拟账户都使用 `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](/en/api-reference/virtual-accounts/master-wallet-create) – 为主钱包创建虚拟账户
* [GET /wallets/{walletId}/virtual-accounts](/en/api-reference/virtual-accounts/master-wallet-get-all) – 列出所有虚拟账户（分页）
* [GET /wallets/{walletId}/virtual-accounts/{virtualAccountId}](/en/api-reference/virtual-accounts/master-wallet-get-one) – 获取特定虚拟账户
* [GET /wallets/{walletId}/virtual-accounts/{virtualAccountId}/transactions](/en/api-reference/virtual-accounts/master-wallet-transactions) – 获取虚拟账户的交易记录
* [PATCH /wallets/{walletId}/virtual-accounts/{virtualAccountId}](/en/api-reference/virtual-accounts/master-wallet-update) – 更新虚拟账户状态
* [POST /wallets/{walletId}/virtual-accounts/{virtualAccountId}/regenerate](/en/api-reference/virtual-accounts/master-wallet-regenerate) – 重新生成虚拟账户
### **子地址端点**
* [POST /wallets/{walletId}/addresses/{addressId}/virtual-accounts](/en/api-reference/virtual-accounts/child-address-create) – 为子地址创建虚拟账户
* [GET /wallets/{walletId}/addresses/{addressId}/virtual-accounts](/en/api-reference/virtual-accounts/child-address-get-all) – 列出所有虚拟账户（分页）
* [GET /wallets/{walletId}/addresses/{addressId}/virtual-accounts/{virtualAccountId}](/en/api-reference/virtual-accounts/child-address-get-one) – 获取特定虚拟账户
* [GET /wallets/{walletId}/addresses/{addressId}/virtual-accounts/{virtualAccountId}/transactions](/en/api-reference/virtual-accounts/child-address-transactions) – 获取虚拟账户的交易记录
* [PATCH /wallets/{walletId}/addresses/{addressId}/virtual-accounts/{virtualAccountId}](/en/api-reference/virtual-accounts/child-address-update) – 更新虚拟账户状态
* [POST /wallets/{walletId}/addresses/{addressId}/virtual-accounts/{virtualAccountId}/regenerate](/en/api-reference/virtual-accounts/child-address-regenerate) – 重新生成虚拟账户
## 创建虚拟账户
您可以根据您的用例为主钱包和子地址创建虚拟账户。请使用 [创建虚拟账户 API](/en/api-reference/virtual-accounts/master-wallet-create) 用于主钱包，或使用 [子地址创建虚拟账户 API](/en/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",
"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](/en/api-reference/virtual-accounts/master-wallet-get-one) 或 [子地址获取虚拟账户 API](/en/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",
"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 | 是 | 重新生成虚拟账户的原因 |
### **请求示例**
```json theme={null}
{
"firstname": "John",
"lastname": "Doe",
"email": "john.doe@example.com",
"phone": "+2348161846125",
"reason": "Customer requested new account number"
}
```
重新生成操作将停用现有的虚拟账户并创建新账户。原始账户的交易历史记录将被保留并仍可查询。
## 更新虚拟账户
您可以激活或停用虚拟账户以控制自动注资行为。请使用 [主钱包更新虚拟账户 API](/en/api-reference/virtual-accounts/master-wallet-update) 或 [子地址更新虚拟账户 API](/en/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"
}
}
```
当虚拟账户被停用时（`isActive: false`），仍可接收付款，但自动稳定币铸造和转账过程将被禁用。您可以随时重新激活账户以再次启用自动注资。
## Webhooks
虚拟账户在收到并处理付款时会触发 webhook 事件。对于 `AUTO_FUNDING` 类型的账户，您将在付款处理流程的每个阶段收到 webhook 通知。
### **Webhook 事件**
当客户向虚拟账户发送法币付款时：
1. **`deposit.processing`** - 当虚拟账户收到法币付款时立即触发。这表示已检测到付款，铸造过程即将开始。
2. **`deposit.success`** - 当稳定币已成功铸造并转入关联钱包或地址时触发。这确认整个自动注资流程已完成。
3. **`deposit.failed`** - 如果铸造或转账过程在任何环节失败时触发。
4. **`deposit.cancelled`** - 如果交易在完成前被取消时触发。
### **Webhook payload 示例**
```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"
}
}
}
```
Webhooks 仅针对激活的虚拟账户（`isActive: true`）触发。如果账户已停用，付款仍可接收，但在账户重新激活之前不会发送 webhook 事件。
有关 webhook 设置、payload 结构和事件处理的更多信息，请参阅 [Webhooks 文档](/en/essentials/webhooks)。
## 用例
### **电子商务支付**
为客户创建虚拟账户以接收产品或服务付款。自动转换为稳定币可与基于区块链的支付系统无缝集成。
### **订阅服务**
将虚拟账户与客户订阅关联，允许通过传统银行转账进行的定期付款自动转换为稳定币。
### **市场交易**
启用点对点交易，让客户可以发送法币付款，这些付款会即时转换为稳定币并存入其钱包。
### **汇款服务**
为客户提供虚拟账户以接收 NGN 汇款，这些汇款会自动转换为稳定币以便于跨境转账。
## 下一步
cNGN 进入您的钱包后：
* **[Swap](/en/essentials/swap)** - 按需将 cNGN 转换为 USDT、USDC 或其他稳定币
* **[Auto-Settlement](/en/essentials/auto-settlements)** - 在每次存款时自动将 cNGN 转换为 USDT/USDC
## 最佳实践
### **账户管理**
* **在两个路由上使用相同的创建 payload**：主钱包和子地址虚拟账户的创建都使用客户详细信息（`firstname`、`lastname`、`email`、`phone`、`bvn`、`dateOfBirth`）
* **电话号码格式**：在创建虚拟账户时，请始终对尼日利亚电话号码使用正确的格式（`+234XXXXXXXXXX`）
* **账户激活**：仅在准备好处理付款时才激活账户
* **监控账户状态**：定期检查账户状态并妥善处理未激活的账户
* **记录重新生成原因**：始终在重新生成账户时提供明确的原因，以便审计
### **多个账户**
* **规划账户结构**：提前决定每个客户可能需要多少个账户
* **跟踪账户历史记录**：在重新生成时，请保留对先前账户 ID 的引用，以便进行交易对账
### **安全**
* **客户验证**：在创建虚拟账户之前验证客户信息
* **账户验证**：在处理付款之前验证账户详细信息
* **访问控制**：为虚拟账户管理实施适当的访问控制
## 错误处理
API 返回标准的 HTTP 状态码和错误响应。常见错误包括：
| 状态码 | 错误 | 说明 |
| ----- | -------------------- | ----------------------------- |
| `400` | Bad Request | 无效的请求参数（例如，无效的电话格式或格式错误的账户详情） |
| `401` | Unauthorized | 缺少或无效的 API 密钥 |
| `404` | Not Found | 找不到虚拟账户或钱包 |
| `422` | Unprocessable Entity | 验证失败（例如，缺少必填字段） |
### **错误响应示例**
```json theme={null}
{
"message": "Validation failed",
"statusCode": 422,
"error": "Unprocessable Entity"
}
```
## 支持
* **电子邮件**：[support@blockradar.co](mailto:support@blockradar.co)
* **实时聊天**：在 dashboard 上提供
* **API 参考**：[虚拟账户 API](/en/api-reference/virtual-accounts/master-wallet-get-all)
需要其他稳定币或货币的支持？请联系 [support@blockradar.co](mailto:support@blockradar.co)。