Developers

订单和幂等性

创建订单会锁定汇率并分配存款地址。这是集成错误会导致资金移动的地方：幂等性在此不是便利功能。

已发布合约，尚未开放

这些端点目前未公开。它们被记录在案，以便您可以提前构建集成；其形态已确定，任何破坏性变更都将通过新版本和变更日志条目进行。

POST/api/v1/ordersPublished contract, not open

创建订单

锁定汇率并返回专用存入地址。订单携带已锁定的明细：它是可重放的，使您即使在数月后也能重建确切应用的价格。需要Idempotency-Key头。

身份验证： Authorization: Bearer … 参见身份验证

参数

参数
字段	类型	描述
`quoteId`必需	string	已接受报价的标识符。
`beneficiary`必需	object	通道模式强加的字段。名称必须与已验证身份匹配：不允许第三方支付。
`networkId`必需	string	存入将发送到的网络。它决定返回的地址，以及在某些网络上的强制备注。

请求bash

curl -sS -X POST https://fiatside.com/api/v1/orders \
  -H 'Authorization: Bearer sk_live_...' \
  -H 'Idempotency-Key: 7f3a1c92-5d0e-4a1b-9c2f-6b8e0d4a1f33' \
  -H 'Content-Type: application/json' \
  -d '{
    "quoteId": "qt_01J9Z...",
    "networkId": "tron",
    "beneficiary": {
      "railId": "sepa_instant",
      "beneficiaryName": "Camille Dupont",
      "iban": "FR7630001007941234567890185"
    }
  }'

响应——已发布合约json

{
  "reference": "K7Q4-M2XB",
  "state": "AWAITING_DEPOSIT",
  "deposit": {
    "asset": "USDT",
    "network": "tron",
    "address": "T...",
    "memo": null,
    "amountBase": "1000000000",
    "expiresAt": "2026-09-02T12:41:00Z"
  },
  "payout": { "railId": "sepa_instant", "netMinor": 91228, "currency": "EUR" },
  "rateLock": { "midRate": "0.92168430", "lockedUntil": "2026-09-02T12:41:00Z" }
}

备注在大多数网络上为null，在XRP、Stellar和TON上为必填。在这些网络上省略备注会丢失资金：一旦字段非null，就将其视为必填。

可能的错误： unauthorized, invalid_request, quote_expired, idempotency_conflict, beneficiary_rejected, country_not_served. 完整目录

GET/api/v1/orders/{reference}Published contract, not open

读取订单

当前状态和带时间戳的转换历史。历史是事实来源：它是仅追加的，从不重写，它回答了“为什么我的订单在那个时间移动到那个状态”。

身份验证： Authorization: Bearer … 参见身份验证

请求bash

curl -sS https://fiatside.com/api/v1/orders/K7Q4-M2XB \
  -H 'Authorization: Bearer sk_live_...'

响应——已发布合约json

{
  "reference": "K7Q4-M2XB",
  "state": "COMPLETED",
  "transitions": [
    { "at": "2026-09-02T12:11:04Z", "from": "QUOTE_LOCKED",     "to": "AWAITING_DEPOSIT" },
    { "at": "2026-09-02T12:19:52Z", "from": "AWAITING_DEPOSIT", "to": "DEPOSIT_DETECTED" },
    { "at": "2026-09-02T12:21:10Z", "from": "CONFIRMING",       "to": "DEPOSIT_CONFIRMED" },
    { "at": "2026-09-02T12:21:44Z", "from": "PAYOUT_QUEUED",    "to": "PAYOUT_SENT" },
    { "at": "2026-09-02T12:22:03Z", "from": "PAYOUT_SENT",      "to": "COMPLETED" }
  ]
}

可能的错误： unauthorized, not_found. 完整目录

幂等性

创建请求在网络超时时，无法告知您订单是否已创建。没有幂等键，您只有两个糟糕的选择：重试并冒创建两个订单的风险，或不重试并冒一个都没有的风险。

请求头http

Idempotency-Key: 7f3a1c92-5d0e-4a1b-9c2f-6b8e0d4a1f33

每个意图一个键

该键标识意图“创建该订单”，而非 HTTP 请求。您这边的一个唯一 ID：购物车 ID、调用前生成的 UUID，绝不要用计数器。

重放返回原始响应

使用相同键和相同请求体重放，将返回第一个请求的响应，并带有相同的 HTTP 状态。这就是重试安全的原因，包括超时后的重试。

相同键，不同请求体：冲突

响应是明确的冲突。如果内容改变，键也必须改变：否则无法判断应重放哪个订单。

24 小时保留

之后键被遗忘，重放将创建新订单。在窗口内重试，或使用读取端点检查状态。

备注（在需要备注的网络上）

在 XRP、Stellar 和 TON 上，存款地址不够：需要额外的标识符来指定最终接收方。这是出金集成中代价最高的故障原因。

没有备注的存款是丢失的存款

在大多数网络上 memo 字段为 null，在需要它的网络上为非 null。一旦非 null，就应视为必填，并以与地址相同的权重显示。在共享地址上，没有备注到达的存款需要手动恢复，这并不总是成功。

订单状态

以下状态是您的集成可以观察到的。转换带有时间戳并追加，从不重写：历史记录回答“为什么我的订单在那个时候移动到那个状态”。

订单状态
状态	含义
`QUOTE_LOCKED`	汇率已冻结。订单等待收款人详细信息或身份验证。
`AWAITING_DEPOSIT`	存款地址已分配，存款窗口正在运行。这是唯一可以发送资金的时刻。
`DEPOSIT_DETECTED`	在网络上看到一笔传入交易，尚未确认。安抚用户，不要交付任何东西。
`CONFIRMING`	确认数正在累积。所需数量取决于网络，而非金额。
`DEPOSIT_CONFIRMED`	存款已安全。合规和重新定价规则从此处开始评估。
`UNDERPAID`	收到的金额低于预期且超出容差。三种结果：补足、按收到金额继续，或退款。
`OVERPAID`	收到的金额超过预期。初始金额按锁定汇率计算，超出部分另行处理。
`PAYOUT_QUEUED`	转账已排队。队列保证即使多个工作进程并行触发，付款也会发送一次。
`PAYOUT_SENT`	转账已通过支付通道发出。已发送不等于已收到：最终延迟取决于收款银行。
`COMPLETED`	结算已由支付通道确认。终态。
`PAYOUT_FAILED`	支付通道拒绝或退回转账。不会自动重试：原因几乎总是出在细节上。
`REFUNDED`	资金已退回原始地址，扣除网络费用。终态。