> ## Documentation Index
> Fetch the complete documentation index at: https://docs.velafi.com/llms.txt
> Use this file to discover all available pages before exploring further.

# 获取订单

> 通过订单 ID 获取单个订单的完整详情和当前状态。支持法币兑加密货币、加密货币兑法币以及法币兑法币订单类型。

使用此端点获取任意订单的完整状态——包括支付说明、汇率、金额、时间戳以及当前状态码。由于单币种订单（`fiat_to_crypto` / `crypto_to_fiat`）与跨币种订单（`fiat_to_fiat`）的响应结构不同，您必须提供 `orderType` 查询参数，并同时提供 `orderId`（对于 `fiat_to_crypto` 和 `crypto_to_fiat` 订单，也可以提供您的 `clientId`）。轮询此端点可驱动应用中基于状态的逻辑，例如向用户展示支付说明，或在 `orderStatus` 达到 `60`（已完成）时触发下游流程。

## 端点

```text theme={null}
GET https://api.velafi.com/v2/order/detail
```

> [!NOTE]
>
> 沙盒环境测试请使用 `https://api-test.velafi.com/v2/order/detail`。

## 查询参数

**orderId** `integer`

要获取的订单的唯一数字 ID。`fiat_to_fiat` 订单必填。对于 `fiat_to_crypto` 和 `crypto_to_fiat` 订单，可传入 `orderId` 或 `clientId`；若两者都传入，则使用 `orderId`。

**clientId** `string`

您在创建订单时提供的 `clientId`。仅支持 `fiat_to_crypto` 和 `crypto_to_fiat` 订单。

**orderType** `string` *required*

订单类型。必须为 `fiat_to_crypto`、`crypto_to_fiat` 或 `fiat_to_fiat` 之一。

## 订单状态码

`orderStatus` 对 `fiat_to_crypto` / `crypto_to_fiat` 订单使用一套状态码，对 `fiat_to_fiat` 订单使用另一套状态码。

| 订单类型 | 可能收到的状态码 |
| - | - |
| `fiat_to_crypto`, `crypto_to_fiat` | `10`, `11`, `12`, `31`, `32`, `40`, `50`, `60`, `70`, `71`, `72`, `73`, `80`, `81` |
| `fiat_to_fiat` | `10`, `11`, `12`, `31`, `41`, `51`, `60`, `71`, `72`, `90` |

> [!NOTE]
>
> 由 VelaFi 为您的账户创建的出入金订单（而非通过 API 或控制台创建）还可能显示 `20`（审核被拒）或 `30`（已批准）。

## 响应字段 — 法币兑加密货币 / 加密货币兑法币

**code** `integer`

响应状态码。`200` 表示成功。

**msg** `string`

可读的响应消息。

**data** `object`

订单详情对象。

**data 字段**

**data.orderId** `string`

唯一订单 ID。

**data.clientId** `string`

您在创建时提供的自定义订单参考 ID。

**data.merchantId** `integer`

与此订单关联的商户 ID。

**data.paymentId** `integer`

支付方式 ID（`fiat_to_crypto` 订单会填充此字段）。

**data.userPaymentId** `integer`

用户收款方式（收款人）ID（`crypto_to_fiat` 订单会填充此字段）。

**data.country** `string`

此订单的国家名称。

**data.crypto** `string`

加密货币代码（例如 `"USDT"`）。

**data.fiat** `string`

法币代码（例如 `"MXN"`）。

**data.orderType** `string`

订单类型：`fiat_to_crypto` 或 `crypto_to_fiat`。

**data.orderPrice** `string`

订单创建时的汇率（每单位加密货币对应的法币数量）。

**data.cryptoAmount** `string`

订单涉及的加密货币数量。

**data.fiatAmount** `string`

订单涉及的法币金额。

**data.fiatFee** `string`

以法币收取的手续费。

**data.orderStatus** `integer`

当前订单状态码。请参阅上方状态表。

**data.traceNumber** `string`

国家中央银行的交易参考编号。

**data.paymentInfo** `object`

此订单支付说明的键值映射（例如墨西哥 SPEI 订单的 CLABE 号码）。内容因国家和支付方式而异。

**data.failCode** `integer`

失败订单记录的错误码。未记录失败码时为 `0`。

**data.failReason** `string`

订单失败原因的可读描述。

**data.createTime** `string`

订单创建时的 Unix 时间戳（毫秒）。

**data.completedTime** `string`

订单进入最终状态时的 Unix 时间戳（毫秒）。在此之前，该值等于 `createTime`。

**data.orderExpireTimestamp** `string`

仅在订单处于 `status: 32`（等待加密货币充值，后付款出金）时返回。商户加密货币余额必须覆盖该订单的截止时间，以秒为单位的 Unix 时间戳表示。

**data.bankOrderId** `string`

订单的银行端参考号。目前主要为 ARS 订单填充。

**data.orderFeeDetail** `object`

逐项列出的手续费明细。仅对记录了分项手续费的订单列出费用条目。

**orderFeeDetail 字段**

**grossAmount** `string`

订单的法币总金额，包含 `feeLines` 中列出的手续费。

**netAmount** `string`

`grossAmount` 减去各费用条目 `amount` 之和。

**feeLines** `array`

每项费用对应一个条目。每个条目包含 `feeType`（例如 `CONVERT_FEE`）、`rate`（小数形式；乘以 100 即为百分比）、`fixed`（固定费用）、`receivableAmount`（减免前应收的费用）、`amount`（实际收取的费用）、`currency` 以及 `hasWaived`（费用已减免时为 `1`，否则为 `0`）。

## 响应字段 — 法币兑法币

**data** `object`

法币兑法币订单详情对象。

**data 字段**

**data.orderId** `string`

唯一订单 ID。

**data.clientId** `string`

您的自定义订单参考 ID。

**data.onRampMerchantId** `integer`

入金环节的商户 ID。

**data.onRampPaymentId** `integer`

入金环节的支付方式 ID。

**data.onRampCountry** `string`

收取法币的国家。

**data.onRampFiat** `string`

入金环节收取的法币币种。

**data.onRampFiatAmount** `string`

入金环节收取的金额。

**data.onRampFiatFee** `string`

入金环节的手续费。

**data.offRampMerchantId** `integer`

出金环节的商户 ID。

**data.offRampPaymentId** `integer`

出金环节的收款人收款方式 ID。

**data.offRampCountry** `string`

交付法币的国家。

**data.offRampFiat** `string`

出金环节交付的法币币种。

**data.offRampFiatAmount** `string`

扣除手续费前的待交付金额。

**data.offArriveRampFiatAmount** `string`

扣除手续费后收款人实际到账的净额。

**data.offRampFiatFee** `string`

出金环节的手续费。

**data.orderPrice** `string`

订单创建时的跨币种汇率。

**data.orderStatus** `integer`

当前订单状态。请参阅上方法币兑法币状态码。

**data.onRampPaymentInfo** `object`

入金环节的支付说明（例如 MXN 的 CLABE）。

**data.offRampPaymentInfo** `object`

出金环节的支付说明。

**data.createTime** `string`

订单创建时的 Unix 时间戳（毫秒）。

**data.completedTime** `string`

订单完成时的 Unix 时间戳（毫秒）。

**data.onRampOrderFeeDetail** `object`

入金环节的分项手续费明细。结构与上方的 `orderFeeDetail` 相同。

**data.offRampOrderFeeDetail** `object`

出金环节的分项手续费明细。结构与上方的 `orderFeeDetail` 相同。

## 示例

> [tab] 法币兑加密货币订单
>
> ```bash theme={null}
> curl -X GET "https://api.velafi.com/v2/order/detail?orderId=493829236956962816&orderType=fiat_to_crypto" \
>   -H "X-BH-TOKEN: YOUR_TOKEN"
> ```
>
> ```json theme={null}
> {
>   "code": 200,
>   "msg": "SUCCESS",
>   "data": {
>     "orderId": "493829236956962816",
>     "clientId": "f_c_0250222004",
>     "merchantId": 3,
>     "paymentId": 0,
>     "userPaymentId": 0,
>     "country": "Mexico",
>     "crypto": "USDT",
>     "fiat": "MXN",
>     "orderType": "fiat_to_crypto",
>     "orderPrice": "21.4104",
>     "cryptoAmount": "5.1376",
>     "fiatAmount": "110",
>     "fiatFee": "0",
>     "orderStatus": 60,
>     "hasRefund": 0,
>     "failCode": 0,
>     "failReason": "",
>     "traceNumber": "20241223907069062e51744c4f0e57",
>     "paymentInfo": {
>       "Cuenta CLABE": "000000000000000001"
>     },
>     "createTime": "1740214865000",
>     "completedTime": "1740214866000"
>   }
> }
> ```

> [tab] 法币兑法币订单
>
> ```bash theme={null}
> curl -X GET "https://api.velafi.com/v2/order/detail?orderId=494541042692263936&orderType=fiat_to_fiat" \
>   -H "X-BH-TOKEN: YOUR_TOKEN"
> ```
>
> ```json theme={null}
> {
>   "code": 200,
>   "msg": "SUCCESS",
>   "data": {
>     "orderId": "494541042692263936",
>     "clientId": "c_f_0250224003",
>     "onRampMerchantId": 3,
>     "onRampPaymentId": 17,
>     "onRampCountry": "Mexico",
>     "onRampFiat": "MXN",
>     "onRampFiatAmount": "110",
>     "onRampFiatFee": "1",
>     "offRampCountry": "Argentina",
>     "offRampMerchantId": 4,
>     "offRampPaymentId": 134,
>     "offRampFiat": "ARS",
>     "offRampFiatAmount": "6156.3",
>     "offArriveRampFiatAmount": "6155.3",
>     "offRampFiatFee": "1",
>     "orderPrice": "55.9664",
>     "orderStatus": 31,
>     "onRampPaymentInfo": {
>       "Cuenta CLABE": "000000000000000001"
>     },
>     "offRampPaymentInfo": {
>       "CVU/CBU": "0000000000000000000002"
>     },
>     "createTime": "1740384573000",
>     "completedTime": "1740384573000"
>   }
> }
> ```


## Related topics

- [获取订单列表](https://docs.velafi.com/cn/api-reference/order/retrieve-a-list-of-orders.md)
- [确认订单](https://docs.velafi.com/cn/api-reference/order/confirm-a-specific-order.md)
- [创建入金订单](https://docs.velafi.com/cn/api-reference/order/create-a-fiat-to-crypto-order.md)
- [入金（法币兑加密货币）](https://docs.velafi.com/cn/docs/guides/on-ramp.md)
- [错误码](https://docs.velafi.com/cn/docs/error-codes.md)


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.