> ## 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.

# 支付订单

> 列出并跟踪一次性虚拟账户的支付订单，从创建到结算的全过程

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

## 前提条件

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

<Steps>
  <Step title="API 密钥">
    从 [Blockradar 控制台](https://dashboard.blockradar.co) 获取您的 API 密钥。前往 **Developers** 生成密钥。
  </Step>

  <Step title="已创建钱包">
    通过 [Create Wallet API](/en/api-reference/wallets/create-wallet) 或控制台创建钱包。支付订单操作需要 `walletId`。
  </Step>

  <Step title="合规已批准">
    在控制台完成尽职调查流程：My wallets > Settings > Compliance
  </Step>

  <Step title="功能已启用">
    合规批准后，申请开通虚拟账户功能。请联系 [support@blockradar.co](mailto:support@blockradar.co) 或使用控制台的在线聊天。
  </Step>

  <Step title="主网环境">
    虚拟账户仅在 **MAINNET**（主网）上可用。测试网环境不支持虚拟账户操作。
  </Step>

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

## 工作原理

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

<CardGroup cols={2}>
  <Card title="订单已创建" icon="plus">
    生成一笔订单，包含参考编号、预期金额及其收款通道。
  </Card>

  <Card title="账户已签发" icon="building-columns">
    对于一次性虚拟账户通道，会在 `paymentInstructions` 中附上一个一次性银行账户。
  </Card>

  <Card title="已收到付款" icon="credit-card">
    客户在 `expiresAt` 之前向该账户付款；订单会转为 `processing`，然后转为 `paid`。
  </Card>

  <Card title="结算" icon="wallet">
    等额的稳定币会被铸造并结算至关联的钱包或子地址。
  </Card>
</CardGroup>

## 订单状态

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

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

## 收款通道

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

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

## 列出主钱包支付订单

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

`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）。                                                |

### **响应示例**

```json theme={null}
{
  "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` 一同提供。                               |

### **响应示例**

```json theme={null}
{
  "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`           | 按状态汇总的订单计数。                                               |

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

***

## API 参考

### 发现与配置

| 端点                                                                                                      | 说明                |
| ------------------------------------------------------------------------------------------------------- | ----------------- |
| [Get Supported Assets](/en/api-reference/deposit-fiat/get-supported-assets)                             | 列出可用于法币充值的稳定币资产   |
| [Get Supported Currencies](/en/api-reference/deposit-fiat/get-supported-currencies)                     | 列出可用于充值的法币货币      |
| [Get Supported Rails](/en/api-reference/deposit-fiat/get-supported-rails)                               | 列出支持的法币收款通道       |
| [Resolve Payment Order Requirements](/en/api-reference/deposit-fiat/resolve-payment-order-requirements) | 解析在指定通道下创建订单所需的字段 |

### 主钱包

| 端点                                                                                                      | 说明             |
| ------------------------------------------------------------------------------------------------------- | -------------- |
| [Master Wallet Get Quote](/en/api-reference/deposit-fiat/master-wallet-get-quote)                       | 在创建订单前获取报价     |
| [Master Wallet Create Payment Order](/en/api-reference/deposit-fiat/master-wallet-create-payment-order) | 为主钱包创建一笔支付订单   |
| [List Payment Orders](/en/api-reference/deposit-fiat/master-wallet-list-payment-orders)                 | 列出某个主钱包的支付订单   |
| [Get Payment Order](/en/api-reference/deposit-fiat/master-wallet-get-payment-order)                     | 通过标识符检索单笔支付订单  |
| [Refresh Payment Order](/en/api-reference/deposit-fiat/master-wallet-refresh-payment-order)             | 刷新订单以获取最新状态和详情 |
| [Cancel Payment Order](/en/api-reference/deposit-fiat/master-wallet-cancel-payment-order)               | 取消一笔待处理的支付订单   |

### 子地址

| 端点                                                                                                      | 说明           |
| ------------------------------------------------------------------------------------------------------- | ------------ |
| [Get Child Address Quote](/en/api-reference/deposit-fiat/child-address-get-quote)                       | 在创建订单前获取报价   |
| [Create Child Address Payment Order](/en/api-reference/deposit-fiat/child-address-create-payment-order) | 为子地址创建一笔支付订单 |
| [List Child Address Payment Orders](/en/api-reference/deposit-fiat/child-address-list-payment-orders)   | 列出某个子地址的支付订单 |

<Note>
  检索、刷新和取消订单只需订单 ID，因此子地址没有对应的端点。任何订单（包括针对子地址创建的订单）都应使用上方的主钱包端点处理。

  此 API 还提供 **Find Fiat Deposit** 操作
  （`POST /v1/wallets/{id}/deposit/fiat/finder`），可根据支付参考编号定位法币充值及其处理详情。当客户声称已付款时，可用它将该笔付款与其所属订单进行对账。
</Note>