支付订单

简而言之
一笔支付订单代表一次预期的法币收款。当您使用一次性虚拟账户通道时，每笔订单都由一个专用银行账户支持，该账户仅对一次付款有效。支付订单端点让您能够在主钱包层级列出并跟踪每一笔订单，或将范围限定到特定的子地址。

前提条件

在使用支付订单 API 之前，请确保您已具备：

API 密钥

从 Blockradar 控制台获取您的 API 密钥。前往 Developers 生成密钥。

已创建钱包

在控制台中（参见创建主钱包）创建钱包。支付订单操作需要 walletId。

合规已批准

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

功能已启用

合规批准后，申请开通虚拟账户功能。请联系 [email protected] 或使用控制台的在线聊天。

主网环境

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

稳定币支持

充值法币并将其转换为稳定币是一项付费功能。请确保您的账户套餐包含稳定币访问权限。通过 控制台 → Settings → Subscription 升级。

工作原理

每当客户发起一笔法币充值时，就会创建一笔支付订单。对于 one_time_virtual_account 通道，Blockradar 会签发一个与该订单及其金额集合绑定的全新虚拟银行账户。客户付款后，订单会按其生命周期推进，对应的稳定币会被铸造并结算至关联的钱包或地址。

订单已创建

生成一笔订单，包含参考编号、预期金额及其收款通道。

账户已签发

对于一次性虚拟账户通道，会在 paymentInstructions 中附上一个一次性银行账户。

已收到付款

客户在 expiresAt 之前向该账户付款；订单会转为 processing，然后转为 paid。

结算

等额的稳定币会被铸造并结算至关联的钱包或子地址。

订单状态

每笔订单都会报告其当前的生命周期状态。使用 status 查询参数来筛选结果。

状态	说明
`pending`	订单已创建，等待客户付款。
`processing`	已收到付款，正在确认/结算中。
`paid`	付款已确认并成功结算。
`expired`	订单未在 `expiresAt` 之前完成付款。
`failed`	付款或结算无法完成。
`cancelled`	订单在付款前被取消。

收款通道

rail 字段标识订单的收款方式。一次性虚拟账户使用 one_time_virtual_account 通道。

通道	说明
`one_time_virtual_account`	仅对一次付款有效的专用银行账户。
`payment_link`	托管的支付链接。
`qr_code`	可扫描的二维码。

绑定会话的创建流程

要创建支付订单，请先使用 assetId、currency、amount 和 rail 请求报价。当存款属于现有客户时，还请包含 customerId，以便复用已保存的提供方 KYC。提供方适配器会根据所选法币货币推断 KYC 走廊。报价会返回 sessionId 和 sessionExpiresAt。该会话会在 20 分钟内绑定钱包、钱包资产、法币货币、金额、通道、提供方、转换路径、客户和 KYC 走廊。我们建议在后续每个请求中都使用返回的 sessionId：

当 additionalDataRequirements.data 不为 null 时，使用它初始化表单。其中包含已为该客户、提供方和走廊保存的可复用值。
收集 additionalDataRequirements.schema 要求的所有缺失值。
如果 schema 包含 x-resolution，请使用 sessionId 和当前的 additionalData 调用 POST /v1/wallets/{id}/deposit/fiat/payment-order-requirements/resolve。
将解析得到的值合并到 additionalData 中。
使用 sessionId、additionalData 以及任何可选订单字段（例如 reference 或 metadata）创建订单。

Quote request

{
  "assetId": "ae455f23-3824-4125-baab-d158315cbcbd",
  "currency": "NGN",
  "amount": "100.00",
  "rail": "one_time_virtual_account",
  "customerId": "18d2f159-e0cd-4a45-b735-e9dfe0f7520a"
}

Quote session

{
  "sessionId": "13a36c1c-f4a6-4e49-a582-2ecded2559bc",
  "sessionExpiresAt": "2026-09-15T15:20:00.000Z",
  "additionalDataRequirements": {
    "schema": {
      "$schema": "http://json-schema.org/draft-07/schema#",
      "type": "object",
      "title": "Refund account and customer KYC"
    },
    "data": null
  }
}

为简洁起见，上例仅展示了 schema 的顶层字段；请渲染 API 返回的完整的提供方专属 JSON Schema。

Resolve requirements

{
  "sessionId": "13a36c1c-f4a6-4e49-a582-2ecded2559bc",
  "additionalData": {
    "institutionIdentifier": "OPAYNGPC",
    "accountIdentifier": "8034007516",
    "kyc": {
      "entityType": "person",
      "personDetails": {
        "fullName": "Ada Okafor",
        "birthDate": "1992-04-18",
        "idDocument": {
          "number": "12345678901"
        },
        "taxId": {
          "value": "10987654321"
        }
      }
    }
  }
}

Create payment order

{
  "sessionId": "13a36c1c-f4a6-4e49-a582-2ecded2559bc",
  "additionalData": {
    "institutionIdentifier": "OPAYNGPC",
    "accountIdentifier": "8034007516",
    "accountName": "Ada Okafor",
    "kyc": {
      "entityType": "person",
      "personDetails": {
        "fullName": "Ada Okafor",
        "birthDate": "1992-04-18",
        "idDocument": {
          "number": "12345678901"
        },
        "taxId": {
          "value": "10987654321"
        }
      }
    }
  },
  "reference": "dep_20260915_001"
}

上例为 Paycrest NGN 个人资料：idDocument.number 是客户的 11 位 NIN，taxId.value 是客户的 11 位 BVN。要求因提供方、走廊和实体类型而异，因此请始终渲染报价返回的 schema，而不要硬编码这些字段。当使用内联 KYC 创建订单时，Blockradar 会将其与业务客户、所选提供方和走廊关联保存。之后使用相同 customerId 和走廊发起的报价会在 additionalDataRequirements.data 中返回已保存的 KYC。在之后的订单中提交更改后的 KYC 会更新已保存的走廊资料；无需单独的 KYC 端点。

请勿将会话与来自其他报价的资产、货币、金额、通道或提供方值混用。如果 API 返回 FIAT_DEPOSIT_SESSION_EXPIRED、FIAT_DEPOSIT_SESSION_MISMATCH 或 FIAT_DEPOSIT_SESSION_UNAVAILABLE，请重新请求报价并重新开始要求解析。

为保持向后兼容，sessionId 为可选项。如果省略它，请在要求解析和订单创建请求中发送原始的 assetId、currency、amount 和 rail。当提供 sessionId 时，以会话中存储的值为准。

列出主钱包支付订单

返回某个主钱包下创建的所有支付订单的分页列表。使用查询参数按状态、通道、货币、资产、日期范围或自由文本搜索进行筛选。 GET /v1/wallets/{id}/deposit/fiat/orders

查询参数

参数	类型	说明
`status`	enum	按订单状态筛选：`pending`、`paid`、`processing`、`expired`、`failed`、`cancelled`。
`rail`	enum	按收款通道筛选：`one_time_virtual_account`、`payment_link`、`qr_code`。
`currency`	string	ISO 4217 法币货币代码（3 个字符），例如 `NGN`。
`assetId`	string	稳定币资产标识符（UUID）。
`search`	string	按参考编号、标签、账户名称或账号查询。
`startDate`	string	含边界的 ISO 8601 起始日期。需与 `endDate` 一同提供。
`endDate`	string	含边界的 ISO 8601 结束日期。需与 `startDate` 一同提供。
`page`	number	从 1 开始的页码（默认：1）。
`limit`	number	每页记录数（默认：10，范围：1–100）。

响应示例

{
  "statusCode": 200,
  "message": "Successful",
  "data": [
    {
      "id": "80ea45ab-38b9-4506-b213-52da8bc7e825",
      "type": "deposit",
      "rail": "one_time_virtual_account",
      "reference": "dep_20260719_001",
      "status": "pending",
      "currency": "NGN",
      "amount": "100.00",
      "amountFiat": "155000.00",
      "feeFiat": "1500.00",
      "amountFiatPayable": "156500.00",
      "expiresAt": "2026-07-19T13:00:00.000Z",
      "paymentInstructions": {
        "type": "one_time_virtual_account",
        "bank": {
          "name": "Example Bank",
          "code": "999",
          "accountName": "Blockradar / Acme Ltd",
          "accountNumber": "0123456789"
        }
      },
      "asset": {
        "id": "ae455f23-3824-4125-baab-d158315cbcbd",
        "symbol": "USDC",
        "name": "USD Coin"
      },
      "wallet": {
        "id": "4465468a-3c36-4536-918a-91d689e18a74",
        "address": "0x947514e4B803e312C312da0F1B41fEDdbe15ae7a"
      },
      "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
  },
  "analytics": {
    "totalOrdersCount": 1,
    "totalPendingOrdersCount": 1,
    "totalPaidOrdersCount": 0
  }
}

列出子地址支付订单

返回范围限定于单个子地址的支付订单。响应包含相同的订单字段，以及额外的结算、提供方和客户详情。 GET /v1/wallets/{walletId}/addresses/{addressId}/deposit/fiat/orders

路径参数

参数	类型	是否必填	说明
`walletId`	string	是	钱包标识符（UUID）。
`addressId`	string	是	子地址标识符（UUID）。

查询参数

参数	类型	说明
`status`	enum	按订单状态筛选：`pending`、`paid`、`processing`、`expired`、`failed`、`cancelled`。
`rail`	enum	按收款通道筛选：`one_time_virtual_account`、`payment_link`、`qr_code`。
`currency`	string	ISO 4217 法币货币代码（3 个字符），例如 `NGN`。
`assetId`	string	稳定币资产标识符（UUID）。
`search`	string	按参考编号、标签、账户名称或账号查询。
`startDate`	string	含边界的 ISO 8601 起始日期。需与 `endDate` 一同提供。
`endDate`	string	含边界的 ISO 8601 结束日期。需与 `startDate` 一同提供。

响应示例

{
  "statusCode": 200,
  "message": "Successful",
  "data": [
    {
      "id": "80ea45ab-38b9-4506-b213-52da8bc7e825",
      "type": "deposit",
      "rail": "one_time_virtual_account",
      "reference": "dep_20260719_001",
      "providerReference": "provider_order_839201",
      "transactionId": null,
      "status": "pending",
      "currency": "NGN",
      "amount": "100.00",
      "amountFiat": "155000.00",
      "feeFiat": "1500.00",
      "amountFiatPayable": "156500.00",
      "amountFiatReceived": null,
      "amountSettled": null,
      "expiresAt": "2026-07-19T13:00:00.000Z",
      "paymentInstructions": {
        "type": "one_time_virtual_account",
        "bank": {
          "name": "Example Bank",
          "code": "999",
          "accountName": "Blockradar / Acme Ltd",
          "accountNumber": "0123456789"
        },
        "paymentLink": null,
        "qrCode": null,
        "expiresAt": "2026-07-19T13:00:00.000Z",
        "metadata": null
      },
      "metadata": {
        "checkoutId": "checkout_123"
      },
      "provider": {
        "id": "1128dd40-2c94-4c16-a6bf-fbbc6afee52c",
        "slug": "example-provider",
        "name": "Example Provider"
      },
      "wallet": {
        "id": "4465468a-3c36-4536-918a-91d689e18a74",
        "address": "0x947514e4B803e312C312da0F1B41fEDdbe15ae7a"
      },
      "address": null,
      "asset": {
        "id": "ae455f23-3824-4125-baab-d158315cbcbd",
        "symbol": "USDC",
        "name": "USD Coin"
      },
      "customer": {
        "id": "18d2f159-e0cd-4a45-b735-e9dfe0f7520a"
      },
      "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
  },
  "links": {
    "first": "https://api.blockradar.co/v1/wallets/.../deposit/fiat/orders?page=1&limit=10",
    "previous": null,
    "next": null,
    "last": "https://api.blockradar.co/v1/wallets/.../deposit/fiat/orders?page=1&limit=10"
  },
  "analytics": {
    "totalOrdersCount": 1,
    "totalPendingOrdersCount": 1,
    "totalPaidOrdersCount": 0,
    "totalProcessingOrdersCount": 0,
    "totalExpiredOrdersCount": 0,
    "totalFailedOrdersCount": 0,
    "totalCancelledOrdersCount": 0
  }
}

响应字段

字段	说明
`id`	支付订单的唯一标识符。
`type`	订单类型。法币收款为 `deposit`。
`rail`	该订单使用的收款通道。
`reference`	您为该订单设定的参考编号。
`status`	订单当前的生命周期状态。
`currency`	预期付款的 ISO 4217 法币货币。
`amount`	待铸造的稳定币金额。
`amountFiat`	扣除手续费前订单的法币价值。
`feeFiat`	以法币收取的手续费。
`amountFiatPayable`	客户需支付的法币总额（`amountFiat` + `feeFiat`）。
`expiresAt`	未付款订单在此时间戳之后过期。
`paymentInstructions`	客户的付款方式。对于 `one_time_virtual_account` 通道，包含一次性 `bank` 详情。
`asset`	订单结算所使用的稳定币资产。
`wallet`	该订单所属的主钱包。
`meta`	结果集的分页元数据。
`analytics`	按状态汇总的订单计数。

amountFiatReceived、amountSettled、providerReference、provider 和 customer 字段会在子地址端点返回，并随着订单在结算过程中的推进而填充。

API 参考

发现与配置

端点	说明
Get Supported Assets	列出可用于法币充值的稳定币资产
Get Supported Currencies	列出可用于充值的法币货币
Get Supported Rails	列出支持的法币收款通道
Resolve Payment Order Requirements	解析在指定通道下创建订单所需的字段

主钱包

端点	说明
Master Wallet Get Quote	在创建订单前获取报价
Master Wallet Create Payment Order	为主钱包创建一笔支付订单
List Payment Orders	列出某个主钱包的支付订单
Get Payment Order	通过标识符检索单笔支付订单
Refresh Payment Order	刷新订单以获取最新状态和详情
Cancel Payment Order	取消一笔待处理的支付订单

子地址

端点	说明
Get Child Address Quote	在创建订单前获取报价
Create Child Address Payment Order	为子地址创建一笔支付订单
List Child Address Payment Orders	列出某个子地址的支付订单

检索、刷新和取消订单只需订单 ID，因此子地址没有对应的端点。任何订单（包括针对子地址创建的订单）都应使用上方的主钱包端点处理。此 API 还提供 Find Fiat Deposit 操作（POST /v1/wallets/{id}/deposit/fiat/finder），可根据支付参考编号定位法币充值及其处理详情。当客户声称已付款时，可用它将该笔付款与其所属订单进行对账。

开始使用

钱包

收款

付款

转换与管理

合规与工具

前提条件

工作原理

订单已创建

账户已签发

已收到付款

结算

订单状态

收款通道

绑定会话的创建流程

列出主钱包支付订单

查询参数

响应示例

列出子地址支付订单

路径参数

查询参数

响应示例

响应字段

API 参考

发现与配置

主钱包

子地址

​前提条件

​工作原理

订单已创建

账户已签发

已收到付款

结算

​订单状态

​收款通道

​绑定会话的创建流程

​列出主钱包支付订单

​查询参数

​响应示例

​列出子地址支付订单

​路径参数

​查询参数

​响应示例

​响应字段

​API 参考

​发现与配置

​主钱包

​子地址

前提条件

工作原理

订单状态

收款通道

绑定会话的创建流程

列出主钱包支付订单

查询参数

响应示例

列出子地址支付订单

路径参数

查询参数

响应示例

响应字段

API 参考

发现与配置

主钱包

子地址