存入法币 - Blockradar

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

前提条件

在使用虚拟账户 API 之前，请确保您具备：

API 密钥

从 Blockradar Dashboard 获取您的 API 密钥。前往 Developers 生成密钥。

已创建钱包

通过创建钱包 API 或 dashboard 创建钱包。您将需要 walletId 用于虚拟账户操作。

合规审批通过

填写尽职调查表（请参阅下文的合规要求）。

功能已启用

合规审批通过后，请申请启用虚拟账户功能。请联系 [email protected] 或使用 dashboard 上的实时聊天。

主网环境

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

稳定币支持

存入法币并将其转换为稳定币是付费功能。请确保您的账户套餐包含稳定币访问权限。请从 Dashboard → 设置 → 订阅 升级。

工作原理

账户创建

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

付款接收

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

自动注资

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

资金管理

铸造的稳定币会被转入关联的钱包或地址，可立即使用。

自动注资流程

所有虚拟账户都使用 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
`bvn`	string	是	客户的 Bank Verification Number
`dateOfBirth`	string	是	客户的出生日期，格式为 `yyyy-MM-dd`

主钱包请求示例

{
  "firstname": "John",
  "lastname": "Doe",
  "email": "[email protected]",
  "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`

子地址请求示例

{
  "firstname": "John",
  "lastname": "Doe",
  "email": "[email protected]",
  "phone": "+2348161846125",
  "bvn": "22345678901",
  "dateOfBirth": "1992-08-14"
}

响应示例

{
  "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
}

多个虚拟账户

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

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

列出虚拟账户

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

查询参数

参数	类型	说明
`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",
      "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",
    "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	是	重新生成虚拟账户的原因

请求示例

{
  "firstname": "John",
  "lastname": "Doe",
  "email": "[email protected]",
  "phone": "+2348161846125",
  "reason": "Customer requested new account number"
}

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

更新虚拟账户

您可以激活或停用虚拟账户以控制自动注资行为。请使用主钱包更新虚拟账户 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"
  }
}

当虚拟账户被停用时（isActive: false），仍可接收付款，但自动稳定币铸造和转账过程将被禁用。您可以随时重新激活账户以再次启用自动注资。

Webhooks

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

Webhook 事件

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

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

Webhook payload 示例

{
  "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 文档。

用例

电子商务支付

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

订阅服务

将虚拟账户与客户订阅关联，允许通过传统银行转账进行的定期付款自动转换为稳定币。

市场交易

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

汇款服务

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

下一步

cNGN 进入您的钱包后：

Swap - 按需将 cNGN 转换为 USDT、USDC 或其他稳定币
Auto-Settlement - 在每次存款时自动将 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	验证失败（例如，缺少必填字段）

错误响应示例

{
  "message": "Validation failed",
  "statusCode": 422,
  "error": "Unprocessable Entity"
}

支持

电子邮件：[email protected]
实时聊天：在 dashboard 上提供
API 参考：虚拟账户 API

需要其他稳定币或货币的支持？请联系 [email protected]。

开始使用

钱包

收款

付款

转换与管理

合规与工具

Documentation Index

​前提条件

​工作原理

账户创建

付款接收

自动注资

资金管理

​自动注资流程

​1. 付款接收

​2. 自动铸造

​3. 区块链转账

​合规要求

​所需文件

​提交申请

​支持的货币

​API 端点

​主钱包端点

​子地址端点

​创建虚拟账户

​主钱包请求参数

​主钱包请求示例

​子地址请求参数

​子地址请求示例

​响应示例

​多个虚拟账户

​列出虚拟账户

​查询参数

​响应示例

​获取单个虚拟账户

​响应示例

​虚拟账户交易

​查询参数

​响应示例

​重新生成虚拟账户

​重新生成参数

​请求示例

​更新虚拟账户

​自动注资行为

​更新参数

​请求示例

​响应示例

​Webhooks

​Webhook 事件

​Webhook payload 示例

​用例

​电子商务支付

​订阅服务

​市场交易

​汇款服务

​下一步

​最佳实践

​账户管理

​多个账户

​安全

​错误处理

​错误响应示例

​支持

前提条件

工作原理

自动注资流程

1. 付款接收

2. 自动铸造

3. 区块链转账

合规要求

所需文件

提交申请

支持的货币

API 端点

主钱包端点

子地址端点

创建虚拟账户

主钱包请求参数

主钱包请求示例

子地址请求参数

子地址请求示例

响应示例

多个虚拟账户

列出虚拟账户

查询参数

响应示例

获取单个虚拟账户

响应示例

虚拟账户交易

查询参数

响应示例

重新生成虚拟账户

重新生成参数

请求示例

更新虚拟账户

自动注资行为

更新参数

请求示例

响应示例

Webhooks

Webhook 事件

Webhook payload 示例

用例

电子商务支付

订阅服务

市场交易

汇款服务

下一步

最佳实践

账户管理

多个账户

安全

错误处理

错误响应示例

支持