存入法币 - Blockradar

v2 · 推荐
v1 · Legacy

简而言之
虚拟账户让您的客户通过传统银行转账接收法币，这些法币会自动转换为区块链上的稳定币。v2 流程会发现您的钱包可用的资产和货币，返回一个描述每个通道所需内容的 schema，并跨多种货币和稳定币创建与 master wallet 或 child address 关联的虚拟账户。

v2 要求会返回一个 JSON Schema，描述某个通道所需的信息。当 additionalDataRequired 为 true 时，请使用动态表单指南来收集、验证并将这些字段作为 additionalData 提交。v1 流程可在 v1 · Legacy 标签页中查看，但不再推荐使用。

前提条件

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

API 密钥

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

已创建钱包

通过创建 Master Wallet 指南或控制台创建钱包。您将需要 walletId 用于虚拟账户操作。

合规已批准

在控制台完成尽职调查流程：My Wallets → Settings → Compliance。合规要求和批准流程因地区而异，因此您只需完成您的产品所使用的本地渠道对应的项目。

功能已启用

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

主网环境

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

稳定币支持

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

工作原理

发现选项

获取您的钱包可用的资产和货币。

获取要求

检索描述所选通道所需内容的 schema。

创建账户

使用 additionalData 和可选的 label 创建虚拟账户。

自动注资

传入的法币会自动向关联的钱包或地址铸造等额的稳定币。

受支持的法币

货币因通道和提供商而异。请始终通过发现端点获取您的钱包可用的内容，而不要将列表硬编码。下表显示了每种受支持货币所覆盖的稳定币和区块链：

Fiat Currency	USDC Blockchains	USDT Blockchains	EURC Blockchains
COP	Ethereum, Polygon	Ethereum	—
GHS	Ethereum, Base, Polygon	Ethereum, Base, Polygon	Base
INR	Ethereum, Base, Polygon	Ethereum, Base, Polygon	Base
KES	Ethereum, Base, Polygon	Ethereum, Base, Polygon	Base
NGN	Ethereum, Base, Polygon	Ethereum, Base, Polygon	Base
TZS	Ethereum, Base, Polygon	Ethereum, Base, Polygon	Base
UGX	Ethereum, Base, Polygon	Ethereum, Base, Polygon	Base

自动注资流程

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

1. 付款接收

通过银行转账在虚拟账户中接收付款。此阶段会触发 deposit.processing webhook。

2. 自动铸造

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

3. 区块链转账

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

受支持的资产和货币

v2 支持多种稳定币和货币。请不要假设固定的配对，而是通过发现端点获取您的钱包可用的内容。例如，NGN 银行转账可以自动注资 cNGN，而其他通道则结算为 USDC 或其他受支持的资产。

API 端点

Master Wallet 端点

Operation	Endpoint
Discover options	`GET /v2/wallets/{id}/virtual-accounts/discovery`
Get requirements	`GET /v2/wallets/{id}/virtual-accounts/requirements`
Create	`POST /v2/wallets/{id}/virtual-accounts`
List	`GET /v2/wallets/{id}/virtual-accounts`
Get one	`GET /v2/wallets/{id}/virtual-accounts/{virtualAccountId}`
Update status	`PATCH /v2/wallets/{id}/virtual-accounts/{virtualAccountId}`
Regenerate	`POST /v2/wallets/{id}/virtual-accounts/{virtualAccountId}/regenerate`

Child Address 端点

Operation	Endpoint
Create	`POST /v2/wallets/{walletId}/addresses/{addressId}/virtual-accounts`
List	`GET /v2/wallets/{walletId}/addresses/{addressId}/virtual-accounts`
Get one	`GET /v2/wallets/{walletId}/addresses/{addressId}/virtual-accounts/{virtualAccountId}`
Transactions	`GET /v2/wallets/{walletId}/addresses/{addressId}/virtual-accounts/{virtualAccountId}/transactions`
Update status	`PATCH /v2/wallets/{walletId}/addresses/{addressId}/virtual-accounts/{virtualAccountId}`
Regenerate	`POST /v2/wallets/{walletId}/addresses/{addressId}/virtual-accounts/{virtualAccountId}/regenerate`

步骤 1：发现选项

获取您的钱包可用于虚拟账户的资产和货币。

curl --request GET \
  --url 'https://api.blockradar.co/v2/wallets/{walletId}/virtual-accounts/discovery' \
  --header 'x-api-key: <api-key>'

Discovery Response

{
  "statusCode": 200,
  "message": "Successful",
  "data": {
    "assets": [
      {
        "asset": {
          "id": "ae455f23-3824-4125-baab-d158315cbcbd",
          "name": "USD Coin",
          "symbol": "USDC",
          "logoUrl": "https://cdn.example.com/assets/usdc.svg",
          "blockchain": {
            "id": "7773c3f9-f35d-4a36-9d85-5f4c537cd097",
            "name": "Ethereum",
            "symbol": "ETH",
            "slug": "ethereum",
            "tokenStandard": "ERC20",
            "logoUrl": "https://cdn.example.com/blockchains/ethereum.svg"
          }
        },
        "currencies": ["NGN"]
      }
    ],
    "currencies": {
      "NGN": {
        "code": "NGN",
        "currency": "NGN",
        "shortName": "Naira",
        "name": "Nigerian Naira",
        "symbol": "₦"
      }
    }
  }
}

步骤 2：获取要求

获取描述所选货币（以及可选的资产）所需内容的 schema。使用动态表单来解释并完成它。

Parameter	In	Required	Description
`currency`	query	Yes	ISO 4217 货币代码
`assetId`	query	No	接收结算的稳定币资产
`customerId`	query	No	现有客户标识符，当提供商需要时
`provider`	query	No	提供商 slug。省略以让 Blockradar 自动路由

curl --request GET \
  --url 'https://api.blockradar.co/v2/wallets/{walletId}/virtual-accounts/requirements?currency=NGN&assetId=ae455f23-3824-4125-baab-d158315cbcbd' \
  --header 'x-api-key: <api-key>'

Requirements Response

{
  "statusCode": 200,
  "message": "Successful",
  "data": {
    "supported": true,
    "unlocked": true,
    "additionalDataRequired": true,
    "additionalDataSchema": {
      "$schema": "http://json-schema.org/draft-07/schema#",
      "type": "object",
      "title": "Bank account details",
      "properties": {
        "bvn": { "type": "string", "title": "BVN", "minLength": 11, "maxLength": 11 },
        "dateOfBirth": { "type": "string", "title": "Date of birth", "format": "date" }
      },
      "required": ["bvn", "dateOfBirth"],
      "additionalProperties": false
    },
    "provider": "example-provider"
  }
}

如果 additionalDataRequired 为 false，您可以跳过收集 additionalData 并直接创建账户。创建账户时请使用此处返回的 provider。

步骤 3：创建虚拟账户

为 master wallet 或 child address 创建虚拟账户。发送根据要求 schema 构建的已验证 additionalData 对象。

Parameter	Type	Required	Description
`provider`	string	Yes	从要求流程中解析出的提供商 slug
`currency`	string	Yes	ISO 4217 虚拟账户货币
`assetId`	string	No	接收结算的稳定币资产
`customerId`	string	No	现有客户标识符，当提供商需要时
`additionalData`	object	No	根据 `additionalDataSchema` 收集并验证的值
`label`	string	No	您为虚拟账户设置的显示标签（最多 100 个字符）

curl --request POST \
  --url 'https://api.blockradar.co/v2/wallets/{walletId}/virtual-accounts' \
  --header 'Content-Type: application/json' \
  --header 'x-api-key: <api-key>' \
  --data '{
    "provider": "example-provider",
    "currency": "NGN",
    "assetId": "ae455f23-3824-4125-baab-d158315cbcbd",
    "label": "Ada collection account",
    "additionalData": {
      "bvn": "12345678901",
      "dateOfBirth": "1992-04-18"
    }
  }'

curl --request POST \
  --url 'https://api.blockradar.co/v2/wallets/{walletId}/addresses/{addressId}/virtual-accounts' \
  --header 'Content-Type: application/json' \
  --header 'x-api-key: <api-key>' \
  --data '{
    "provider": "example-provider",
    "currency": "NGN",
    "assetId": "ae455f23-3824-4125-baab-d158315cbcbd",
    "label": "Ada collection account",
    "additionalData": {
      "bvn": "12345678901",
      "dateOfBirth": "1992-04-18"
    }
  }'

响应示例

{
  "statusCode": 201,
  "message": "Virtual account created successfully",
  "data": {
    "created": true,
    "virtualAccount": {
      "id": "3e8fcd73-4067-4386-8c1e-9929e6a768d7",
      "reference": "va_01J2X8JQ4V9N0P7K2M6C3F5R8T",
      "accountNumber": "0123456789",
      "accountName": "Acme Ltd / Ada Okafor",
      "bankName": "Example Bank",
      "bankCode": "999",
      "currency": "NGN",
      "institutionAddress": null,
      "assetId": "ae455f23-3824-4125-baab-d158315cbcbd",
      "providerId": "1128dd40-2c94-4c16-a6bf-fbbc6afee52c",
      "isActive": true,
      "status": "active",
      "type": "AUTO_FUNDING",
      "label": "Ada collection account",
      "createdAt": "2026-07-19T12:30:00.000Z",
      "updatedAt": "2026-07-19T12:30:00.000Z"
    }
  }
}

列出虚拟账户

列表端点会返回虚拟账户的分页列表。使用查询参数进行搜索、按激活状态筛选，以及按日期范围筛选。

查询参数

Parameter	Type	Description
`isActive`	boolean	按激活状态筛选（`true` 或 `false`）
`search`	string	按引用、标签、账户名或账号搜索
`startDate`	string	包含性的 ISO 8601 起始日期。仅当提供 `endDate` 时必填
`endDate`	string	包含性的 ISO 8601 结束日期。仅当提供 `startDate` 时必填
`page`	integer	从 1 开始的页码（默认值：1）
`limit`	integer	每页记录数，最多 100（默认值：10）

Response Example

{
  "statusCode": 200,
  "message": "Virtual accounts retrieved successfully",
  "data": [
    {
      "id": "3e8fcd73-4067-4386-8c1e-9929e6a768d7",
      "reference": "va_01J2X8JQ4V9N0P7K2M6C3F5R8T",
      "accountNumber": "0123456789",
      "accountName": "Acme Ltd / Ada Okafor",
      "bankName": "Example Bank",
      "bankCode": "999",
      "currency": "NGN",
      "institutionAddress": null,
      "assetId": "ae455f23-3824-4125-baab-d158315cbcbd",
      "providerId": "1128dd40-2c94-4c16-a6bf-fbbc6afee52c",
      "isActive": true,
      "status": "active",
      "type": "AUTO_FUNDING",
      "label": "Ada collection account",
      "createdAt": "2026-07-19T12:30:00.000Z",
      "updatedAt": "2026-07-19T12:30:00.000Z"
    }
  ],
  "meta": {
    "total": 1,
    "page": 1,
    "limit": 10,
    "pageCount": 1,
    "hasPreviousPage": false,
    "hasNextPage": false
  }
}

获取单个虚拟账户

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

虚拟账户交易

使用子地址交易端点检索与虚拟账户关联的交易。每个自动注资事件也会通过 webhooks 送达。

查询参数

Parameter	Type	Description
`page`	integer	从 1 开始的页码（默认值：1）
`limit`	integer	每页记录数，最多 100（默认值：10）

Response Example

{
  "statusCode": 200,
  "message": "Virtual account transactions retrieved successfully",
  "data": [
    {
      "id": "ad3ce9a3-3e1c-43dc-bb7f-2c570fc7bfdc",
      "reference": "auto-funding-09026725110701402449700167083590131815",
      "senderAddress": "0xD2b6be31932E0294F2ebD14a008C3f1E05B47BC4",
      "recipientAddress": "0xbaD4E4B5e6660AcD138F776a992b566e8Bf3bb15",
      "tokenAddress": "0x46C85152bFe9f96829aA94755D9f915F9B10EF5F",
      "amount": "50.0",
      "amountPaid": "50.0",
      "amountUSD": "50.0",
      "rateUSD": "1.0",
      "currency": "NGN",
      "hash": "0xbe0c9a4dd314b6220c4eaae218003e753e948ce6183b5b92c764501e1b4e7c0a",
      "confirmed": true,
      "status": "SUCCESS",
      "processingStatus": "SUCCESS",
      "type": "DEPOSIT",
      "note": "Auto funding of 50.0 cNGN",
      "createdAt": "2026-01-22T22:29:28.679Z",
      "updatedAt": "2026-01-22T23:15:21.849Z"
    }
  ],
  "meta": {
    "total": 1,
    "page": 1,
    "limit": 10,
    "pageCount": 1,
    "hasPreviousPage": false,
    "hasNextPage": false
  }
}

更新虚拟账户

激活或停用虚拟账户以控制自动注资行为。请使用主钱包更新虚拟账户 API 或子地址更新虚拟账户 API。

自动注资行为

激活账户：收到的付款会触发自动稳定币铸造。
未激活账户：可以收到付款，但自动注资被禁用。

更新参数

Parameter	Type	Required	Description
`isActive`	boolean	Yes	`true` 表示激活，`false` 表示停用

Request Example

{
  "isActive": false
}

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

重新生成虚拟账户

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

客户的银行账户详情需要更改
虚拟账户已被泄露
您需要将客户迁移到不同的提供商

重新生成参数

Parameter	Type	Required	Description
`provider`	string	Yes	替换账户的提供商 slug
`currency`	string	Yes	ISO 4217 虚拟账户货币
`reason`	string	Yes	需要替换账户的原因
`assetId`	string	No	接收结算的稳定币资产
`customerId`	string	No	现有客户标识符
`additionalData`	object	No	根据要求 schema 验证的值
`label`	string	No	您为虚拟账户设置的显示标签

Request Example

{
  "provider": "example-provider",
  "currency": "NGN",
  "reason": "The previous account was closed by the institution.",
  "label": "Ada collection account"
}

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

Webhooks

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

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",
    "virtualAccount": {
      "id": "3e8fcd73-4067-4386-8c1e-9929e6a768d7",
      "accountNumber": "0123456789",
      "bankName": "Example Bank"
    },
    "wallet": {
      "id": "4465468a-3c36-4536-918a-91d689e18a74",
      "name": "Base Wallet"
    }
  }
}

Webhooks 仅针对激活的虚拟账户（isActive: true）触发。如果账户已停用，付款仍可接收，但在账户重新激活之前不会发送 webhook 事件。

有关 webhook 设置、payload 结构和事件处理，请参阅 Webhooks 文档。

下一步

稳定币进入您的钱包后：

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

用例

电子商务支付

为客户创建虚拟账户以接收产品或服务的付款，这些付款会自动转换为稳定币，供您基于区块链的支付系统使用。

订阅服务

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

市场交易

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

汇款服务

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

最佳实践

账户管理

使用要求 schema：仅收集当前要求 schema 中的字段。不要硬编码入驻字段——请参阅动态表单。
复用返回的提供商：使用要求请求返回的 provider 进行创建。
为账户添加标签：设置 label 使账户可搜索且易于对账。
账户激活：停用您尚未准备好注资的账户；准备就绪后再重新激活。
记录重新生成原因：为审计目的，重新生成时请始终提供明确的 reason。

安全

客户验证：在创建虚拟账户之前验证客户信息。
保留字符串：将标识符和代码作为字符串发送，以避免精度损失。
访问控制：为虚拟账户管理实施适当的访问控制。

错误处理

API 返回标准的 HTTP 状态码和错误响应。

Status Code	Error	Description
`400`	Bad Request	无效的请求参数或格式错误的 `additionalData`
`401`	Unauthorized	缺少或无效的 API 密钥
`404`	Not Found	找不到虚拟账户或钱包
`422`	Unprocessable Entity	验证失败（例如，缺少必填字段）

错误响应示例

{
  "statusCode": 400,
  "message": "Invalid additional data for bvn: bvn does not match the expected format"
}

API 参考

v2（推荐）

Endpoint	Description
Discover Options	列出可用的资产和货币
Get Requirements	获取某个通道的字段 schema
Master Wallet Create	为 master wallet 创建虚拟账户
Master Wallet List	列出 master wallet 的虚拟账户
Master Wallet Get One	检索特定的虚拟账户
Master Wallet Update	激活或停用虚拟账户
Master Wallet Regenerate	重新生成虚拟账户
Child Address Create	为 child address 创建虚拟账户
Child Address List	列出 child address 的虚拟账户
Child Address Get One	检索特定的虚拟账户
Child Address Transactions	列出虚拟账户的交易
Child Address Update	激活或停用虚拟账户
Child Address Regenerate	重新生成虚拟账户

支持

邮箱：[email protected]
实时聊天：在控制台上提供
API 参考：虚拟账户 API

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

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

前提条件

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

API 密钥

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

已创建钱包

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

合规审批通过

在控制台完成尽职调查流程：My wallets > Settings > Compliance

功能已启用

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

主网环境

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

稳定币支持

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

工作原理

账户创建

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

付款接收

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

自动注资

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

资金管理

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

自动注资流程

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

1. 付款接收

通过传统银行转账在虚拟账户中接收付款。此阶段会触发 deposit.processing webhook。

2. 自动铸造

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

3. 区块链转账

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

支持的货币

法币：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]。

​前提条件

​工作原理

发现选项

获取要求

创建账户

自动注资

​受支持的法币

​自动注资流程

​1. 付款接收

​2. 自动铸造

​3. 区块链转账

​受支持的资产和货币

​API 端点

​Master Wallet 端点

​Child Address 端点

​步骤 1：发现选项

​步骤 2：获取要求

​步骤 3：创建虚拟账户

​响应示例

​列出虚拟账户

​查询参数

​获取单个虚拟账户

​虚拟账户交易

​查询参数

​更新虚拟账户

​自动注资行为

​更新参数

​重新生成虚拟账户

​重新生成参数

​Webhooks

​Webhook 事件

​Webhook Payload 示例

​下一步

​用例

​电子商务支付

​订阅服务

​市场交易

​汇款服务

​最佳实践

​账户管理

​安全

​错误处理

​错误响应示例

​API 参考

​v2（推荐）

​支持

​前提条件

​工作原理

账户创建

付款接收

自动注资

资金管理

​自动注资流程

​1. 付款接收

​2. 自动铸造

​3. 区块链转账

​支持的货币

​API 端点

​主钱包端点

​子地址端点

​创建虚拟账户

​主钱包请求参数

​主钱包请求示例

​子地址请求参数

​子地址请求示例

​响应示例

​多个虚拟账户

​列出虚拟账户

​查询参数

​响应示例

​获取单个虚拟账户

​响应示例

​虚拟账户交易

​查询参数

​响应示例

​重新生成虚拟账户

​重新生成参数

​请求示例

​更新虚拟账户

​自动注资行为

前提条件

工作原理

受支持的法币

自动注资流程

1. 付款接收

2. 自动铸造

3. 区块链转账

受支持的资产和货币

API 端点

Master Wallet 端点

Child Address 端点

步骤 1：发现选项

步骤 2：获取要求

步骤 3：创建虚拟账户

响应示例

列出虚拟账户

查询参数

获取单个虚拟账户

虚拟账户交易

查询参数

更新虚拟账户

自动注资行为

更新参数

重新生成虚拟账户

重新生成参数

Webhooks

Webhook 事件

Webhook Payload 示例

下一步

用例

电子商务支付

订阅服务

市场交易

汇款服务

最佳实践

账户管理

安全

错误处理

错误响应示例

API 参考

v2（推荐）

支持

前提条件

工作原理

自动注资流程

1. 付款接收

2. 自动铸造

3. 区块链转账

支持的货币

API 端点

主钱包端点

子地址端点

创建虚拟账户

主钱包请求参数

主钱包请求示例

子地址请求参数

子地址请求示例

响应示例

多个虚拟账户

列出虚拟账户

查询参数

响应示例

获取单个虚拟账户

响应示例

虚拟账户交易

查询参数

响应示例

重新生成虚拟账户

重新生成参数

请求示例

更新虚拟账户

自动注资行为

更新参数

请求示例

响应示例

Webhooks

Webhook 事件

Webhook payload 示例

用例

电子商务支付