获取订单

GET

order

detail

获取订单

curl --request GET \
  --url https://api-test.velafi.com/v2/order/detail \
  --header 'X-BH-TOKEN: <api-key>'

const options = {method: 'GET', headers: {'X-BH-TOKEN': '<api-key>'}};

fetch('https://api-test.velafi.com/v2/order/detail', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

{
  "code": 123,
  "msg": "<string>",
  "data": {
    "data.orderId": "<string>",
    "data.clientId": "<string>",
    "data.onRampMerchantId": 123,
    "data.onRampPaymentId": 123,
    "data.onRampCountry": "<string>",
    "data.onRampFiat": "<string>",
    "data.onRampFiatAmount": "<string>",
    "data.onRampFiatFee": "<string>",
    "data.offRampMerchantId": 123,
    "data.offRampPaymentId": 123,
    "data.offRampCountry": "<string>",
    "data.offRampFiat": "<string>",
    "data.offRampFiatAmount": "<string>",
    "data.offArriveRampFiatAmount": "<string>",
    "data.offRampFiatFee": "<string>",
    "data.orderPrice": "<string>",
    "data.orderStatus": 123,
    "data.onRampPaymentInfo": {},
    "data.offRampPaymentInfo": {},
    "data.createTime": "<string>",
    "data.completedTime": "<string>",
    "data.onRampOrderFeeDetail": {},
    "data.offRampOrderFeeDetail": {}
  }
}

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

端点

GET https://api.velafi.com/v2/order/detail

沙盒环境测试请使用 https://api-test.velafi.com/v2/order/detail。

查询参数

integer

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

string

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

string

必填

订单类型。必须为 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`

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

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

integer

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

string

可读的响应消息。

object

订单详情对象。

显示 data 字段

string

唯一订单 ID。

string

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

integer

与此订单关联的商户 ID。

integer

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

integer

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

string

此订单的国家名称。

string

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

string

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

string

订单类型：fiat_to_crypto 或 crypto_to_fiat。

string

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

string

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

string

订单涉及的法币金额。

string

以法币收取的手续费。

integer

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

string

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

object

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

integer

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

string

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

string

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

string

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

string

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

string

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

object

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

显示 orderFeeDetail 字段

string

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

string

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

array

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

响应字段 — 法币兑法币

object

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

显示 data 字段

string

唯一订单 ID。

string

您的自定义订单参考 ID。

integer

入金环节的商户 ID。

integer

入金环节的支付方式 ID。

string

收取法币的国家。

string

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

string

入金环节收取的金额。

string

入金环节的手续费。

integer

出金环节的商户 ID。

integer

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

string

交付法币的国家。

string

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

string

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

string

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

string

出金环节的手续费。

string

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

integer

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

object

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

object

出金环节的支付说明。

string

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

string

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

object

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

object

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

示例

法币兑加密货币订单
法币兑法币订单

curl -X GET "https://api.velafi.com/v2/order/detail?orderId=493829236956962816&orderType=fiat_to_crypto" \
  -H "X-BH-TOKEN: YOUR_TOKEN"

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

curl -X GET "https://api.velafi.com/v2/order/detail?orderId=494541042692263936&orderType=fiat_to_fiat" \
  -H "X-BH-TOKEN: YOUR_TOKEN"

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

⌘I

获取订单

curl --request GET \
  --url https://api-test.velafi.com/v2/order/detail \
  --header 'X-BH-TOKEN: <api-key>'

const options = {method: 'GET', headers: {'X-BH-TOKEN': '<api-key>'}};

fetch('https://api-test.velafi.com/v2/order/detail', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

{
  "code": 123,
  "msg": "<string>",
  "data": {
    "data.orderId": "<string>",
    "data.clientId": "<string>",
    "data.onRampMerchantId": 123,
    "data.onRampPaymentId": 123,
    "data.onRampCountry": "<string>",
    "data.onRampFiat": "<string>",
    "data.onRampFiatAmount": "<string>",
    "data.onRampFiatFee": "<string>",
    "data.offRampMerchantId": 123,
    "data.offRampPaymentId": 123,
    "data.offRampCountry": "<string>",
    "data.offRampFiat": "<string>",
    "data.offRampFiatAmount": "<string>",
    "data.offArriveRampFiatAmount": "<string>",
    "data.offRampFiatFee": "<string>",
    "data.orderPrice": "<string>",
    "data.orderStatus": 123,
    "data.onRampPaymentInfo": {},
    "data.offRampPaymentInfo": {},
    "data.createTime": "<string>",
    "data.completedTime": "<string>",
    "data.onRampOrderFeeDetail": {},
    "data.offRampOrderFeeDetail": {}
  }
}

概览

账户

配置

商户

加密钱包

收款人

报价

订单

Webhooks

端点

查询参数

订单状态码

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

响应字段 — 法币兑法币

示例

​端点

​查询参数

​订单状态码

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

​响应字段 — 法币兑法币

​示例

端点

查询参数

订单状态码

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

响应字段 — 法币兑法币

示例