開發者文件

商戶系統對接、渠道對接規格、Webhook 事件說明、部署指引與版本紀錄

本文件對象為商戶的工程師。名詞對照:商戶(API 中稱 platform)/渠道(API 中稱 merchant,僅為商戶後台資料,無登入、無 API Key)/客戶(platformUserId)。API 路徑、Header 與 SDK 物件名維持原樣。若您是想部署 SOHO Wallet 的授權客戶,請先閱讀 授權說明,再參考本頁「部署指引」分頁。

10 分鐘接通

給第一次接的商戶工程師:照下面四步,從拿 Key 到收到「訂單完成」通知。每步一個 curl,細節都連到後面各節。想先不碰真實渠道,可直接跳到最後一段「先用沙盒渠道試」。

API Key 只放在貴司後端,不要放進前端或客戶端程式。下面的 curl 都用環境變數,先在終端機貼上這兩行(換成您自己的值),之後每個 curl 整行可直接複製執行;JSON 內的 {…} 請換成上一步回應的值。

bash
export KEY=貼上您的商戶API_Key
export USER_ID=customer-001   # 貴司系統的客戶唯一 ID(試算、建單、查單都必帶 x-user-id)

① 拿商戶 API Key、填通知網址

登入商戶後台 /console/integration(系統對接):產生並複製商戶 API Key(只顯示一次),再填通知網址(Webhook URL,訂單完成時支付中心會 POST 到這裡)。之後所有 API 都帶 header x-api-key。

② 三支 API:渠道 → 試算 → 建單

先列出可用渠道(詳見):

bash
curl "/api/v1/channels?currency=THB" \
  -H "x-api-key: $KEY"

回應節錄(200):

json
{ "channels": [ { "channelId": "渠道 ID", "name": "渠道名稱", "fiat": "THB", "referenceRate": "36.52" } ], "serverTime": "..." }

客戶選好渠道與金額後試算,取得報價單號 quoteId(詳見):

bash
curl -X POST /api/v1/quotes \
  -H "x-api-key: $KEY" \
  -H "x-user-id: $USER_ID" \
  -H "Content-Type: application/json" \
  -d '{ "channelId": "$CHANNEL_ID", "currency": "THB", "crypto": "USDT", "cryptoAmount": "10", "type": "buy" }'

回應節錄(201):

json
{ "quoteId": "報價單號(下單要帶)", "cryptoAmount": "10", "fiatAmount": "365.20", "referenceRate": "36.52", "rate": "36.52", "expiresAt": "...", "remainingMs": 299000 }

帶 quoteId 與 x-user-id 建單,回付款網址(詳見)。渠道報價只是參考匯率;要自訂給客戶的價,可再帶 customerRate(不帶=沿用報價;賣單 withdraw 的 quoteId 路徑 customerRate/fiatAmount 皆可,買單的 fiatAmount 只能搭配 channelId+crypto+currency+cryptoAmount 形狀):

bash
curl -X POST /api/v1/orders/topup \
  -H "x-api-key: $KEY" \
  -H "x-user-id: $USER_ID" \
  -H "Content-Type: application/json" \
  -d '{ "quoteId": "{試算回的報價單號}", "refId": "{貴司側冪等鍵}" }'

回應節錄(201):

json
{ "orderId": "...", "orderNo": "...", "fiatAmount": "365.20", "merchantTransactionUrl": "https://渠道付款頁/...", "channelOrderId": "渠道單號", "quoteId": "..." }

把客戶導向 merchantTransactionUrl 付款;不要快取或改寫這個網址。報價過期會回 409 QUOTE_EXPIRED,回應已附 newQuote:讓客戶確認新價後,直接用 newQuote.quoteId 重送建單即可,不必再打一次試算(範例)。

③ 收「訂單完成」通知(或查單)

客戶付完款、渠道回打後,支付中心會 POST 通知到步驟①填的網址,事件為 topup.completed(渠道端看到的同一件事叫 order.completed)。請用 HMAC 驗簽(header X-Stellabit-Signature,以原始 body 計算)確認來源再入帳。也可以主動查單:

bash
curl /api/v1/orders/{orderId} \
  -H "x-api-key: $KEY" \
  -H "x-user-id: $USER_ID"

回應節錄(200):

json
{ "order": { "id": "...", "orderNo": "...", "status": "completed", "cryptoAmount": "10", "fiatAmount": "365.20", "rate": "36.52", "referenceRate": "36.52", "customerRate": null, "channelOrderId": "渠道單號", "merchantTransactionUrl": "https://渠道付款頁/...", "completedAt": "2026-11-08T01:00:00.000Z" } }

上面只列商戶需要的欄位;實際回應另含內部欄位,可忽略。

入帳以 Webhook 為準,查單只用來補漏與畫面顯示(見 訂單狀態與查詢、重試與冪等)。

④ 提幣、餘額、流水

客戶餘額(詳見):

bash
curl /api/account/balance \
  -H "x-api-key: $KEY" \
  -H "x-user-id: $USER_ID"

回應節錄與欄位請見各節。

  • 客戶流水:見「客戶流水查詢」(#api-ledger);商戶錢包餘額:見「錢包餘額查詢」(#api-vault)
  • 提幣/劃轉(選用):見「商戶劃轉 API」(#api-transfer)與「劃轉前確認」(#transfer-confirm)

快速連結:客戶餘額・客戶流水・錢包餘額・商戶劃轉(提幣)

先用沙盒渠道試

還沒有真實渠道?用我們提供的沙盒渠道(一支可自己架的假渠道),十分鐘內就能把步驟①~③完整跑一遍:建商戶帳號、串接沙盒渠道、下單、模擬付款、看訂單完成。請看 參考 → 沙盒渠道(商戶上手教學)。

產品定位

SOHO Wallet 只是商戶系統中的系統部分:商戶利用 SOHO Wallet 建構完整的商戶系統,與支付渠道結合,向自己的客戶提供服務。支付中心是商戶自建的加密貨幣訂單撮合+記帳系統:替商戶把客戶的買賣幣需求對接到渠道(詢價、建單、通知渠道、收渠道回打確認),並記下每一筆帳。

  • 商戶自建 UI 為主:客戶一律經商戶自己的系統進來,介面由商戶自行設計;支付中心提供 API(渠道列表、試算、建單、查單、Webhook)。
  • 沒有公開看板:不存在讓客戶直接瀏覽渠道、比價、下單的公開頁面;渠道與價格只透過商戶系統呼叫 API 取得。
  • 不經手法幣:法幣由客戶直接付給渠道(在渠道自己的付款頁);支付中心沒有收款帳戶、不代收代付、不做資金清分。
  • 不碰私鑰:只記帳與下指令,不持有、不保管任何人的私鑰;幣在商戶自己的錢包裡凍結與劃轉。

四個角色

角色說明
商戶交易平台(對接方)。有錢包、有商戶後台;以 API Key 呼叫本文件的 API(API 中稱 platform)。
渠道支付渠道,有自己的系統與付款頁;不登入商戶後台,也沒有 API Key 可呼叫商戶 API,只有一組只能回打的機器憑證(渠道 Key+渠道 Secret)。API 中稱 merchant。
客戶商戶的終端用戶,以商戶自己的客戶 ID 識別(API 中稱 platformUserId)。
支付中心本系統:向渠道詢價、建單、通知渠道、驗證回打並劃帳、以 Webhook 通知商戶。

三方語境(示意圖):客戶/商戶系統/支付渠道。商戶系統=商戶+支付中心,不含渠道;商戶在支付中心填寫渠道資訊,就是在串接支付渠道。

本文件怎麼讀

  • 商戶工程師:依序讀「開始」,再讀「商戶系統對接(主線)」。
  • 渠道工程師:直接讀「渠道對接規格」一頁,內含渠道需實作的三個端點與簽章規則。
  • 想用現成介面:「參考」中的 Widget 為參考實作,非必要。

開戶與取得 API 金鑰

  1. 1前往 開戶頁 開戶(免審核,開戶即有錢包)。
  2. 2登入商戶後台,進入 /console/integration(對接設定),自助產生 API Key;API Key 只顯示一次,請保存在商戶後端。
  3. 3同一頁設定接收通知的 Webhook URL,並可發送測試推送(見「Webhook 通知」)。
  4. 4(選用)在同一頁設定 API Key 的 IP 白名單(見「IP 白名單」)。

⚠️ API Key 安全

API Key 等同商戶全部客戶的操作權限,只能放在商戶後端;瀏覽器端請使用短效期的客戶 Token(見「總覽與認證」)。

認證方式與請求標頭詳見「商戶系統對接 → 總覽與認證」。

接第一個渠道

商戶要有至少一個「上工中」的渠道,客戶才有得選。渠道由商戶在後台替渠道建立與維護(渠道本身不登入後台)。

  1. 1到 /console/channels/new 選「系統型渠道」(渠道有自己的系統;類型建立後不能切換)。
  2. 2依設定精靈六步完成:基本資料 → 渠道給的東西(詢價網址、建單網址、通知網址,必要時欄位映射)→ 手續費(選填:一個費用 %,正=多收、負=讓利)→ 測試連線(詢價+建單) → 憑證與資料卡 → 上線。
  3. 3「憑證與資料卡」會產生渠道 Key+渠道 Secret(只顯示一次)與 Webhook Secret,連同「渠道對接規格」一頁一併交給渠道的技術人員。
  4. 4渠道完成實作後,在後台按「測試連線」(test-quote)與「回打測試」(test-callback),全部通過再上線。

渠道沒有系統、由商戶手動維護報價與確認收款的「人工報價渠道」另走 /console/channels/new/manual,屬參考中的「人工報價牌」附錄,與主線完全分開。

不想看文字?支付流程圖與各欄位的白話說明也在 /console/channels/flow。

渠道需要實作什麼,見「渠道對接規格」。

十步支付流程

三方:客戶/商戶系統/支付渠道,其中商戶系統=商戶+支付中心(不含渠道)。流程分兩張圖:先看示意圖掌握全貌,需要實作時再看開發圖。兩張都是通用流程(不綁定特定渠道),之下為文字版逐步說明。

示意圖(三泳道:客戶/商戶系統/支付渠道)

給產品、營運與初次接觸的人:一眼看懂一筆單從探價、下單、付款到回打確認怎麼走。支付中心在商戶系統內運作,所以不單獨畫成一條泳道。

客戶商戶系統SOHO Wallet(支付中心)在商戶系統內運作支付渠道① 商戶系統向各渠道探價渠道回參考匯率② 客戶選渠道、輸入金額③ 商戶系統向渠道詢參考匯率渠道回「參考匯率」+有效期(只是參考)商戶定客戶匯率/法幣數額(依渠道手續費設定或每筆指定,手續費≤上限)(支付中心)客戶匯率+法幣數額+有效期③ 客戶確認④ 商戶系統建單並凍結錢包(支付中心)④ 向渠道建單(法幣數額=商戶定)渠道回付款網址+渠道單號⑤ 商戶系統導客戶前往付款網址⑥ 客戶付款、渠道收款⑦ 渠道回打商戶系統(我方單號+渠道單號)⑧ 商戶系統核對金額、劃帳給客戶(支付中心)

開發圖(四泳道:客戶/商戶/支付中心/支付渠道)

給工程師:把商戶系統拆成「商戶」與「支付中心」兩條泳道,標出每一步呼叫的端點、各設定欄位用在哪、錯誤分支與渠道單號(channelOrderId)的流向。

時間由上往下。實線=呼叫,虛線=回應/通知。灰色圓點為該步驟用到的設定欄位。

  1. ① 商戶 → 支付中心

    商戶向支付中心取渠道列表(含參考匯率)

  2. ① 支付中心 → 渠道

    支付中心向各渠道探參考匯率(快取 45 秒),渠道回參考匯率

  3. ② 客戶 → 商戶

    客戶選渠道、輸入金額

  4. ③ 商戶 → 支付中心

    商戶向支付中心試算

  5. ③ 支付中心 → 渠道

    支付中心向渠道詢價,渠道回「參考匯率」(含有效期);支付中心回商戶參考匯率+報價單號+有效期

  6. ③ 商戶

    商戶自訂客戶匯率或直接定法幣數額(與參考匯率的差距須在手續費上限內)

    依渠道手續費設定或每筆指定;渠道只收法幣數額,客戶匯率不會送給渠道

  7. ④ 客戶 → 商戶

    客戶確認,商戶帶報價單號+客戶匯率或法幣數額下單

    報價過期→回新參考匯率,客戶再確認一次

  8. ⑤ 支付中心

    建單並凍結商戶錢包

  9. ⑤ 支付中心 → 渠道

    支付中心向渠道建單(法幣數額=商戶定;同步 POST 建單網址,8 秒內回應,帶簽章與 Idempotency-Key)

    失敗或逾時:解凍商戶錢包,回商戶 503 CHANNEL_CREATE_FAILED

  10. ⑥ 渠道 ⇢ 支付中心

    渠道回付款網址(+渠道單號);支付中心回訂單給商戶(單號+付款網址)

    商戶把客戶導向該付款網址(放在 merchantTransactionUrl,可能一次性、有時效)

  11. ⑥ 商戶 ⇢ 客戶

    商戶導客戶前往付款網址

  12. ⑦ 客戶 → 渠道

    客戶開啟付款網址付款、渠道收款

  13. ⑧ 渠道 → 支付中心

    渠道回打支付中心(帶我方單號+渠道單號)

  14. ⑨ 支付中心 ⇢ 商戶

    核對金額、劃帳;⑩ 通知商戶(含渠道單號)

    等值→完成 多付→完成並請渠道退差額 少付→作廢重建

渠道要做的三件事

1. 提供詢價介面(Quote URL)

照詢價介面規格實作,回價格與有效期

2. 提供建單介面(Create Order URL)

收支付中心簽章的建單請求,回付款網址(固定付款頁每次回同一個網址即可)

3. 完成後回打(Callback)

拿到渠道 Key+渠道 Secret 後,照說明文件的簽章規則回打支付中心

不經手資金、不碰私鑰

流程十步(四泳道:客戶/商戶/支付中心/渠道)

  1. 1商戶向支付中心取渠道列表(GET /api/v1/channels,含參考匯率 referenceRate)
  2. 2客戶在貴司介面選渠道、輸入金額
  3. 3商戶向支付中心試算(POST /api/v1/quotes)→ 支付中心向渠道詢價 → 回參考匯率+報價單號(quoteId)+有效期
  4. 4商戶自訂客戶匯率或法幣數額(可選;與參考匯率的價差須在上限 maxSpreadPct 內;未指定時依預設價差:每筆指定 > 渠道預設 > 商戶預設 > 參考價原價)。渠道只認法幣數額,建給渠道的 fiatAmount = 商戶定的數額;商戶與渠道的差額雙方自行結算,平台不介入
  5. 5客戶確認,商戶帶 quoteId 下單(POST /api/v1/orders/topup;可選帶 customerRate 自訂價;賣單 customerRate/fiatAmount 皆可)
  6. 6支付中心建單、凍結商戶錢包,並向渠道建單(同步 POST 建單網址,8 秒內回應)
  7. 7渠道回付款網址(+渠道單號 channelOrderId);支付中心回訂單給商戶(訂單編號+付款網址 merchantTransactionUrl+金額/有效期);商戶導客戶前往該付款網址
  8. 8客戶在付款網址付款,渠道收款
  9. 9渠道回打支付中心(渠道 Key+渠道 Secret 簽章;帶我方單號 orderId,建議同時帶渠道單號 channelOrderId)
  10. 10支付中心核對金額、劃帳,並以 Webhook 通知商戶(payload 含 channelOrderId;等值完成/多付完成並請渠道退差額/少付作廢重建)

報價過期的分支:下單時若報價已過期(或剩不到 30 秒),回 409 QUOTE_EXPIRED 並附上新報價; 商戶請把新價顯示給客戶,客戶再確認一次後用新的 quoteId 重新下單。支付中心不會自動用新價建單。

總覽與認證

Widget 本身是純前端介面——每一個畫面背後都是下列 REST API。 若貴司希望完全自訂 UI(不嵌 iframe),可直接對接這些端點, 功能與 Widget 完全對等:報價、買賣訂單、餘額流水、劃轉、鏈上充提、閃兌與2FA。

兩種認證方式

方式帶法適用場景
客戶 Token(Widget JWT)Authorization: Bearer {token}瀏覽器前端直接呼叫。Token 由貴司後端以 API Key 呼叫 POST /api/widget/token 簽發(見「客戶 Token API」章節)
商戶 API Key + 客戶 IDx-api-key + x-user-id僅限貴司後端 server-to-server 呼叫(API Key 絕不可出現在前端程式碼)

除非章節內另有註明,主線與選用各節的端點兩種認證方式皆可,回應格式相同。 例外:from_platform 劃轉僅限 API Key; 錢包帳號相關限制見下方。

Token 生命週期與過期處理

  • 有效期由簽發時的 expiresIn 決定:60–86400 秒,預設 3600 秒(1 小時)
  • 沒有 refresh 端點:Token 過期後任何呼叫會回 401(error: "Invalid token")
  • 前端收到 401 時,應向貴司後端重新取得一顱新 Token(重新呼叫 /api/widget/token 即可,簽發次數無限制)
  • Token 內已綁定商戶與客戶身分(tradingPlatformId + platformUserId),不可跨客戶共用

錢包帳號限制

HTTP錯誤碼行為
403VAULT_OWNER_TOKEN_FORBIDDEN不得為錢包帳號簽發 widget token(POST /api/widget/token 直接拒絕)
403VAULT_OWNER_LOGIN_REQUIRED錢包帳號的資金操作(提幣、劃轉、站內轉帳)僅限帳號本人登入執行,API Key + x-user-id 與 widget token 一律拒絕

⚠️ API Key 安全

商戶 API Key 等同於貴司全部客戶的操作權限,只能保存在貴司後端。 瀏覽器端一律使用短效期的客戶 Token。若已在 Portal 啟用 IP 白名單, 白名單只限制 API Key 認證路徑,客戶 Token 請求不受影響。

客戶 Token API

端點: POST /api/widget/token

Headers

Header必填說明
x-api-key✅商戶 API Key
Content-Type✅application/json

Request Body

欄位類型必填說明
userIdstring✅您商戶的客戶唯一 ID
expiresInnumber❌Token 有效期(秒),預設 3600,範圍 60–86400

Response

json
{
  "token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
  "expiresIn": 3600,
  "widgetUrl": "/widget/account?token=eyJ..."
}

完整範例

http
POST /api/widget/token
x-api-key: $KEY
Content-Type: application/json

{
  "userId": "您商戶的客戶唯一 ID",
  "expiresIn": 3600
}

渠道列表與參考價

客戶一律經貴司的商戶系統進來,介面由貴司自行設計;支付中心只保證 API 把「渠道列表+參考價 → 試算(報價單號+有效期)→ 下單帶報價單號 → 過期 409 新價」全部露出。 系統型渠道(已設定詢價 URL 的渠道)的價格由渠道即時提供,有效期以渠道回傳為準;支付中心只設兩道保護:報價最長保留 5 分鐘,下單時剩餘不到 30 秒視為過期。 人工報價牌(offers)與此主線完全分開,見「參考 → 附錄:人工報價牌(offers)」。

認證與其他商戶端點相同:商戶 x-api-key(列表之外的試算與查報價另需 x-user-id),或 Widget 簽發的客戶 Token。

① 渠道列表(含參考匯率)

GET /api/v1/channels?currency=THB[&type=buy][&crypto=USDT](currency 支援 THB / HKD / CNY / IDR):只列「上工中」的系統型渠道(站主審核通過、與貴商戶綁定有效、渠道自己標示上線中、詢價 URL 與憑證齊全、最近探價成功),買單依價格由低到高排序。 回應的 referenceRate(既有 rate 保留為別名)是支付中心以 100 USDT 定期向渠道探到的參考匯率(快取約 45 秒),僅供選渠道時參考;請在畫面標明「以 100 USDT 計」。渠道只認法幣數額,渠道報價不等於成交價:貴司可自訂給客戶的匯率或法幣數額(見「④ 下單」),貴司與渠道之間的差額由雙方自行結算,平台不介入。

bash
curl "/api/v1/channels?currency=THB&type=buy&crypto=USDT" \
  -H "x-api-key: $KEY" \
  -H "x-user-id: $USER_ID"

回應(200):

json
{
  "channels": [
    {
      "channelId": "渠道 ID",
      "name": "渠道名稱",
      "fiat": "THB",
      "type": "buy",
      "crypto": "USDT",
      "referenceRate": "36.52",
      "referenceAmount": "100",
      "referenceFiatAmount": "3652.00",
      "quotedAt": "2026-11-07T08:00:00.000Z",
      "stale": false
    }
  ],
  "referenceAmount": "100",
  "serverTime": "2026-11-07T08:00:20.000Z"
}

stale=true 表示這筆參考價是舊快取(剛好探價失敗前的最後一次結果);一律以 serverTime 判斷時間,不要用客戶裝置時間。

試算 quotes(取得報價單號)

③ 試算(取得報價單號)

POST /api/v1/quotes:客戶選好渠道並輸入金額後呼叫。cryptoAmount(幣數)與 fiatAmount(法幣金額)擇一; 帶法幣金額時,支付中心換算成幣數再向渠道詢價,回應的 fiatAmount/referenceRate 是渠道的參考報價(rate 為別名);客戶實付以貴司下單時確認的法幣數額為準(見「④ 下單」),requestedFiatAmount 是客戶輸入值,兩者可能差幾分,請明示給客戶。 可帶 Idempotency-Key header,60 秒內重送回同一張報價單。請勿在客戶打字時自動試算,改在按下「取得報價」時呼叫。

Header必填說明
x-api-key✅商戶 API Key
x-user-id✅您商戶的客戶唯一 ID(後端必帶,缺少回 400 Missing x-user-id)
Content-Type✅application/json
Idempotency-Key❌60 秒內重送回同一張報價單

下面的 curl 用環境變數,先貼上這兩行即可整行複製:

bash
export KEY=貼上您的商戶API_Key
export USER_ID=customer-001
bash
curl -X POST /api/v1/quotes \
  -H "x-api-key: $KEY" \
  -H "x-user-id: $USER_ID" \
  -H "Idempotency-Key: {本次試算唯一值}" \
  -H "Content-Type: application/json" \
  -d '{
    "channelId": "$CHANNEL_ID",
    "currency": "THB",
    "crypto": "USDT",
    "cryptoAmount": "250",
    "type": "buy",
    "network": "TRC20"
  }'

成功回應(201):

json
{
  "quoteId": "報價單號(下單要帶)",
  "channelId": "渠道 ID",
  "type": "buy",
  "crypto": "USDT",
  "currency": "THB",
  "network": "TRC20",
  "cryptoAmount": "250",
  "fiatAmount": "9130.00",
  "referenceRate": "36.52",
  "rate": "36.52",
  "requestedFiatAmount": null,
  "expiresAt": "2026-11-07T08:05:00.000Z",
  "remainingMs": 299000,
  "serverTime": "2026-11-07T08:00:01.000Z"
}

倒數請只用 remainingMs(不要用客戶裝置時間)。查詢既有報價單:GET /api/v1/quotes/:quoteId,回應同上並多 status(unused|used|expired)與 orderId(已下單才有)。

部署方可調的環境變數

變數預設說明
CHANNEL_REFERENCE_PROBE_AMOUNT100參考價探價用的 USDT 數量(全站固定)
REFERENCE_CACHE_TTL_SEC45參考價快取秒數
REFERENCE_PROBE_MAX_PER_MIN6每個渠道每分鐘最多探價次數
QUOTE_HOLD_MAX_MS300000報價最長保留時間(5 分鐘)
QUOTE_ORDER_MIN_REMAINING_MS30000下單時報價至少要剩的時間(30 秒)
QUOTE_RATE_LIMIT_USER_PER_MIN10每客戶每分鐘試算次數
QUOTE_RATE_LIMIT_PLATFORM_PER_MIN120每商戶每分鐘試算次數

渠道自己的上線/下線開關見 /guide「2.4a 渠道詢價介面」。商戶後台的渠道列表(GET /api/platform/channels)每筆多 isOnline 與 availability(online|offline|quote_paused)。

建單(帶 quoteId,取得 merchantTransactionUrl)

④ 帶報價單號下單

POST /api/v1/orders/topup:body 只需 quoteId(可加 refId);channelId、金額等欄位可省略,若帶了必須與報價單一致,否則 409 QUOTE_MISMATCH。 帶 quoteId 時不可同時帶 offerId(400 AMBIGUOUS_PRICE_SOURCE)。不帶 quoteId=v1.10 行為(下單時才詢價),原有對接不受影響。

自訂客戶匯率(v1.16,選填):渠道報價只是參考匯率。買單(topup)的 quoteId 路徑要自訂價,請帶 customerRate(給客戶的匯率,字串);fiatAmount(直接指定客戶要付的法幣數額,最多 2 位小數)只能搭配 channelId + crypto + currency + cryptoAmount 形狀使用,{quoteId, fiatAmount} 會回 400 AMBIGUOUS_PRICE_SOURCE。賣單(withdraw)的 quoteId 路徑 customerRate、fiatAmount 皆可(二擇一)。訂單 fiatAmount = 貴司定的數額,這就是建給渠道的數字(渠道不會收到客戶匯率,其 rate 欄位=參考匯率)。 兩個都不帶=套用預設價差(見下方;未設定則完全沿用渠道報價)。與參考匯率的價差不得超過商戶設定的上限 maxSpreadPct(預設 5%,見下方)。貴司與渠道之間的差額由雙方私下結算,平台不計算、不出報表。

  • customerRate 與 fiatAmount 同時帶且互相不一致 → 422 RATE_AMOUNT_CONFLICT
  • 買單 {quoteId, fiatAmount} → 400 AMBIGUOUS_PRICE_SOURCE(買單 quoteId 路徑請改帶 customerRate)
  • 同 refId 重送但 customerRate/fiatAmount 與原單不同 → 409 REF_ID_MISMATCH
  • 超過價差上限 → 422 SPREAD_EXCEEDS_LIMIT(hint 內含上限 maxSpreadPct)
  • 適用:POST /api/v1/orders/topup 與 POST /api/v1/orders/withdraw 的系統型渠道路徑(channelId/quoteId)
  • 訂單回應與 webhook 另帶 referenceRate(渠道報價)、customerRate(貴司給客戶的匯率;null=等於參考);rate=實際用來算 fiatAmount 的匯率

設定價差上限:GET /api/merchant/v1/me 回應含 maxSpreadPct;PUT /api/merchant/v1/max-spread-pct(scope integration:write,body { "maxSpreadPct": "5.00" },0–100、2 位小數)。商戶後台「對接設定」也能改(GET /api/platform/me/PUT /api/platform/max-spread-pct)。

手續費(預設價差,v1.16.0-rc3 單一數字):不想每筆都帶 customerRate,可設一個「費用 %」,系統依方向套用。渠道層:GET/PATCH /api/merchant/v1/channels/:id(scope channels:write;後台同 /api/platform/channels/:id)欄位 defaultSpreadPct;商戶層:GET /api/merchant/v1/me(及 /api/platform/me)的 platform 內同一欄,PUT /api/merchant/v1/default-spread(scope integration:write,非保險絲,後台 PUT /api/platform/default-spread),body { "defaultSpreadPct": "1.5" }。值為字串|null、最多 3 位小數;客戶買幣與賣幣的匯率都會朝對你有利的方向調整這個百分比;填負數=讓利(設 1.5 ⇒ 客戶買價=參考×1.015、客戶賣價=參考×0.985);渠道層 null=沿用商戶層。舊的 defaultSpreadBuyPct/defaultSpreadSellPct 已移除。優先序:請求帶的 customerRate/fiatAmount > 渠道預設 > 商戶預設 > 參考價原價。|值|> maxSpreadPct 回 422 SPREAD_EXCEEDS_LIMIT(extra.maxSpreadPct);maxSpreadPct 對最終 customerRate 一律生效。訂單與 webhook 回 appliedSpreadPct(字串,無="0",舊單 null;=設定值(帶符號),正=多收、負=讓利;請求自帶定價時買單=(customerRate−ref)/ref、賣單=(ref−customerRate)/ref;後台一律照原值顯示,不換算方向、不拆買賣;fiatAmount 取位依幣別:THB/HKD/CNY 2 位、IDR 0 位,half-up,IDR 帶小數的 fiatAmount 回 400 INVALID_AMOUNT_PRECISION)與 appliedSpreadSource(request|channel|merchant|none);詢價 POST /api/v1/quotes 與 GET /api/v1/channels 回套用預設價差後的 customerRate、appliedSpreadPct、appliedSpreadSource(channel|merchant|none),既有 rate/referenceRate 不變。

json
// 買單:渠道參考匯率 36.52,貴司給客戶 36.00(quoteId 路徑用 customerRate)
{ "quoteId": "{試算回的報價單號}", "customerRate": "36.00", "refId": "..." }
// 想直接指定法幣數額(買單):不帶 quoteId,改用 channelId+crypto+currency+cryptoAmount+fiatAmount
{ "channelId": "...", "crypto": "USDT", "currency": "THB", "cryptoAmount": "250", "fiatAmount": "9000.00", "refId": "..." }
bash
curl -X POST /api/v1/orders/topup \
  -H "x-api-key: $KEY" \
  -H "x-user-id: $USER_ID" \
  -H "Content-Type: application/json" \
  -d '{
    "quoteId": "{試算回的報價單號}",
    "refId": "貴司側冪等鍵(建議帶)"
  }'

成功回應(201):欄位同「買賣訂單」的系統型渠道下單回應(orderId、orderNo、fiatAmount、rate、referenceRate、customerRate、expiresAt、merchantTransactionUrl…),另多 quoteId。同一客戶重送已用過的報價單,回原訂單 200 並帶 idempotentHit: true。

報價過期:409 再確認

回應(409):

json
{
  "code": "QUOTE_EXPIRED",
  "message": "Price updated, please confirm again",
  "newQuote": {
    "quoteId": "新的報價單號",
    "rate": "36.60",
    "fiatAmount": "9150.00",
    "cryptoAmount": "250",
    "expiresAt": "2026-11-07T08:10:00.000Z",
    "remainingMs": 299000
  },
  "previousRate": "36.52",
  "serverTime": "2026-11-07T08:05:01.000Z"
}

請顯示「價格已更新:36.52 → 36.60」並讓客戶重新確認,確認後以 newQuote.quoteId 再呼叫一次下單。

回應已附 newQuote,不必再打一次試算:商戶直接拿 newQuote.quoteId 重送同一個建單請求即可(refId 沿用):

bash
# 上面 409 回應節錄:newQuote.quoteId = "新的報價單號"
curl -X POST /api/v1/orders/topup \
  -H "x-api-key: $KEY" \
  -H "x-user-id: $USER_ID" \
  -H "Content-Type: application/json" \
  -d '{ "quoteId": "{newQuote.quoteId}", "refId": "貴司側冪等鍵(與上次相同)" }'

⑤–⑩ 建單之後

  • 回應的 merchantTransactionUrl 是渠道建單回傳的付款網址(可能一次性、有時效),請直接導客戶過去付款,不要快取或改寫;渠道建單失敗會回 503 CHANNEL_CREATE_FAILED(單已取消、錢包已解凍,可重新試算再下單);;訂單狀態以 Webhook 或 GET /api/v1/orders/:id 為準
  • 客戶付款後由渠道回打支付中心;支付中心核對金額:等值→完成、多付→完成並標記 overpaid(差額由渠道退客戶)、少付→作廢並退回凍結(order.price_mismatch),請重新試算下單
  • 下單時商戶錢包不足會回 400 INSUFFICIENT_PLATFORM_BALANCE,報價單退回未使用,補足後可在有效期內再下單
  • 平台費(v1.14):站主若啟用,訂單完成時自動從商戶錢包扣,訂單物件的 platformFee 欄位為該筆平台費(decimal 字串);餘額不足記為欠繳,不擋已成交的單,充值後自動抵扣;有欠繳時建單門檻變成「餘額 ≥ 金額+欠繳」,提幣可用額也會扣掉欠繳

不經試算直接下單(v1.10 行為,channelId+cryptoAmount)

渠道若已在渠道詳情「對接設定」設定詢價 URL,即為系統型渠道:價格一律由渠道即時詢價提供(不帶 customerRate/fiatAmount 時,單上的 fiatAmount / rate 就是渠道的參考報價,支付中心不加點、不用報價牌;要自訂客戶匯率請帶 customerRate 或 fiatAmount,見「④ 下單」)。 貴司下單時不帶 offerId,改帶 channelId(可省略,省略時使用商戶後台「設定」的預設渠道)與 cryptoAmount。 支付中心不經手資金、不碰私鑰:法幣由客戶直接付給渠道,幣在貴商戶自己的錢包裡凍結、劃轉。

  • 判別規則:body 有 offerId → 舊路徑(人工線);沒有 offerId → 新路徑(channelId ?? 商戶預設渠道);兩者欄位同時帶 → 400 AMBIGUOUS_PRICE_SOURCE
  • 詢價失敗/逾時(3 秒)/被渠道拒絕/回應不合法 → 回錯誤(見「錯誤碼表」),不建單、不凍結錢包
  • 訂單過期時間 = min(渠道報價 expiresAt, 系統預設 30 分鐘);回應的 quoteExpiresAt 為渠道報價有效期限
  • 建議一律帶 refId(見下方冪等說明):詢價不重試,逾時重送請沿用同一個 refId

買單(topup)範例:

bash
curl -X POST /api/v1/orders/topup \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "channelId": "{渠道 ID,可省略→用預設渠道}",
    "crypto": "USDT",
    "network": "TRC20",
    "cryptoAmount": "100",
    "currency": "THB",
    "externalOrderId": "貴司系統單號(選填)",
    "refId": "貴司側冪等鍵(建議帶,≤128 字元)"
  }'

成功回應(201;冪等命中回 200 + idempotentHit:true):

json
{
  "success": true,
  "orderId": "....",
  "orderNo": "TP2611....",
  "status": "pending",
  "crypto": "USDT",
  "cryptoAmount": "100",
  "currency": "THB",
  "fiatAmount": "3150.00",
  "rate": "31.5",
  "referenceRate": "31.5",
  "customerRate": null,
  "expiresAt": "2026-11-07T08:30:00.000Z",
  "merchantTransactionUrl": "https://渠道交易頁?...&sig=...&ts=...",
  "overpaid": false,
  "overpaidAmount": null,
  "priceSource": "channel_quote",
  "channelOrderId": "渠道單號(渠道建單有回才有值,否則 null)",
  "channelQuoteId": "渠道報價單號",
  "platformFee": "平台費(USDT,decimal 字串;訂單完成時才計,未完成或站主未啟用為 "0")",
  "quoteExpiresAt": "2026-11-07T08:30:00.000Z"
}

賣單/提現(POST /api/v1/platform/withdraw,同樣不帶 offerId;quoteId 路徑 customerRate 或 fiatAmount 皆可、二擇一,其餘規則與錯誤碼同上)範例:

bash
curl -X POST /api/v1/platform/withdraw \
  -H "x-api-key: $KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "platformUserId": "您商戶的客戶唯一 ID",
    "channelId": "{渠道 ID,可省略→用預設渠道}",
    "crypto": "USDT",
    "cryptoAmount": "100",
    "currency": "THB",
    "refId": "貴司側冪等鍵(建議帶,≤128 字元)"
  }'

成功回應(201):

json
{
  "success": true,
  "orderId": "....",
  "orderNo": "WD2611....",
  "status": "pending",
  "crypto": "USDT",
  "cryptoAmount": "100",
  "currency": "THB",
  "fiatAmount": "3140.00",
  "rate": "31.4",
  "expiresAt": "2026-11-07T08:30:00.000Z",
  "merchantTransactionUrl": "https://渠道交易頁?...&sig=...&ts=...",
  "overpaid": false,
  "overpaidAmount": null,
  "priceSource": "channel_quote",
  "channelOrderId": "渠道單號(渠道建單有回才有值,否則 null)",
  "channelQuoteId": "渠道報價單號",
  "platformFee": "平台費(USDT,decimal 字串;訂單完成時才計,未完成或站主未啟用為 "0")",
  "quoteExpiresAt": "2026-11-07T08:30:00.000Z"
}
新路徑參數型別必填說明
channelIdstring (uuid)否系統型渠道;省略 → 商戶預設渠道(後台「設定」);兩者皆無 → 400 CHANNEL_REQUIRED
cryptoAmountstring(decimal)是要買/賣的幣數(字串,數字亦收;精度超過幣種上限 → 400 INVALID_AMOUNT_PRECISION)
crypto / network / currencystringcrypto、currency 建議帶crypto 例 USDT;network 例 TRC20;currency 例 THB(未帶時用渠道預設)
externalOrderIdstring ≤128否貴司系統單號,透傳給渠道詢價
refIdstring ≤128否(建議帶)冪等鍵:同一 refId 重送回原單 + idempotentHit:true,不重複建單、不重複凍結(買單/提現皆適用);同 refId 但 customerRate/fiatAmount 與原單不同 → 409 REF_ID_MISMATCH

⚠️ offerId 路徑=人工線專用(報價牌)

上方使用 offerId 的「建立買單/賣單」路徑保留給既有人工線(商戶後台按鈕確認、不做金額比對),行為不變。 若 offerId 指向系統型渠道的報價牌 → 422 OFFER_CHANNEL_REQUIRES_QUOTE,請改用上述 channelId+cryptoAmount 新路徑; GET /api/v1/offers 也不列出系統型渠道的報價牌。系統型渠道的訂單只由渠道回打確認,商戶後台人工確認會回 422 MANUAL_CONFIRM_NOT_ALLOWED。

金額三分流(渠道回打確認時,以渠道回報的 fiatAmount 比對單上金額):等值 → 照常完成;多付 → 照單上金額完成並標記overpaid: true、overpaidAmount,差額由渠道退客戶(支付中心不經手資金);少付(或渠道回報的 cryptoAmount 與單上不符)→ 訂單進price_mismatch 終態、退回凍結,並發 order.price_mismatch 事件,請由貴司系統重新下單(新單、新 orderId,舊單不會復活)。 詳見「事件與 Payload」,渠道端規格見 /guide。

訂單狀態與查詢

訂單狀態機

狀態說明
pending已建單。買單:等待客戶付法幣;賣單:等待渠道付法幣
paid客戶已按「我已付款」(僅買單),等待渠道確認收款
confirming(舊版相容狀態)現行流程渠道確認後直接由 pending / paid 翻為 completed,新訂單不會進入此狀態;前端仍應容錯處理
completed完成(終態)。同時發送 topup.completed / withdraw.completed Webhook。系統型渠道單若渠道多付,照單上金額完成並帶 overpaid: true / overpaidAmount(差額由渠道退客戶)
failed失敗(終態)
cancelled已取消(終態)。買單逾時 30 分鐘未付款會自動取消並退回凍結資金
price_mismatch價差作廢(終態,僅系統型渠道單):渠道回打的實收金額少於單上、或幣量與單上不符,訂單作廢並退回凍結;同時發送 order.price_mismatch Webhook,請重新下單

查詢訂單:GET /api/v1/orders/:id

bash
curl /api/v1/orders/{orderId} \
  -H "Authorization: Bearer $TOKEN"

回應為 { "order": { ... } }, 只能查自己的訂單,否則 404。商戶常用欄位如下:

json
{
  "order": {
    "id": "訂單 ID",
    "orderNo": "訂單編號",
    "type": "buy",
    "status": "completed",
    "crypto": "USDT",
    "cryptoAmount": "250",
    "currency": "THB",
    "fiatAmount": "9130.00",
    "rate": "36.52",
    "referenceRate": "36.52",
    "customerRate": null,
    "channelOrderId": "渠道單號",
    "platformFee": "0.70000000",
    "merchantTransactionUrl": "https://渠道付款頁/...",
    "expiresAt": "2026-11-08T01:30:00.000Z",
    "completedAt": "2026-11-08T01:10:00.000Z",
    "createdAt": "2026-11-08T01:00:00.000Z"
  }
}

回應另含內部欄位,商戶可忽略,不需解析。

輪詢與 Webhook 搭配建議

  • 前端:以 3–5 秒間隔輪詢 GET /api/v1/orders/:id,直到狀態進入 completed / failed / cancelled 終態(Widget 內建頁面使用 4 秒)
  • 後端入帳:一律以 topup.completed / withdraw.completed Webhook 為準(見「事件與 Payload」),前端輪詢結果僅供 UI 展示,不應作為入帳依據
  • 漏收 Webhook 時可用 GET /api/platform/webhook-logs 補漏對帳

Webhook 通知:事件與 Payload

訂單狀態變更、鏈上充幣到帳、鏈上提幣狀態變更、帳戶劃轉或錢包餘額不足時,系統會向您在 Portal 設定的 Webhook URL 發送 POST 請求(JSON),通知對應狀態。 所有請求均帶 HMAC-SHA256 簽名(見下方「簽名驗證」),並在失敗時自動重試(見「重試與冪等」)。

請求 Headers

Header說明
Content-Typeapplication/json
X-Platform-Id您的商戶 ID
X-Event事件類型(同 body 中的 event,僅供參考;程式判斷請以 body 的 event 為準)
X-Stellabit-SignatureHMAC-SHA256 簽名,格式 sha256=<hex>

訂單事件 Payload

json
{
  "eventId": "550e8400-e29b-41d4-a716-446655440000",
  "event": "topup.completed",
  "orderId": "uuid",
  "orderNo": "訂單編號",
  "platformUserId": "您的客戶 ID",
  "crypto": "USDT",
  "cryptoAmount": "100.000000",
  "currency": "THB",
  "fiatAmount": "3500.00",
  "channelOrderId": "渠道單號(系統型渠道單,渠道建單時有回才有值,否則 null)",
  "channelQuoteId": "渠道報價單號(系統型渠道單才有值,否則 null)",
  "status": "completed",
  "timestamp": "2026-01-01T00:00:00.000Z"
}

鏈上充幣事件 Payload

json
{
  "eventId": "550e8400-e29b-41d4-a716-446655440001",
  "event": "wallet.deposit.completed",
  "depositId": "uuid",
  "platformUserId": "您的客戶 ID",
  "crypto": "USDT",
  "amount": "100.00000000",
  "tronTxHash": "鏈上交易 hash(僅 TRC-20 且有值時出現;BEP20 事件不帶此鍵)",
  "chain": "TRC20",
  "txHash": "鏈無關交易 hash(新增;見「BEP20 充值」章節)",
  "timestamp": "2026-01-01T00:00:00.000Z"
}
  • 多鏈充值:payload 新增 chain + txHash 欄位(加法);tronTxHash 保留,TRC-20 事件照舊有值才出現、BEP20 / ARB 事件不帶此鍵,詳見「多鏈充值(BEP20 / ARB)」章節
  • amount 一律為 8 位小數字串(如 "100.00000000"),與 wallet.withdraw.* 事件同格式

鏈上提幣事件 Payload

鏈上提幣(POST /api/wallet/withdraw)完成、失敗或審核駁回時推送, 三個事件共用同一份 payload 結構(僅 event / status / hash 欄位不同):

json
{
  "eventId": "550e8400-e29b-41d4-a716-446655440002",
  "event": "wallet.withdraw.completed",
  "withdrawId": "uuid(即提幣單 id,同 POST /api/wallet/withdraw 回應的 id)",
  "platformUserId": "您的客戶 ID",
  "crypto": "USDT",
  "amount": "100.00000000",
  "fee": "1.00000000",
  "netAmount": "100.00000000",
  "toAddress": "T....(提幣目標地址)",
  "tronTxHash": "鏈上交易 hash(completed 必帶;failed 若已送鏈才帶;rejected 無)",
  "chain": "TRC20",
  "txHash": "鏈無關交易 hash(新增;見「多鏈提幣」章節)",
  "status": "completed",
  "timestamp": "2026-01-01T00:00:00.000Z"
}
  • 多鏈提幣:payload 新增 chain + txHash 欄位(加法);tronTxHash 保留,TRC20 事件照舊填、BEP20 / ARB 事件為 null,詳見「多鏈提幣(BEP20 / ARB)」章節
  • wallet.withdraw.completed:交易已鏈上確認,status=completed,交易 hash 必帶(TRC20 填 tronTxHash + txHash;BEP20 / ARB 僅填 txHash)
  • wallet.withdraw.failed:送鏈失敗或鏈上執行失敗(如 revert),status=failed
  • wallet.withdraw.rejected:大額提幣人工審核駁回,status=rejected,金額(含手續費)已退回客戶鏈上錢包餘額
  • 審核通過(approve)不發事件——提幣只是進入發送佇列,最終結果以 completed / failed 為準

帳戶劃轉事件 Payload

客戶劃回商戶(account.transfer.to_platform,資金已入您的錢包):

json
{
  "eventId": "550e8400-e29b-41d4-a716-446655440003",
  "event": "account.transfer.to_platform",
  "platformUserId": "您的客戶 ID",
  "crypto": "USDT",
  "amount": "100.000000",
  "originalCrypto": "USDT",
  "originalAmount": "100.000000",
  "refId": null,
  "timestamp": "2026-01-01T00:00:00.000Z"
}

錢包餘額不足(account.vault.insufficient_balance,該筆 from_platform 劃轉已被拒絕,請儲值錢包後重試):

json
{
  "eventId": "550e8400-e29b-41d4-a716-446655440004",
  "event": "account.vault.insufficient_balance",
  "platformUserId": "您的客戶 ID",
  "crypto": "USDT",
  "amount": "100",
  "vaultBalance": "20.00000000",
  "refId": null,
  "timestamp": "2026-01-01T00:00:00.000Z"
}

事件類型

事件說明
topup.confirmed渠道已確認收到法幣,客戶已入帳
topup.completed充值訂單完成。含 overpaid(boolean)、overpaidAmount(string|null):系統型渠道單若渠道多付,照單上金額完成並標 overpaid=true、overpaidAmount=差額(法幣,由渠道退客戶);無多付為 false/null
topup.failed充值訂單失敗
withdraw.processing(已棄用)舊版逐單鏈上撥款事件;訂單錢包化 v3 起不再發送
withdraw.completed渠道已付款給客戶,提現完成(客戶凍結金額已劃入您的錢包)。同樣含 overpaid/overpaidAmount(渠道多付給客戶時,差額為渠道與客戶之間的事)
withdraw.failed提現訂單失敗
order.price_mismatch價差作廢(系統型渠道單):渠道回打實收少於單上(reason=underpaid)或幣量不符(reason=crypto_mismatch),訂單進 price_mismatch 終態並已退回凍結;請重新下單。payload 見下方範例
order.expired訂單逾時/取消(escrow 已自動解凍:買單回錢包、賣單退回客戶)
wallet.deposit.completed鏈上充幣到帳
wallet.withdraw.completed鏈上提幣完成(交易已上鏈確認,帶 chain + txHash;TRC20 另帶 tronTxHash)
wallet.withdraw.failed鏈上提幣失敗(送鏈失敗或鏈上 revert)
wallet.withdraw.rejected鏈上提幣審核駁回(金額已退回客戶鏈上錢包)
account.transfer.to_platform客戶將資金劃回商戶(已入您的錢包),請在您系統為客戶入帳
account.vault.insufficient_balance錢包可用餘額不足:from_platform 劃轉被拒,或 C2C 買單建單被拒(訂單錢包化 v3,refId=訂單 ID),請儘速儲值錢包

每個事件 body 一定含 event、eventId、timestamp 三個欄位。 另有 account.transfer.confirm: 它是「劃轉前確認」的同步請求(需貴司即時回應允許/拒絕,見該章節),不屬於上表的非同步事件、也不重試。

v1.16 起,訂單類事件(topup.*/withdraw.*/order.*)的 payload 新增 referenceRate(渠道報價,字串或 null)與customerRate(貴司給客戶的匯率;null=等於參考);rate=實際用來算 fiatAmount 的匯率,其他欄位不變。 範例:"fiatAmount": "9000.00", "rate": "36.00", "referenceRate": "36.52", "customerRate": "36.00"。

order.price_mismatch Payload 與 overpaid 說明

json
{
  "eventId": "550e8400-e29b-41d4-a716-446655440001",
  "event": "order.price_mismatch",
  "orderId": "....",
  "orderNo": "TP2611....",
  "type": "buy",
  "platformUserId": "您商戶的客戶唯一 ID",
  "crypto": "USDT",
  "cryptoAmount": "100",
  "currency": "THB",
  "fiatAmount": "3150.00",
  "referenceRate": "31.5",
  "customerRate": null,
  "status": "price_mismatch",
  "reason": "underpaid",
  "expectedFiatAmount": "3150.00",
  "receivedFiatAmount": "3000.00",
  "refundedAt": "2026-11-07T08:12:00.000Z",
  "timestamp": "2026-11-07T08:12:00.000Z"
}

reason 為 underpaid(少付)或 crypto_mismatch(渠道回報幣量與單上不符;此時另帶 expectedCryptoAmount/receivedCryptoAmount)。 收到後請重新下單(新單、新 orderId);客戶若已在渠道付款,渠道會以新單 id 回打確認。 多付時不另發事件:topup.completed/withdraw.completed 的 payload 帶 "overpaid": true 與 "overpaidAmount": "50.00",差額由渠道退客戶。

同一筆訂單的狀態變化,系統也會向渠道的 Webhook URL 發送 order.created/order.completed/order.cancelled(渠道事件;多付時 completed 帶 overpaid/overpaidAmount 與退差額提示,少付時 cancelled 的 reason 為 underpaid 或 crypto_mismatch),規格見 /guide。

💡 回應要求

收到通知後請回應 HTTP 2xx(10 秒內),否則視為發送失敗並觸發自動重試。 建議收到後立即回 200,較重的業務處理放到非同步執行。

來源 IP 與白名單

Webhook 由本站 API 伺服器直接發出(無代理、無第三方轉發),出口 IP 固定。 基於安全考量,具體 IP 不在公開文件列出,貴司開戶後可向站主索取, 加入防火牆白名單作為額外防護(建議與簽名驗證並用,而非取代)。 若日後出口 IP 有變更,會提前通知所有商戶。

簽名驗證

每個 Webhook 請求都帶有 X-Stellabit-Signature header,用於驗證請求確實來自 SOHO Wallet 且內容未被竄改。簽名以您的 API Key(商戶後台自助產生的那把)作為共享密鑰,對「原始 request body 字串」計算 HMAC-SHA256:

text
X-Stellabit-Signature: sha256=<hex(HMAC_SHA256(apiKey, rawBody))>

⚠️ 務必使用原始 body 驗簽

簽名是對「原始 JSON 字串」計算的。請在 JSON 解析之前取得原始 body 進行驗簽——若先 parse 再 stringify,欄位順序或空白差異會導致驗簽失敗。 比對簽名時請使用 timing-safe 比較函式,避免時序攻擊。

Node.js(Express)範例

javascript
const crypto = require('crypto')
const express = require('express')

const app = express()

// 用 express.raw 取得原始 body(勿先經過 express.json)
app.post('/webhook', express.raw({ type: 'application/json' }), (req, res) => {
  const rawBody = req.body.toString('utf8')
  const signature = req.headers['x-stellabit-signature'] || ''

  const expected = 'sha256=' +
    crypto.createHmac('sha256', process.env.API_KEY)
      .update(rawBody)
      .digest('hex')

  // timing-safe 比較,避免時序攻擊
  const valid =
    signature.length === expected.length &&
    crypto.timingSafeEqual(Buffer.from(signature), Buffer.from(expected))

  if (!valid) {
    return res.status(401).send('invalid signature')
  }

  const payload = JSON.parse(rawBody)

  // 以 eventId 去重(見「重試與冪等」)
  // if (alreadyProcessed(payload.eventId)) return res.status(200).send('ok')

  // 快速回 200,重的處理放非同步
  res.status(200).send('ok')
  // processEventAsync(payload)
})

app.listen(8080)

Python 範例

python
import hmac
import hashlib

def verify_signature(api_key: str, raw_body: bytes, signature_header: str) -> bool:
    expected = 'sha256=' + hmac.new(
        api_key.encode(), raw_body, hashlib.sha256
    ).hexdigest()
    # hmac.compare_digest 為 timing-safe 比較
    return hmac.compare_digest(signature_header, expected)

💡 渠道回打改用「渠道 Key+簽章」(v1.9.0 起)

渠道系統回打確認:POST /api/v1/callback/topup-confirm 與POST /api/v1/callback/withdraw-fiat-sent, 須帶渠道 Key(x-api-key)與 X-Channel-Timestamp/X-Channel-Nonce/X-Channel-Signature 簽章;商戶 API Key 不再受理。 憑證由商戶在後台渠道詳情「對接設定」分頁代渠道產生並一次性顯示。商戶自己確認訂單請用後台「已收到法幣/已付法幣」按鈕。 完整規格見 /guide 渠道回打確認。

重試與冪等

Webhook 發送失敗(回應非 2xx、逾時 10 秒、或連線錯誤)時,系統會自動重試, 依下表間隔退避,最多共 8 次嘗試;全部失敗後標記為最終失敗、不再重送。

重試間隔

嘗試次數距上次發送間隔
第 1 次事件發生時立即發送
第 2 次1 分鐘
第 3 次5 分鐘
第 4 次15 分鐘
第 5 次1 小時
第 6 次3 小時
第 7 次6 小時
第 8 次12 小時

以 eventId 去重(冪等處理)

每個事件的 payload 都含唯一的 eventId(UUID),重試時 payload 內容與首次發送完全相同(含 eventId 與 timestamp),簽名對同一 body 重新計算,驗簽方式不變。

由於網路逾時等情況下您可能已成功處理但支付中心未收到 2xx,同一事件可能重複送達。 請務必以 eventId 做冪等處理:

  1. 1收到通知後,先查詢該 eventId 是否已處理過
  2. 2已處理過 → 直接回 200,不重複執行業務邏輯
  3. 3未處理過 → 記錄 eventId 並執行業務處理(建議與記錄同一交易內完成)

💡 為什麼不能只靠 refId 去重

refId 是發起方帶入的業務層冪等 ID,僅在以 API 發起劃轉時才有值;account.transfer.to_platform 事件若為客戶在 Widget 介面自行發起,payload 的 refId 為 null。 因此接收端請一律以 eventId 作為去重主鍵。

⚠️ 快速回應

發送逾時為 10 秒。請在收到請求後儘快回 200(驗簽 + 去重檢查即可), 將較重的業務處理(入帳、通知客戶等)放到非同步佇列執行,避免處理過久被判定失敗而觸發不必要的重試。

測試 Webhook

設定好 Webhook URL 後,可透過測試端點主動觸發一筆測試通知,驗證接收端與驗簽邏輯是否正確。 測試發送為同步直發(不入佇列、不重試),呼叫後立即回傳接收端的 HTTP 狀態與回應內容。

端點: POST /api/platform/webhook-test

請求範例

bash
curl -X POST /api/platform/webhook-test \
  -H "x-api-key: $KEY"

您的接收端會收到

json
{
  "eventId": "550e8400-e29b-41d4-a716-446655440002",
  "event": "test",
  "test": true,
  "timestamp": "2026-01-01T00:00:00.000Z",
  "platformId": "您的商戶 ID"
}

測試請求同樣帶 X-Stellabit-Signature 簽名,可直接用來驗證驗簽程式碼。

回應

json
{
  "success": true,
  "responseStatus": 200,
  "responseBody": "ok"
}

success 表示接收端是否回應 2xx;responseBody 為接收端回應內容(最多 500 字元),可協助排查驗簽失敗等問題。

Webhook 發送紀錄查詢

端點: GET /api/platform/webhook-logs
查詢本站向貴司端點發送 Webhook 的歷次紀錄,包含事件 payload、接收端 HTTP 狀態、 是否成功與重試狀態。若貴司接收端曾短暫故障,可用此端點補漏對帳—— 撈出失敗或漏收的事件重新入帳。

Headers

Header必填說明
x-api-key✅商戶 API Key

每筆紀錄包含

  • 事件類型與完整 payload(含 eventId,可與貴司已處理的事件比對)
  • 接收端回應的 HTTP 狀態碼
  • 發送成功與否、重試狀態(嘗試次數)
  • 發送時間

請求範例

bash
curl /api/platform/webhook-logs \
  -H "x-api-key: $KEY"

客戶餘額查詢

端點: GET /api/account/balance
查詢指定客戶在本站的即時資金帳戶餘額。客戶只有一份站內餘額(資金帳戶):買賣訂單、劃轉、閃兌與鏈上充提(TRC-20 / BEP20 / ARB)都以它為入帳/扣帳主體,不分鏈。Widget 餘額頁顯示的即為此餘額。

兩種呼叫方式

方式Headers說明
① 商戶伺服器x-api-key + x-user-id商戶 API Key;x-user-id 為您商戶的客戶唯一 ID
② 客戶前端Authorization: Bearer 客戶 Token以客戶 Token 直接呼叫,查詢該客戶自己的餘額

請求範例

① 商戶伺服器(x-api-key + x-user-id)

bash
curl /api/account/balance \
  -H "x-api-key: $KEY" \
  -H "x-user-id: $USER_ID"

② 客戶前端(Authorization: Bearer 客戶 Token)

bash
curl /api/account/balance \
  -H "Authorization: Bearer $TOKEN"

回應

json
{
  "balances": [
    { "crypto": "USDT", "balance": "1250.00000000", "lockedBalance": "100.00000000" }
  ]
}

lockedBalance 為進行中賣單等凍結中的金額,不可動用。

x-user-id 與簽 token 時傳入的 userId、Webhook payload 中的 platformUserId 為同一個值,原樣對應、不做任何轉換。

同值端點:GET /api/wallet/balance

/api/wallet/balance 與上述端點同源同值(歷史上曾分別對應帳本與錢包,v1.6.0 起已收斂),回應欄位名保留相容,僅多回 pendingWithdrawal(處理中 pending / pending_review / processing 的鏈上提幣總額)。

json
{
  "balances": [
    { "crypto": "USDT", "balance": "500.00000000", "pendingWithdrawal": "0.00000000" }
  ]
}

客戶流水查詢

端點: GET /api/account/ledger
查詢指定客戶的資金流水(含劃轉紀錄),適合輪詢對帳、核對單筆劃轉是否入帳。

兩種呼叫方式

方式Headers說明
① 商戶伺服器x-api-key + x-user-id商戶 API Key;x-user-id 為您商戶的客戶唯一 ID(與簽 token 時的 userId 相同)
② 客戶前端Authorization: Bearer 客戶 Token以客戶 Token 直接呼叫,適合自訂 UI 展示流水;僅能查詢該客戶自己的流水

Query 參數

參數說明
page頁碼,預設 1
limit每頁筆數,上限 100
crypto幣種過濾(如 USDT)
source來源過濾(見下方來源類型)
direction方向過濾(收入 / 支出)

劃轉相關的來源類型

source說明
transfer_out客戶劃轉至商戶(to_platform)的流水
transfer_in商戶劃入客戶(from_platform)的流水

每筆流水的主要欄位

欄位說明
id流水唯一 ID
amount異動金額(decimal 字串)
balanceAfter異動後餘額(可核對餘額連續性)
refId發起劃轉時帶入的冪等 ID(客戶自行發起時為 null)
createdAt流水建立時間

請求範例

① 商戶伺服器(x-api-key + x-user-id)

bash
curl "/api/account/ledger?source=transfer_out&page=1&limit=50" \
  -H "x-api-key: $KEY" \
  -H "x-user-id: $USER_ID"

② 客戶前端(Authorization: Bearer 客戶 Token)

bash
curl "/api/account/ledger?page=1&limit=20" \
  -H "Authorization: Bearer $TOKEN"

錢包餘額查詢

端點: GET /api/platform/vault
查詢貴司商戶錢包的即時餘額,含凍結金額(如進行中訂單的 escrow 凍結)。 僅需 API Key,無需 x-user-id。API 路徑與回應欄位沿用舊名 vault(金庫=錢包),內容即商戶錢包餘額。

請求範例

bash
curl /api/platform/vault \
  -H "x-api-key: $KEY"

💡 建議定期監控

from_platform 劃轉會即時扣錢包可用餘額,餘額不足會直接拒絕(INSUFFICIENT_PLATFORM_BALANCE)。建議定期輪詢此端點監控水位,低於閾值時及早為錢包儲值。

商戶劃轉 API(預存制)

商戶採預存制:開戶時系統同時建立您的錢包, 免審核。您劃轉給客戶的資金一律從錢包餘額即時扣款, 請先為錢包儲值再開始劃轉。

錢包帳號

  • 儲值:以錢包帳號登入,走一般鏈上充幣流程(TRC-20 / BEP20 / ARB 充幣地址)即可為錢包加值
  • 提幣:僅限錢包帳號本人登入操作(需通過 2FA 驗證),API Key 無法發起錢包提幣
  • 客戶劃回商戶(to_platform)的資金會自動進入錢包餘額

商戶入帳(from_platform)

將資金從商戶錢包劃入指定客戶的資金帳戶。僅限您的後端以 API Key 發起—— 以客戶 JWT(含 Widget Token)呼叫會被拒絕(403)。系統在同一筆交易內原子性地 「扣錢包餘額 → 為客戶入帳」,錢包餘額不足時直接拒絕、不會產生部分入帳。

http
POST /api/account/transfer
x-api-key: $KEY
x-user-id: $USER_ID
Content-Type: application/json

{
  "direction": "from_platform",
  "crypto": "USDT",
  "amount": "100",
  "refId": "您系統的唯一交易 ID(選填,冪等用)",
  "note": "備註(選填)"
}

成功回應:

json
{
  "success": true,
  "direction": "from_platform",
  "crypto": "USDT",
  "amount": "100",
  "duplicate": false,
  "message": "已從商戶金庫劃入客戶資金帳戶"
}

💡 以 refId 冪等

建議每次劃轉帶上您系統的唯一交易 ID 作為 refId。 相同 refId 重複呼叫會回 duplicate: true 且不重複入帳,網路重試時不會造成重複劃轉。

錯誤碼

HTTP錯誤碼說明
403PLATFORM_API_KEY_REQUIREDfrom_platform 劃轉僅限商戶以 API Key 發起;客戶 JWT(含 Widget Token)呼叫會被拒絕
400INSUFFICIENT_PLATFORM_BALANCE商戶錢包餘額不足,回應含 vaultBalance / required,並同時發送錢包餘額不足 Webhook 通知。v1.14 起建單門檻為「可用餘額 ≥ 凍結金額+平台費欠繳」,有欠繳時 message 會註明(含平台費欠繳 N);充值後欠繳自動抵扣
400PLATFORM_VAULT_NOT_BOUND商戶尚未綁定錢包帳號,請聯繫站主完成綁定

錢包餘額不足時的回應範例:

json
{
  "error": "INSUFFICIENT_PLATFORM_BALANCE",
  "message": "商戶金庫餘額不足:目前 20.00000000,需要 100,請先儲值金庫帳戶",
  "vaultBalance": "20.00000000",
  "required": "100"
}

⚠️ 請維持錢包餘額充足

錢包餘額不足會導致劃轉即時失敗。系統會發送 account.vault.insufficient_balance Webhook 通知(見「事件與 Payload」),建議接收後立即為錢包儲值,並依需要重試原劃轉(帶相同 refId)。

客戶劃回商戶(to_platform)

客戶在 Widget(balance-hub)發起、需通過 2FA 驗證。資金會進入您的商戶錢包餘額, 並發送 account.transfer.to_platform Webhook 通知您在自己系統為該客戶入帳。

資金託管模式

商戶與客戶之間的「劃轉」是本站系統的內部帳本操作——不涉及鏈上交易、 即時完成、無鏈上手續費。客戶劃轉至貴商戶(to_platform)時,資金從該客戶的資金帳戶 劃入貴司在本站的商戶錢包帳戶;反向(from_platform)則由錢包即時扣款入客戶帳戶。

  • 劃轉 = 內部帳本異動:不上鏈、即時到帳、無鏈上手續費
  • 客戶劃轉至商戶的資金一律進入貴司的商戶錢包帳戶(錢包餘額即時增加)
  • 對應的鏈上資產(USDT,TRC-20 / BEP20 / ARB)由本站託管錢包統一持有;站內餘額不分鏈
  • 錢包餘額可由「錢包綁定帳號」登入後提幣至鏈上地址(需 2FA,API Key 無法發起錢包提幣)

💡 對帳建議

由於劃轉不產生鏈上交易,對帳請以本站提供的查詢 API 為準:錢包餘額(GET /api/platform/vault)、逐客戶流水(GET /api/account/ledger)與 Webhook 發送紀錄(GET /api/platform/webhook-logs),詳見下方各章節。

劃轉狀態模型與冪等

劃轉(雙向)是同步原子操作,沒有 pending 中間狀態, 也不存在「已扣款但失敗待退回」的情況,因此無需退回流程:

結果含義處理方式
HTTP 200 + success: true已完成入帳duplicate: true 表示同 refId 先前已成功,本次為冪等空操作,同樣視為成功
HTTP 4xx未發生任何資金異動(整筆交易回滾)可安全重試(帶相同 refId 不會重複入帳)

單筆狀態確認

帶相同 refId 重發同一請求——若回 duplicate: true 即代表該筆已成功;或透過「客戶流水查詢」(GET /api/account/ledger)核對流水。

⚠️ to_platform 事件的 refId 可能為 null

account.transfer.to_platform Webhook 的 refId 僅在以 API 發起劃轉時才有值;客戶在 Widget 介面自行發起的劃轉沒有 refId(為 null)。 此時請一律以 eventId 去重(見「重試與冪等」章節),勿以 refId 作為唯一去重鍵。

劃轉前確認(選用)

選用機制(opt-in):於商戶後台設定「劃轉前確認 URL」後,每筆客戶劃轉至您商戶(to_platform)執行前,系統會先同步 POST 詢問您的端點是否放行。 未設定(預設)則直接執行,行為與現在完全相同。適合需要即時風控(單筆限額、 名單檢查、客戶狀態驗證等)的商戶。

確認請求格式

系統對您設定的 URL 發出 POST 請求(同步、單次、不重試):

http
POST {您設定的劃轉前確認 URL}
Content-Type: application/json
X-Platform-Id: $PLATFORM_ID
X-Event: account.transfer.confirm
X-Stellabit-Signature: sha256=<hex(HMAC_SHA256(apiKey, rawBody))>

{
  "event": "account.transfer.confirm",
  "platformUserId": "您商戶的客戶唯一 ID",
  "crypto": "USDT",
  "amount": "100",
  "refId": null,
  "timestamp": "2026-01-01T00:00:00.000Z"
}

簽名與事件 Webhook 同一套:以您的 API Key 作共享密鑰,對原始 request body 計算 HMAC-SHA256(驗簽程式碼可與「簽名驗證」章節完全共用)。refId 僅在以 API 發起劃轉時才有值,客戶在 Widget 介面自行發起時為 null。

回應契約

請在 5 秒內回應 HTTP 2xx + JSON:

json
// 放行:劃轉照常執行
{ "accept": true }

// 拒絕:劃轉不執行,reason(選填)會顯示給客戶
{ "accept": false, "reason": "單筆金額超過上限" }
您的端點回應系統行為客戶看到的錯誤碼
2xx + {"accept":true}放行,執行原子劃轉並發送 to_platform Webhook—
2xx + {"accept":false}拒絕,劃轉不執行(客戶餘額零異動),reason 透傳給客戶TRANSFER_CONFIRM_REJECTED
逾時(>5 秒)/ 連線失敗 / 非 2xx / 格式不對一律拒絕(fail-closed),劃轉不執行(客戶餘額零異動)TRANSFER_CONFIRM_UNAVAILABLE

⚠️ Fail-closed:端點異常=全部劃轉被拒

本機制採保守設計:只要未在 5 秒內收到 2xx + {"accept":true},該筆劃轉一律不執行。若您的確認端點故障,所有客戶的 to_platform 劃轉都會失敗—— 請確保端點高可用並快速回應(建議只做輕量檢查);若不需要此機制, 在 Portal 清空該欄位即可回到直接執行。

💡 確認通過 ≠ 入帳依據

確認只是執行前的預授權。確認通過後系統才執行原子劃轉,並照常發送 account.transfer.to_platform Webhook——請勿在回應 accept:true 時就為客戶入帳,入帳一律以 Webhook 為準(以 eventId 去重,見「重試與冪等」)。極端情況下可能確認通過但劃轉未執行 (例如客戶餘額不足),此時不會有 Webhook、也不應入帳。

設定方式

於商戶後台(「Webhook 設定」區塊)填寫,或以 API 設定(僅接受 HTTPS;傳 null 清除、停用機制):

http
PUT /api/platform/transfer-confirm-url
x-api-key: $KEY
Content-Type: application/json

{ "transferConfirmUrl": "https://yourplatform.com/transfer-confirm" }

劃轉與站內轉帳

客戶劃回商戶:POST /api/account/transfer(to_platform)

客戶發起(客戶 Token 可呼叫),資金從客戶資金帳戶劃入貴商戶錢包, 並發送 account.transfer.to_platform Webhook 通知貴司入帳。若客戶已啟用 2FA,需先取得驗證碼並以 x-2fa-token header 帶入。

http
POST /api/account/transfer
Authorization: Bearer $TOKEN
x-2fa-token: {6 位驗證碼,客戶已啟用 2FA 時必填}
Content-Type: application/json

{
  "direction": "to_platform",
  "crypto": "USDT",
  "amount": "100",
  "refId": "貴司系統的唯一 ID(選填,冪等用)",
  "note": "備註(選填)"
}
HTTP錯誤碼說明
400TRANSFER_CONFIRM_REJECTED貴司設定了劃轉前確認 URL 且明確拒絕(回應含 reason),客戶餘額零異動
400TRANSFER_CONFIRM_UNAVAILABLE劃轉前確認連線失敗/逾時 → fail-closed 拒絕,客戶餘額零異動
400PLATFORM_VAULT_NOT_BOUND商戶尚未綁定錢包帳號
4032FA_REQUIRED / 2FA_INVALID客戶已啟用 2FA 但未帶/帶錯 x-2fa-token

商戶入帳:POST /api/account/transfer(from_platform)

僅限貴司後端以 API Key 發起——以客戶 Token 呼叫會回 403 PLATFORM_API_KEY_REQUIRED。 完整說明見「商戶劃轉 API」章節。

站內轉帳:POST /api/account/transfer/peer

同商戶客戶間即時轉帳(內部帳本操作,無鏈上手續費)。收款方以 Email 或客戶 ID 指定,兩者擇一必填。

http
POST /api/account/transfer/peer
Authorization: Bearer $TOKEN
Content-Type: application/json

{
  "toUserId": "收款方客戶 ID(或改用 toEmail)",
  "crypto": "USDT",
  "amount": "50",
  "note": "備註(選填)"
}
HTTP錯誤說明
404Recipient not found收款方不存在(toEmail 只能解析到同商戶已註冊 Email 的客戶)
400Cannot transfer to yourself不可轉給自己
400Transfer Failed餘額不足等,message 含具體原因

兩種劃轉都是內部帳本操作:即時完成、同一交易內原子執行,不會產生部分入帳。 建議帶 refId 做冪等(to_platform / from_platform),重試時不會重複劃轉。

API Key IP 白名單(選用)

選用安全機制(opt-in):為您的 API Key 綁定來源 IP 白名單。設定後, 只有白名單內的 IP 能以此 API Key 調用商戶 API,其他來源一律回 403。 未設定(預設)則不限制,行為與現在完全相同。建議所有正式接入的商戶啟用, 可大幅降低 API Key 洩漏後被盜用的風險。

設定方式

於商戶後台(「Webhook 設定」區塊)填寫,或以 API 設定:

http
PUT /api/platform/allowed-ips
x-api-key: $KEY
Content-Type: application/json

{ "allowedIps": ["203.0.113.7", "10.0.0.0/24", "2001:db8::1"] }

格式:字串陣列,每項為單一 IPv4/IPv6(如 203.0.113.7)或 CIDR 網段(如 10.0.0.0/24、2001:db8::/32),上限 20 組。傳 null 或空陣列清除(不限制)。 目前設定可從 GET /api/platform/me 的 allowedIps 欄位查詢。

未命中時的回應

來源 IP 不在白名單內時,所有以此 API Key 發起的請求回:

json
HTTP 403
{
  "error": "API_KEY_IP_FORBIDDEN",
  "message": "此 API Key 已啟用來源 IP 白名單,您的請求來源 IP(198.51.100.9)不在白名單內。...",
  "sourceIp": "198.51.100.9"
}

回應中的 sourceIp 是支付中心(SOHO Wallet)實際看到的請求來源 IP,方便您排查(例如出口 IP 與預期不符、經過了未預期的代理等)。 比對以伺服器實際看到的真實來源 IP 為準,客戶端自帶的 X-Forwarded-For 等代理 header 不會被採用(無法藉此偽造來源)。

⚠️ 請填貴司伺服器的「出口 IP」

白名單比對的是您的伺服器對外發起請求時的公網出口 IP(egress IP), 不是內網 IP。若您的服務部署在雲平台或經 NAT 出網,請先確認實際出口 IP (例如在該伺服器上執行 curl ifconfig.me)。 另外,商戶後台本身也以 API Key 調用——設定前請確保您當前瀏覽器的出口 IP 也在白名單內, 否則將無法繼續使用 Portal(可從白名單內的伺服器以 API 清除設定)。

💡 不影響客戶端 Widget

此限制只作用於「以 API Key 認證」的伺服器對伺服器調用 (劃轉、對帳、Token 簽發等)。客戶在 Widget 中的操作使用的是客戶 Token(JWT), 不受此白名單限制——客戶從任何網路環境使用 Widget 都不受影響。

錯誤碼表

錯誤回應格式統一為 { "error": "...", "code": "...", "message": "..." }, 部分錯誤附加欄位(如 retryAfter、reason)。 程式化判斷請一律以 code 欄位為準 (SCREAMING_SNAKE 命名,對外穩定契約);error 與 message 為歷史欄位,格式不一(白話/中文),僅供顯示。 少數參數驗證失敗回 { "error": "Validation Error", "details": [...] }; 500 為系統內部錯誤,不會洩漏內部細節。

HTTP錯誤碼(code)含義
401Invalid token客戶 Token 無效或已過期 → 重新簽發 Token
401UnauthorizedAPI Key 缺失/無效
400Missing x-user-idAPI Key 認證路徑未帶 x-user-id header
403API_KEY_IP_FORBIDDENAPI Key 來源 IP 不在白名單(回應含 sourceIp)
403VAULT_OWNER_TOKEN_FORBIDDEN不得為錢包帳號簽發 widget token
403VAULT_OWNER_LOGIN_REQUIRED錢包帳號資金操作僅限本人登入
403PLATFORM_API_KEY_REQUIREDfrom_platform 劃轉僅限 API Key 發起
4032FA_REQUIRED需要 2FA 驗證碼(先呼叫 send-otp)
4032FA_INVALID2FA 驗證碼無效或已過期
403USDC_DISABLED帶入 crypto=USDC(目前僅支援 USDT,USDC 已停用)
409REF_ID_CONFLICT / REF_ID_MISMATCH建單 refId 已被同商戶其他客戶使用 / 同客戶重送但參數與原單不一致(見「買賣訂單」章節)
400AMBIGUOUS_PRICE_SOURCEofferId 路徑與 channelId/cryptoAmount/currency 等新路徑欄位同時出現
400CHANNEL_REQUIRED新路徑沒帶 channelId,且商戶未設預設渠道
400INVALID_AMOUNT_PRECISION金額小數位數超過允許精度
404CHANNEL_NOT_FOUNDchannelId 不存在或不屬於此商戶
422CHANNEL_NOT_QUOTABLE該渠道未設詢價 URL,或未發放渠道 Key+Secret(不是系統型渠道)
422CHANNEL_QUOTE_REJECTED渠道回 available=false(回應帶 reason 透傳,例 AMOUNT_OUT_OF_RANGE/CURRENCY_NOT_SUPPORTED/TEMPORARILY_UNAVAILABLE);不建單、不凍結
503CHANNEL_QUOTE_UNAVAILABLE詢價逾時(3 秒)/連不上/回應簽章錯誤/回應不合法;不建單、不凍結,可稍後以同一 refId 重送
422OFFER_CHANNEL_REQUIRES_QUOTEofferId 指向系統型渠道的報價牌;請改用 channelId+cryptoAmount 新路徑
422MANUAL_CONFIRM_NOT_ALLOWED系統型渠道的訂單只能由渠道回打確認,商戶後台不可人工確認
400INSUFFICIENT_BALANCE客戶資金帳戶餘額不足
400INSUFFICIENT_PLATFORM_BALANCE商戶錢包餘額不足(有平台費欠繳時,需餘額 ≥ 金額+欠繳,message 含欠繳數字)
400PLATFORM_VAULT_NOT_BOUND商戶尚未綁定錢包帳號
400TRANSFER_CONFIRM_REJECTED劃轉前確認被商戶拒絕(含 reason)
400TRANSFER_CONFIRM_UNAVAILABLE劃轉前確認無法連線,fail-closed 拒絕
400DAILY_LIMIT_EXCEEDED超過每日提幣限額(error 欄位為舊值 DailyLimitExceeded)
400OFFER_NOT_FOUND報價不存在或已下架
400AMOUNT_BELOW_MIN / AMOUNT_ABOVE_MAX金額低於下限 / 超過上限(建單依報價 min–max;提幣依提幣設定)
400OFFER_RATE_UNAVAILABLE動態報價匯率暫時不可用
400ORDER_CREATION_FAILED建單失敗(其他未分類原因,見 message)
400INVALID_ORDER_STATUS訂單狀態不允許此操作(如對非 pending 訂單 confirm-paid)
400INVALID_AMOUNT金額格式/數值無效
400INVALID_ADDRESS地址格式錯誤(提幣/地址簿);提幣 message 按 chain 給對應格式提示,見「多鏈提幣」章節
400UNSUPPORTED_CHAIN / UNSUPPORTED_CHAIN_CRYPTO / CHAIN_TEMPORARILY_DISABLED多鏈充提:鏈未開放(貴司商戶未開通 BEP20 / ARB)/ 該鏈不支援此幣種 / 該鏈暫停提幣(見「多鏈提幣(BEP20 / ARB)」章節)
400WALLET_NOT_FOUND尚未產生該幣種鏈上錢包(先呼叫 deposit/address)
400ADDRESS_BOOK_FULL提幣地址簿已滿(每幣種上限 20)
400SELF_TRANSFER_FORBIDDEN不可站內轉帳給自己
400TRANSFER_FAILED劃轉/轉帳失敗(其他未分類原因,見 message)
400SWAP_VALIDATION閃兌參數驗證失敗(幣種/金額超出供應商範圍等)
400OTP_INVALID2FA 驗證碼無效或已過期(/api/2fa/verify)
400TWOFA_ENABLE_FAILED / OTP_SEND_FAILED啟用 2FA / 發送驗證碼失敗(見 message)
403IDENTITY_MISMATCHbody 帶的 tradingPlatformId/platformUserId 與認證身分不符
404ORDER_NOT_FOUND訂單不存在或非本人訂單(含閃兌訂單)
404RECIPIENT_NOT_FOUND站內轉帳收款人不存在
404ADDRESS_NOT_FOUND地址簿項目不存在或非本人
429TOO_MANY_REQUESTSOTP 限流/鎖定,依 retryAfter 退避
503SWAP_UNAVAILABLE閃兌未開放
502SWAP_PROVIDER_ERROR閃兌供應商暫時無法服務

備註:401(Invalid token / Unauthorized)與參數驗證 400(Validation Error + details)目前不帶 code 欄位, 請分別以 HTTP 狀態碼與 details 陣列判斷。

錯誤碼

HTTP錯誤碼(code)出現在含義與處理
400AMOUNT_REQUIRED試算cryptoAmount 與 fiatAmount 都沒帶
400INVALID_AMOUNT_PRECISION試算金額小數位超出限制
404CHANNEL_NOT_FOUND試算/下單渠道不存在、未綁定、已下線或不在上工中名單;請重新取渠道列表
422REFERENCE_RATE_UNAVAILABLE試算帶法幣金額但目前沒有參考價可換算;改用 cryptoAmount 或稍後再試
422CHANNEL_NOT_QUOTABLE試算渠道目前不能報價(非系統型渠道或條件不符)
422CHANNEL_QUOTE_REJECTED試算渠道不報價(例如金額超出範圍),reason 原樣透傳
429QUOTE_RATE_LIMITED試算試算太頻繁(每客戶 10 次/分、每商戶 120 次/分),依 retryAfter 稍後再試
503CHANNEL_QUOTE_UNAVAILABLE試算/下單渠道詢價逾時或失敗,不建單、不凍結;可稍後重試
404QUOTE_NOT_FOUND下單報價單不存在,或不屬於這個商戶/客戶
409QUOTE_ALREADY_USED下單報價單已被使用(不同客戶或已建過單)
409QUOTE_EXPIRED下單報價過期,回應附 newQuote 與 previousRate,請客戶再確認
409QUOTE_MISMATCH下單同時帶的 channelId/金額等與報價單不一致
400AMBIGUOUS_PRICE_SOURCE下單帶 quoteId 又帶 offerId,價格來源不明確
422RATE_AMOUNT_CONFLICT下單customerRate 與 fiatAmount 都帶但互相不一致(二擇一)
422SPREAD_EXCEEDS_LIMIT下單客戶匯率/法幣數額與參考匯率的價差超過 maxSpreadPct 上限(回應含 hint、maxSpreadPct、referenceRate)
409REF_ID_MISMATCH下單同 refId 重送,但 customerRate/fiatAmount 與原單不同
400INSUFFICIENT_PLATFORM_BALANCE下單商戶錢包餘額不足(含平台費欠繳時 message 會註明),報價單退回未使用

測試環境

測試環境為獨立部署的完整站台,與正式環境()帳號、資料互不相通。接入開發期間請將所有 Base URL 指向測試環境:

項目測試環境正式環境
API Base URL
SDK script/sdk.js/sdk.js
Widget Demo/widget-demo/widget-demo
商戶開戶/register/register
Swagger 文件(測試環境不對外開放)/api-docs

測試環境使用真實主網(TRON / BSC / Arbitrum,非測試鏈),測試儲值時請使用小額 USDT。 兩個環境跑同一版程式,API 契約一致(Swagger 以正式環境為準)。 測試環境支援全部流程:簽 token、Widget 嵌入、儲值、買賣訂單、雙向劃轉、Webhook(含 webhook-test 端點)。

測試環境與正式環境完全獨立

  • 兩個環境的資料庫完全獨立:帳號、客戶、餘額、訂單互不相通
  • API Key 互不通用:測試環境產生的 Key 無法在正式環境使用(反之亦然),跨環境呼叫會得到 401
  • 測試時請將 API Base URL(token、劃轉、查詢、SDK script 等)全部指向 ;正式上線時再全部切換為正式環境域名

⚠️ 常見 401 原因

在測試環境產生的 API Key,卻把請求打到正式環境(或反過來),會因 Key 不存在而回 401。 請確認 API Key 與 Base URL 屬於同一個環境。

💡 建議接入流程

先在測試環境完整跑通(token → Widget → 小額儲值 → 雙向劃轉 → Webhook 驗簽/去重), 再於正式環境開戶並產生正式 API Key 上線。

管理 API 總覽(給 Agent)

管理 API 讓 AI Agent 代為操作商戶後台:後台 UI 能做的事(建渠道、設網址、欄位映射、上下線、測試、查紀錄與訂單…),API 都能做。 前綴為 /api/merchant/v1,以 Authorization: Bearer <管理 Key> 認證。機器可讀的精簡版見 /docs/agent-guide 與 /llms.txt。

管理 Key vs 交易 Key

管理 Key交易 API Key
用途管理渠道、對接設定、查詢(後台操作)交易整合:token、quotes、建單、劃轉
HeaderAuthorization: Bearer mk_…x-api-key
可打的 API/api/merchant/v1/*/api/v1/platform/*
誤用打交易 API → 401打管理 API → 401 INVALID_MANAGEMENT_KEY
建立/吊銷僅人類在後台後台

Scope

scope說明
channels:read讀取渠道、上線檢查、紀錄、欄位映射、詢價試算
channels:write建立/修改/停用/解綁渠道、上下線、測試詢價與建單
mappings:write修改欄位映射
integration:read讀取 Webhook、IP 白名單、API Key(masked)、回打憑證(masked)
integration:write修改 Webhook/IP 白名單、輪替 Key/憑證/Secret(🔒 受保險絲管制)
orders:read讀取訂單列表與詳情
account:read讀取金庫餘額、平台費與流水

如何在後台建立管理 Key

  1. 1登入商戶後台,進入「管理 Key」頁面。
  2. 2填寫標籤,勾選需要的 scope(最小權限原則),可選填 IP 白名單(IPv4/IPv6/CIDR,最多 20 筆)與到期時間。
  3. 3若帳號已啟用 TOTP,輸入驗證碼後建立。
  4. 4明文 Key(mk_…)只顯示一次,請立即交給 Agent 保存;可隨時在後台吊銷。
帳號、密碼、2FA、登入、管理 Key 的建立與吊銷永遠只能由人類在後台操作,管理 API 不提供。

管理 API 端點

路徑前綴 /api/merchant/v1。🔒 = 高敏感操作,商戶保險絲開啟時回 202 待人類確認(見下節)。

方法路徑scope用途
GET/me(無)Key 自身:id/label/prefix/last4/scopes、保險絲狀態、限流資訊(limit/remaining/resetAt)、platform {id,name}、maxSpreadPct、defaultSpreadPct(手續費 %,字串|null)
GET/channelschannels:read渠道列表(同後台 GET /api/platform/channels 回應)
POST/channelschannels:write建渠道(body 同後台;system 型可帶 fieldMappings)
GET/channels/:idchannels:read渠道詳情
PATCH/channels/:idchannels:write改資料、三網址(quoteUrl/createOrderUrl/callbackUrl)、payUrlHostAllowlist、手續費 defaultSpreadPct(單一費用 %,字串|null,最多 3 位小數、可負=讓利;null=沿用商戶層;|值|>maxSpreadPct 422 SPREAD_EXCEEDS_LIMIT);改 URL 自動下線
DELETE/channels/:merchantIdchannels:write解綁(409 CHANNEL_HAS_OPEN_ORDERS)
POST/channels/:merchantId/pausechannels:write停用
POST/channels/:merchantId/resumechannels:write啟用
GET/channels/:id/onboarding-statuschannels:read上線檢查結果
PATCH/channels/:id/onlinechannels:writebody {isOnline:boolean} 上線/下線(須通過檢查)
POST/channels/:id/test-quotechannels:write測試詢價(真打)
POST/channels/:id/test-create-orderchannels:write測試建單(真打,不產生訂單)
POST/channels/:id/test-callbackchannels:write發回打測試單號
POST/channels/:id/webhook-testchannels:write測試推送
POST/channels/:id/quote-testchannels:read詢價試算(不持久化)
GET/channels/:id/webhook-logschannels:read推送紀錄(limit/offset)
GET/channels/:id/quote-logschannels:read詢價紀錄(page/limit)
GET/channels/:id/field-mappingschannels:read欄位映射
PUT/channels/:id/field-mappingsmappings:write整組取代 body {mappings:[{mappingType,ourField,merchantField,notes?}]}
POST/channels/:id/field-mappingsmappings:write新增一筆
PATCH/channels/:id/field-mappings/:mappingIdmappings:write改一筆
DELETE/channels/:id/field-mappings/:mappingIdmappings:write刪一筆
POST/channels/:id/field-mappings/suggestchannels:read貼 JSON 樣本 body {kind:"quote"|"create"|"webhook", sample:object} → {suggestions:[{ourField,merchantField,confidence,candidates[]}], unmatched:[ourField]}
POST/channels/:id/webhook-secret/rotate 🔒integration:write重置渠道 Webhook Secret
GET/channels/:id/credentialsintegration:read回打憑證(masked:keyLast4、issuedAt、hasSecret)
POST/channels/:id/credentials/rotate 🔒integration:write輪替回打憑證(一次性回明文)
PUT/channels/:id/allowed-ips 🔒integration:write渠道回打 IP 白名單
GET/webhookintegration:read商戶 Webhook URL
PUT/webhook 🔒integration:write改 Webhook URL body {webhookUrl}
PUT/default-spreadintegration:write改商戶層手續費 body {defaultSpreadPct}(單一費用 %,字串|null;最多 3 位小數、可負=讓利);系統依方向套用(客戶買 ref×(1+pct/100)、客戶賣 ref×(1−pct/100));建單未帶 customerRate/fiatAmount 時套用,|值|>maxSpreadPct 回 422 SPREAD_EXCEEDS_LIMIT
PUT/max-spread-pctintegration:write改最大價差(目前值由 GET /me 的 maxSpreadPct 讀取)body {maxSpreadPct:"5.00"}(0–100、2 位小數);商戶自訂客戶匯率/法幣數額與渠道參考匯率的差距上限,超過下單回 422 SPREAD_EXCEEDS_LIMIT
GET/webhook-logsintegration:read商戶推送紀錄
POST/webhook-testintegration:write測試推送到商戶 Webhook
GET/allowed-ipsintegration:read交易 API Key IP 白名單
PUT/allowed-ips 🔒integration:write改白名單 body {allowedIps:string[]|null}
GET/api-keyintegration:read交易 API Key(masked)
POST/api-key/rotate 🔒integration:write輪替交易 API Key(一次性回明文)
GET/approvals(無)本 Key 相關待確認列表 ?status=pending|approved|rejected|expired|all
GET/approvals/:id(無)單筆狀態;approved 時含 result(含一次性明文,僅第一次 GET 回傳後清除)
GET/ordersorders:read訂單列表 ?status&channelId&limit&offset
GET/orders/:idorders:read訂單詳情
GET/accountaccount:read金庫餘額+平台費(同後台 /api/platform/account)
GET/account/ledgeraccount:read金庫流水 ?limit&offset

冪等、保險絲、限流與錯誤碼

冪等(Idempotency-Key)

所有寫操作(POST/PUT/PATCH/DELETE)可帶 Idempotency-Key(1–128 字),伺服器保存 24 小時、每把 Key 獨立:

  • 同 key+同 body:回傳原 status 與 body,並加 header Idempotent-Replayed: true。
  • 同 key+不同 body:409 IDEMPOTENCY_MISMATCH。
  • 同 key 仍在處理中:409 IDEMPOTENCY_IN_PROGRESS,稍後以同 key 重試。

保險絲(高敏感操作需人類確認)

標 🔒 的操作在保險絲開啟(預設)時不會立即執行,而是回 202:

json
{ "success": true, "status": "pending_approval", "approvalId": "…", "actionType": "channel.credentials.rotate", "expiresAt": "…" }
  1. 1收到 202 與 approvalId。
  2. 2通知人類到後台「待確認」確認(需 TOTP);24 小時未處理即過期(expired)。
  3. 3用 GET /approvals/:id 查結果;approved 時含 result,一次性明文(新 Key/Secret)只在第一次 GET 回傳。

actionType:platform.api_key.rotate、platform.webhook_url.set、platform.allowed_ips.set、channel.webhook_secret.rotate、channel.credentials.rotate、channel.allowed_ips.set。保險絲關閉則直接執行並回 200。

限流

每把 Key 每分鐘 120 次;超過回 429 RATE_LIMITED 與 Retry-After。GET /me 可查 limit/remaining/resetAt。

錯誤格式

json
{ "success": false, "error": "<CODE>", "code": "<CODE>", "message": "...", "hint": "英文下一步建議", "docs": "/docs/agent-guide#<code 小寫>" }
hint 為下一步建議,docs 指向 /docs/agent-guide 中該錯誤碼的說明。缺 scope 時為 403 INSUFFICIENT_SCOPE 並帶 requiredScope。

錯誤碼表

codeHTTP說明
MISSING_MANAGEMENT_KEY401未帶 Authorization: Bearer <管理 Key>
INVALID_MANAGEMENT_KEY401管理 Key 無效(例如誤用交易 API Key 打管理 API)
MANAGEMENT_KEY_REVOKED401管理 Key 已被吊銷,請在後台重新建立
MANAGEMENT_KEY_EXPIRED401管理 Key 已過期,請在後台重新建立
IP_NOT_ALLOWED403來源 IP 不在此 Key 的 allowedIps 內
INSUFFICIENT_SCOPE403缺少 scope;回應含 requiredScope 欄位
RATE_LIMITED429每把 Key 每分鐘 120 次;依 Retry-After 稍後重試
IDEMPOTENCY_MISMATCH409同一 Idempotency-Key 但 body 不同
IDEMPOTENCY_IN_PROGRESS409同一 Idempotency-Key 的請求仍在處理中
VALIDATION_ERROR400請求參數不合法
CHANNEL_NOT_FOUND404找不到渠道(或不屬於此商戶)
APPROVAL_NOT_FOUND404找不到待確認記錄
APPROVAL_NOT_PENDING409待確認記錄已不是 pending(已處理或過期)
CHANNEL_NOT_SYSTEM400此操作僅限 system 型渠道
URL_REQUIRED400上線前須先設定必要網址
WEBHOOK_URL_BLOCKED400Webhook URL 被安全檢查擋下(內網/不允許的位址)
MAPPING_DUPLICATE409欄位映射重複
CHANNEL_HAS_OPEN_ORDERS409渠道仍有未結訂單,無法解綁

最小可用範例(curl)

建渠道 → 設欄位映射 → 上線 → 查上線檢查結果。

bash
BASE=
MK=mk_xxxxxxxx_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx   # 後台建立的管理 Key

# 1) 建 system 型渠道(需 channels:write)
curl -sS -X POST "$BASE/api/merchant/v1/channels" \
  -H "Authorization: Bearer $MK" -H "Idempotency-Key: create-ch-001" \
  -H "Content-Type: application/json" \
  -d '{"name":"My Channel","contactEmail":"[email protected]","channelType":"system","quoteUrl":"https://ch.example.com/quote","createOrderUrl":"https://ch.example.com/orders","callbackUrl":"https://ch.example.com/callback"}'

# 2) 整組取代欄位映射(需 mappings:write;CHANNEL_ID 取自上一步回應)
curl -sS -X PUT "$BASE/api/merchant/v1/channels/$CHANNEL_ID/field-mappings" \
  -H "Authorization: Bearer $MK" -H "Idempotency-Key: map-ch-001" \
  -H "Content-Type: application/json" \
  -d '{"mappings":[{"mappingType":"quote_field","ourField":"rate","merchantField":"data.price"}]}'

# 3) 上線(需 channels:write;須通過上線檢查)
curl -sS -X PATCH "$BASE/api/merchant/v1/channels/$CHANNEL_ID/online" \
  -H "Authorization: Bearer $MK" -H "Idempotency-Key: online-ch-001" \
  -H "Content-Type: application/json" -d '{"isOnline":true}'

# 4) 查上線檢查結果(需 channels:read)
curl -sS "$BASE/api/merchant/v1/channels/$CHANNEL_ID/onboarding-status" \
  -H "Authorization: Bearer $MK"

渠道對接規格(給渠道看的一頁)

本頁寫給渠道的技術人員,可單獨轉給渠道。渠道有自己的系統,支付中心與它之間只有三件事:詢價(支付中心問渠道「這筆多少錢」)、建單(客戶確認後,支付中心向渠道建單,渠道回付款網址,客戶到該網址付款)、回打(渠道收款後通知支付中心)。 支付中心不經手法幣、不碰私鑰;法幣由客戶直接付給渠道。

#端點方向誰實作簽章金鑰
①詢價 URL(Quote URL)支付中心 → 渠道渠道提供 HTTPS 端點請求用 Webhook Secret 簽;回應用渠道 Secret 簽
②建單網址(Create Order URL)支付中心 → 渠道渠道提供 HTTPS 建單端點,回付款網址請求用 Webhook Secret 簽(X-Stellabit-Signature)
③回打(支付中心的兩個端點)渠道 → 支付中心渠道呼叫渠道 Key+渠道 Secret

另外渠道還需提供一個 通知網址(Webhook URL) 接收取消等後續事件(見「Webhook 通知(支付中心 → 渠道)」)。建單請求本身就是新單通知,不會另外再發 order.created。

憑證一覽(由商戶在後台產生,交給渠道)

憑證白話用在哪
Webhook Secret支付中心發訊息給渠道時蓋的「印章」鑰匙渠道用它驗:詢價請求、建單請求、Webhook 通知
渠道 Key(Channel Key)渠道回打時出示的「身分證」回打 header x-api-key
渠道 Secret(Channel Secret)渠道回打時蓋的「印章」鑰匙,只顯示一次,不在網路上傳送簽回打請求;簽詢價回應
IP 白名單(選填)只收這些渠道伺服器 IP 打來的回打;空=不限額外一道,不取代 Key+簽章

兩把 Secret 分開是為了方向分離:任一把外洩只影響一個方向,且可各自重新產生。

定價模型(v1.16):渠道只認「法幣數額該收/該出多少、給誰」。渠道的報價只是參考匯率,給平台與商戶參考; 商戶可在上限內自訂給客戶的匯率或法幣數額,建單帶給渠道的 fiatAmount = 商戶定的數額,渠道收到的 rate 欄位=參考匯率(不含客戶匯率)。 商戶與渠道之間的差額由雙方自行結算,平台不計算、不介入。

① 詢價端點(支付中心 → 渠道)

渠道在後台填入的「詢價 URL」必須是 https。渠道沒有詢價介面就不能設為系統型渠道。每張單、每次試算都即時詢價,不快取、不重試;逾時 3 秒(連線加讀取合計)、不跟隨轉址,逾時或失敗一律視為渠道暫時不可報價。

請求(POST {詢價 URL})Headers:

Header值
Content-Typeapplication/json
X-Stellabit-Eventquote.request
X-Stellabit-Merchant渠道 id
X-Stellabit-Signaturesha256= + hex(HMAC_SHA256(Webhook Secret, rawBody))

請求 Body:

欄位型別說明
requestIduuid本次詢價 id,渠道可用來去重;回應必須原樣帶回
typebuy | sellbuy=客戶買幣(充值單);sell=客戶賣幣(提現單)
cryptostring例 USDT
networkstring?例 TRC20
cryptoAmountstring(decimal)客戶要買/賣的幣數
currencystring法幣:THB | HKD | CNY | IDR
externalOrderIdstring?商戶系統帶來的外部單號(若有)
timestampintunix 秒;渠道應拒絕 ±300 秒外的請求

回應:HTTP 2xx,並帶 header X-Channel-Timestamp(unix 秒,與支付中心時間差須在 ±300 秒內)與 X-Channel-Signature = sha256= + hex(HMAC_SHA256(渠道 Secret, {timestamp}.{requestId}.{rawResponseBody}))。簽章不過,視同詢價失敗。

可報價:

json
{
  "available": true,
  "requestId": "與請求相同的 uuid",
  "quoteId": "渠道自己的報價單號(≤64 字元,同渠道不可重複)",
  "cryptoAmount": "250",
  "currency": "THB",
  "fiatAmount": "9130.00",
  "rate": "36.52",
  "expiresAt": "2026-11-07T08:05:00.000Z"
}
欄位規則
available必須為 true/false(布林)
requestId必須等於請求的
cryptoAmount必須等於請求的(以 8 位小數比較),否則視為無效報價
currency必須等於請求的
fiatAmount字串,最多 2 位小數。buy:客戶要付的法幣;sell:渠道要付給客戶的法幣。單上的金額就是這個值
rate字串,最多 8 位小數;這是「參考匯率」,須滿足 |fiatAmount − cryptoAmount × rate| ≤ 0.01(防算錯,不是容忍價差)。商戶可能在上限內調整給客戶的匯率,最終以建單的 fiatAmount 為準
quoteId1–64 字元,同一渠道不可重複使用
expiresAtISO 8601。渠道承諾此價到此時有效;須晚於現在 60 秒以上(否則該次詢價視為渠道不接受),超過 30 分鐘以 30 分鐘計

不報價(同樣要簽章):

json
{ "available": false, "reason": "AMOUNT_OUT_OF_RANGE", "message": "選填說明" }

reason 可用 AMOUNT_OUT_OF_RANGE、CURRENCY_NOT_SUPPORTED、TEMPORARILY_UNAVAILABLE 或自訂字串,會原樣透傳給商戶系統(422 CHANNEL_QUOTE_REJECTED)。 詢價回應中的 quoteId、fiatAmount、rate、expiresAt、cryptoAmount 欄位名可用「欄位映射」改成渠道自己的叫法(見下方);available、requestId、currency 固定用標準名。

② 建單端點(支付中心 → 渠道,渠道回付款網址)

客戶確認下單後,支付中心先建單並凍結商戶錢包,接著同步 POST 渠道登記的「建單網址」;渠道建好單,回一條付款網址(payUrl)。 支付中心把它放進 merchantTransactionUrl 回給商戶系統,商戶系統再把客戶導向該網址付款。支付中心不再自己拼交易頁網址、也不再對網址參數簽章——網址完整性由渠道負責。

請求(POST {建單網址},Content-Type: application/json)Headers:

Header值
X-Stellabit-Signaturesha256= + hex(HMAC_SHA256(Webhook Secret, rawBody));簽「原始 body 字串」,與詢價請求同一套驗法
Idempotency-Key支付中心訂單 id(等同 body 的 orderId),渠道端建單的冪等鍵

Body 欄位:

欄位說明
orderId支付中心訂單 id(uuid)。渠道建單的冪等鍵,回打時要原樣帶回
orderNo訂單編號,給人看的
type固定 topup(客戶付法幣買幣);賣幣單法幣由渠道付給客戶,不走建單
fiatAmount法幣數額(字串,兩位小數)=商戶定的數額,渠道照這個數額收/付;可能與詢價時的報價略有不同
currency法幣
cryptoAmount幣數
crypto幣種
rate參考匯率(=詢價時渠道自己報的匯率)。不會帶商戶給客戶的匯率;請勿用它重算 fiatAmount,以 fiatAmount 為準
channelQuoteId渠道詢價時回的報價單號(有才帶)
expiresAt訂單有效期,ISO 8601
ts請求時間,unix 毫秒;建議渠道拒絕 ±5 分鐘以外的請求(防重放)
test只有後台「測試建單」才帶 true,且 orderId 以 TEST- 開頭

body 欄位名可用 webhook_field 映射改成渠道自己的叫法;沒映射就是標準名。不會帶客戶個資、商戶內部 ID、客戶 refId。

json
{
  "orderId": "3f1c9a52-8e0b-4d6c-9b61-2c7d1f0e5a11",
  "orderNo": "P2P-20261107-00123",
  "type": "topup",
  "fiatAmount": "3512.00",
  "currency": "THB",
  "cryptoAmount": "100.00000000",
  "crypto": "USDT",
  "rate": "35.12",
  "channelQuoteId": "Q-8841",
  "expiresAt": "2026-11-07T09:30:00.000Z",
  "ts": 1794041628056
}

驗簽範例(用原始 body 驗,不要先 parse 再重新 stringify):

javascript
const crypto = require('crypto')

function verifyCreateOrder(rawBody, signatureHeader, webhookSecret) {
  const expected = 'sha256=' + crypto.createHmac('sha256', webhookSecret).update(rawBody).digest('hex')
  return signatureHeader && expected.length === signatureHeader.length &&
    crypto.timingSafeEqual(Buffer.from(expected), Buffer.from(signatureHeader))
}
python
import hmac, hashlib

def verify_create_order(raw_body: bytes, signature_header: str, webhook_secret: str) -> bool:
    expected = 'sha256=' + hmac.new(webhook_secret.encode(), raw_body, hashlib.sha256).hexdigest()
    return hmac.compare_digest(expected, signature_header or '')
php
function verifyCreateOrder(string $rawBody, string $signatureHeader, string $webhookSecret): bool {
    $expected = 'sha256=' . hash_hmac('sha256', $rawBody, $webhookSecret);
    return hash_equals($expected, $signatureHeader);
}

回應:HTTP 2xx、JSON。

欄位必填說明
payUrl✅付款網址。必須 https、不超過 2048 字、不含帳密(user:pass@)。支付中心只當不透明字串轉交商戶,不會去開它
channelOrderId建議渠道自己的訂單號,對帳/客服用;缺則存空
expiresAt選填付款網址到期時間(ISO 8601);缺則沿用我方訂單有效期
json
{ "payUrl": "https://pay.a.example.com/c/9Zk3Qm...", "channelOrderId": "A-20261107-77", "expiresAt": "2026-11-07T09:30:00.000Z" }

回應中的 payUrl、channelOrderId、expiresAt 欄位名可用「建單回應欄位(create_field)」映射改成渠道的叫法(支援 a.b 點路徑,例如 data.cashier_url → payUrl)。若商戶設了「付款網址網域限制」,payUrl 的網域必須等於或是清單內網域的子網域。

建單的規則(固定網址渠道、冪等、逾時、錯誤)

  • 固定網址渠道:你的付款頁是固定網址、訂單資訊自行處理?建單端點每次回同一個 payUrl 即可,不需要第二套機制;訂單資訊(orderNo 等)請在你這邊用建單請求的內容記錄。
  • 冪等:同一個 orderId(Idempotency-Key)重送,必須回同一個 payUrl/同一張渠道單,不可重複建單。
  • 時限:請在 8 秒內回應(含讀取 body)。支付中心不跟隨轉址;連線失敗或 HTTP 502/503/504 會在時限內重試最多 1 次,逾時不自動重試(渠道可能已建單)。
  • 失敗與逾時:非 2xx、非 JSON、缺 payUrl、payUrl 不合規、逾時,一律視為建單失敗:支付中心取消該單、解凍商戶錢包、回商戶 503 CHANNEL_CREATE_FAILED。逾時時會再發一次 order.cancelled Webhook 給你,收到請作廢該單。
  • 付款完成仍靠回打:付款網址不是入帳依據。客戶付款後請照下方「③ 回打」通知支付中心;支付中心只認回打(簽章驗證)+金額核對。
  • 測試:後台「測試建單」會帶 "test": true 與 TEST- 開頭的 orderId,請回正常格式的 payUrl,但不要建立真實可付款的單。測試不會在支付中心產生訂單、不凍結。

Webhook 通知(支付中心 → 渠道的 Webhook URL)

支付中心把訂單事件 POST 到渠道的 Webhook URL(舊名 Callback URL 已作廢,一律稱 Webhook URL)。Headers:X-Stellabit-Event、X-Stellabit-Merchant、X-Stellabit-Signature = sha256= + hex(HMAC_SHA256(Webhook Secret, rawBody)),與詢價請求同一套驗法。失敗會進佇列重試,請以 eventId 去重(同一事件重試時 eventId 不變)。

事件何時重點欄位
order.created提現單建立(v1.13 起充值單不再發 order.created,建單請求即為通知)orderId, orderNo, type, crypto, cryptoAmount, currency, fiatAmount(商戶定的數額), rate(參考匯率), paymentMethod{methodType, details}, createdAt
order.completed劃帳完成同上基本欄位+status, completedAt, overpaid, overpaidAmount;多付時另帶 message,請渠道退客戶差額
order.cancelled訂單作廢或取消基本欄位+reason(underpaid、crypto_mismatch、expired、channel_failed、merchant_cancelled…);少付/幣量不符時另帶 expected/received 欄位
test後台「發送測試推送」只驗連通與驗簽

系統型渠道的訂單由渠道自己的詢價決定價格,order.created 的 paymentMethod 可能為空物件。通知內容一律使用標準欄位名(映射表不套用在這個方向)。

③ 回打(渠道 → 支付中心)

渠道收到客戶的法幣後,呼叫支付中心通知確認:

用途端點
充值單:渠道已收到法幣POST /api/v1/callback/topup-confirm
提現單:渠道已付法幣給客戶POST /api/v1/callback/withdraw-fiat-sent
(選用)渠道自行上線/下線PATCH /api/channel/me/online { "isOnline": true|false }

必帶 Headers(Key 與簽章兩道都要過):

Header說明
x-api-key渠道 Key
X-Channel-Timestampunix 秒;與支付中心時間差須 ≤ 300 秒
X-Channel-Nonce16–64 字元,限 A–Z a–z 0–9 _ -;每通唯一,10 分鐘內不可重用(防重放)
X-Channel-Signaturesha256= + 小寫 hex(HMAC_SHA256(渠道 Secret, canonical))

canonical 為五段以換行(\n)串接:{timestamp}\n{nonce}\n{METHOD}\n{path}\n{rawBody}。METHOD 為大寫(POST);path 不含 host、不含 query(例如 /api/v1/callback/topup-confirm);rawBody 是實際送出的 request body 原始字串,空 body 為空字串。簽章必須對送出的原始 bytes 計算,請勿在簽完後再重新序列化。

javascript
const crypto = require('crypto')

function signedHeaders(channelKey, channelSecret, method, path, rawBody) {
  const timestamp = Math.floor(Date.now() / 1000).toString()
  const nonce = crypto.randomBytes(16).toString('hex')           // 32 字元
  const canonical = [timestamp, nonce, method.toUpperCase(), path, rawBody].join('\n')
  const signature = 'sha256=' + crypto.createHmac('sha256', channelSecret).update(canonical, 'utf8').digest('hex')
  return {
    'Content-Type': 'application/json',
    'x-api-key': channelKey,
    'X-Channel-Timestamp': timestamp,
    'X-Channel-Nonce': nonce,
    'X-Channel-Signature': signature,
  }
}

const rawBody = JSON.stringify({ orderId: '{建單請求帶來的 orderId}', fiatAmount: '9130.00', paymentRef: '渠道側單號(選填)' })
const path = '/api/v1/callback/topup-confirm'
await fetch(BASE_URL + path, { method: 'POST', headers: signedHeaders(KEY, SECRET, 'POST', path, rawBody), body: rawBody })

回打 Body

欄位必填說明
orderId二擇一支付中心訂單 id(建單請求的 orderId)。orderId 與 channelOrderId 至少帶一個
fiatAmountchannel_quote 單必填實收(充值)/實付(提現)法幣金額,必須等於商戶建單時的法幣數額(訂單上的 fiatAmount),精確比對(無容差)。字串、最多 2 位小數;channel_quote 單缺少回 400 FIAT_AMOUNT_REQUIRED
channelOrderId選填渠道自己的訂單號。建議帶:與建單回應給的一致即可;支付中心會核對,也可在 orderId 異常時作反查備援(以 channelOrderId 找回單)。兩者都帶但指向不同的單回 409 ORDER_ID_MISMATCH;只帶 channelOrderId 時,若同一渠道有多筆單撞同一個渠道單號,回 409 CHANNEL_ORDER_ID_AMBIGUOUS(請改帶 orderId)
paymentRef選填渠道側單號(僅充值回打)
cryptoAmount選填渠道認定的幣量;有帶且與單上不符,視為少付處理
rate選填渠道成交匯率,只記錄、不比對

金額核對與回應

情況結果
fiatAmount 等於單上劃帳完成,回 200
多付(大於單上)照單上金額劃帳(不多給幣),訂單完成並標 overpaid;回 200,body 帶 overpaid: true、overpaidAmount;差額請渠道自行退還客戶
少付(小於單上),或 cryptoAmount 與單上不符不劃帳,訂單作廢(price_mismatch)並退回凍結;回 409 PRICE_MISMATCH(帶 expected/received 金額);由商戶系統重新詢價建單,舊單不會復活
同一單重複回打回 200 並帶 idempotent: true,不重複入帳,渠道可放心重試
channelOrderId 與 orderId 對不上(同一通回打帶的兩個單號指向不同的單)409 ORDER_ID_MISMATCH,不動帳;請渠道核對後帶正確單號重打
只帶 channelOrderId,但同一渠道內撞號(多筆單同一渠道單號)409 CHANNEL_ORDER_ID_AMBIGUOUS,不動帳;請改帶 orderId 重打
單不屬於這個渠道404
單已取消/已作廢又來確認409 ORDER_STATE_CONFLICT

200 回應範例:

json
{ "success": true, "orderId": "…", "orderNo": "OD2026110700001", "status": "completed", "idempotent": false, "overpaid": false, "overpaidAmount": null }

驗證失敗的回應

HTTPcode原因
401MISSING_API_KEY / INVALID_API_KEY沒帶或查不到渠道 Key(商戶 API Key 不被接受)
403CHANNEL_INACTIVE / IP_NOT_ALLOWED渠道已停用;來源 IP 不在白名單
401CHANNEL_CREDENTIALS_NOT_ISSUED商戶尚未產生渠道 Key+Secret
401MISSING_SIGNATURE缺 X-Channel-Timestamp/Nonce/Signature
401TIMESTAMP_OUT_OF_WINDOW時間差超過 300 秒
401INVALID_SIGNATURE簽章不符,或 nonce 格式不合
401NONCE_REUSEDnonce 已用過
503NONCE_STORE_UNAVAILABLE防重放服務暫時不可用,稍後重試(重試請換新 nonce 與 timestamp)
422CALLBACK_STATUS_NOT_SUCCESS回打的狀態值(經映射後)不是成功狀態,不動帳

渠道 Key 只能呼叫上述回打路由;拿它呼叫商戶後台或商戶對接 API 一律 401。只拿到 Key(例如 log 外洩)偽造不了確認,必須同時有渠道 Secret。

欄位映射:渠道的叫法 ↔ 支付中心的標準名

渠道的欄位名、狀態值與支付中心不同時,不用改程式:由商戶在後台「欄位映射」建對照表,支付中心自動翻譯。沒有映射就用標準名,渠道直接照本頁實作也能接。 一個標準欄位只能對一個渠道欄位;渠道欄位名支援 a.b 點路徑取巢狀值。

映射類型(後台顯示名)作用在可映射的標準欄位
詢價回應欄位(quote_field)渠道詢價回應 → 支付中心quoteId、fiatAmount、rate、expiresAt、cryptoAmount
建單回應欄位(create_field)渠道建單回應 → 支付中心payUrl(必填)、channelOrderId、expiresAt
建單請求/回打欄位(webhook_field)建單請求 body 的欄位名;回打 body 的欄位名建單請求:orderId、orderNo、fiatAmount、currency、crypto、cryptoAmount、rate、expiresAt、ts;回打:orderId、paymentRef、fiatAmount、rate、cryptoAmount、status
狀態值對應(status_value)回打 body 的 status 值渠道的狀態值 → 標準狀態值

回打 body 若帶 status 且商戶設了狀態相關映射,映射後的值必須是成功狀態之一(success/completed/paid/confirmed,不分大小寫),否則回 422 CALLBACK_STATUS_NOT_SUCCESS、不動帳;沒設狀態映射、或 body 沒帶 status,視為成功。

常見叫法對照

標準名渠道常見的叫法(舉例)說明
orderIdout_trade_no、merchant_order_id、order_id、trade_no支付中心訂單 id(uuid),回打與 channelOrderId 至少帶一個
channelOrderIdtrade_no、platform_order_id、order_id渠道自己的訂單號(選填;回打可作反查備援)
orderNoorder_no、order_sn、reference訂單編號,給人看的
payUrlpay_url、cashier_url、checkout_url、pay_link渠道建單回的付款網址,必填,https
fiatAmountamount、total_fee、pay_amount、real_amount法幣金額;回打時為實收/實付
cryptoAmountcoin_amount、usdt_amount、quantity幣數
rateprice、exchange_rate1 幣 = ? 法幣(詢價回應:參考匯率;建單請求:參考匯率)
quoteIdquote_id、price_id、offer_id(渠道自己的報價單號)渠道報價單號,同渠道不可重複
expiresAtexpire_time、valid_until、expired_at報價有效期,ISO 8601
paymentReftransaction_id、bank_ref、receipt_no渠道側單號,選填
status 值:completedSUCCESS、PAID、DONE、1成功狀態;其他值(如 FAILED)會被擋下,不動帳

名詞對照(後台欄位 ↔ 本頁用語)

後台顯示名本頁用語誰提供
詢價 URL(Quote URL)①詢價端點渠道提供
建單網址(Create Order URL)②建單端點渠道提供
通知網址(Webhook URL,舊稱 Callback URL)接收取消等後續事件的網址渠道提供
Webhook Secret驗支付中心發來的訊息系統產生,商戶交給渠道
渠道 Key/渠道 Secret③回打憑證商戶在後台產生(只顯示一次),交給渠道
欄位映射(Field Mapping)渠道叫法對照商戶填

測試方式

三項測試都在商戶後台操作(渠道設定精靈的「測試連線」(詢價+建單兩段)與「憑證與資料卡」),通過後才能上線;測試不會建立訂單、不會動帳。

測試怎麼做檢查什麼
test-quote(測試連線)商戶後台按「測試連線」,對應 POST /api/platform/channels/:id/test-quote。不需先發憑證支付中心真的向詢價 URL 打一次,逐項檢查:連得上、回應簽章、欄位(含映射)、rate 與有效期(至少 60 秒後到期)
test-create-order(建單測試)商戶後台按「測試建單」,對應 POST /api/platform/channels/:id/test-create-order。不需先發憑證;請求帶 "test": true 與 TEST- 開頭的 orderId支付中心真的向建單網址送一筆測試單,逐項檢查:連得上(不轉址)、HTTP 2xx、回應為 JSON、取得 payUrl(含映射)、payUrl 合規(https、≤2048、無帳密、符合網域限制)、渠道接受簽章(非 401/403)。不產生訂單、不凍結
test-callback(回打測試)商戶後台先產生測試單號(POST /api/platform/channels/:id/test-callback,30 分鐘有效,需已發憑證);渠道用自己的 Key+簽章呼叫 POST /api/v1/callback/test,body { "orderId": "{測試單號}", "test": true }。也可在正式回打路徑加 ?test=true只驗渠道 Key、簽章(含時間與 nonce)與欄位映射,不查訂單、不動帳。失敗回 422,code 為 TEST_ORDER_NOT_ISSUED/TEST_ORDER_EXPIRED/TEST_ORDER_MISMATCH/ORDER_ID_MISSING

上線檢查清單共八項:已選渠道類型、詢價/建單/通知三個網址都已填且為 https、欄位對照正確、已產生對接金鑰、詢價連線測試通過、建單測試通過、回打測試通過、商戶確認已把資料填入渠道後台。渠道自助上線(PATCH /api/channel/me/online)同樣需通過清單。

沙盒渠道(商戶上手教學)

沙盒渠道是一支免依賴的 Node 腳本,扮演「支付渠道」:會回報價、收建單並回付款頁、按下「模擬付款」後向支付中心回打,也能收商戶通知。商戶系統=商戶+SOHO Wallet(支付中心);在支付中心填渠道資訊,就是在串接支付渠道——沙盒渠道讓您不用等真實渠道,就能把這段完整練一遍。

啟動

腳本位於 repo 的 scripts/sandbox-channel/,需要 Node 18+,並且要有一個支付中心連得到的 https 公開網址(反向代理或隧道皆可):

bash
node sandbox-channel.mjs --port 18099 --public-url https://xxx --paycenter https://你的支付中心網址
端點用途
POST /quote詢價(填進精靈的「詢價網址」)
POST /create-order建單(「建單網址」),回付款網址
POST /webhook收商戶的訂單通知(「通知網址」)
GET /pay/:token付款頁,有一顆「模擬付款」
POST /pay/:token/confirm付款頁按鈕呼叫:簽章後回打支付中心 /api/v1/callback/topup-confirm
GET /__setup設定頁:貼資料卡的憑證、送回打測試
GET /__cbtest?orderId=…精靈第 4 步的回打測試
GET /__events最近的詢價/建單/通知/回打紀錄
GET/POST /__cfg讀寫設定(JSON),例:POST /__cfg 帶 {"mode":"price"}

設定(含 Secret)存在 --state 指定的檔案(預設 ./sandbox-state.json,權限 600),重啟後保留;勿提交版控。

模式 mode(可在 /__setup 切換):

mode行為
ok預設。用標準欄位名回應,不需要欄位映射
price改用另一套欄位名,練欄位映射:詢價 price/expire_time/pay_amount;建單 pay_link/trade_no/expire_time
500詢價與建單都回 HTTP 500,練失敗回滾
timeout拖到超過支付中心逾時才回
http建單回 http:// 付款網址,會被拒絕(付款網址必須 https)

商戶上手教學

  1. 1建商戶帳號:到 /register 開戶、設定 2FA,登入後進 /console/dashboard;到「系統對接」拿 API Key、填通知網址(可填沙盒渠道的 /webhook)。
  2. 2用精靈串接沙盒渠道:「渠道 → 新增渠道 → 系統型渠道」。第②步三個網址填:詢價 {public-url}/quote、建單 {public-url}/create-order、通知 {public-url}/webhook(全部 https)。第③步測詢價、測建單全綠後,第④步按「發憑證」。
  3. 3把資料卡貼進 /__setup:資料卡的值對照填入——渠道 Key→「渠道 Key」;渠道 Secret→「渠道 Secret」與「詢價簽章 Secret」;驗證金鑰 Webhook Secret→「Webhook Secret」,儲存。沒填的話,第③步雖然會綠(此步不驗簽章),真正詢價與建單會因簽章不符失敗。
  4. 4回打測試要用最新發的單號:精靈按「發測試單號」,把單號貼到 /__setup 的「回打測試」送出,精靈顯示「已收到渠道的回打測試」即通過。重新發過單號,就要用最新那個;舊的會失敗。勾「我已完成設定」後上線。
  5. 5欄位映射練習:把 mode 切到 price,回精靈第②步(或渠道的「欄位映射」)新增:rate→price、expiresAt→expire_time、fiatAmount→pay_amount、建單的 payUrl→pay_link、channelOrderId→trade_no、建單的 expiresAt→expire_time。渠道欄位名要與渠道文件逐字一致,含底線(expire_time 不是 expireTime),多一個空白或少一個底線都對不上。
  6. 6下單:用 Widget 參考頁(見「Widget:快速開始」;/widget/buy?token=…&currency=THB),或照「10 分鐘接通」步驟②的三個 curl(渠道 → quotes → orders/topup)。渠道必須已「上線」才列得出來。
  7. 7付款頁按「模擬付款」:建單回應的 merchantTransactionUrl 就是沙盒渠道的 /pay/:token 付款頁;按下去,沙盒渠道會用渠道 Key/Secret 簽章回打支付中心,頁面顯示回打結果。
  8. 8後台看結果:「總覽」看錢包變動;訂單列表看訂單狀態與渠道單號(channelOrderId);「系統對接」的發送紀錄看到 topup.completed 通知。
  9. 9切 500 看失敗回滾:mode 切到 500 再下單:詢價回 503 CHANNEL_QUOTE_UNAVAILABLE、建單回 503 CHANNEL_CREATE_FAILED;單會取消、錢包解凍,不會有扣款。切回 ok 後恢復。

沙盒渠道的 /__setup 沒有身分驗證,只在測試環境使用;Key/Secret 不要貼到公開處,用完請關閉服務。

回到 10 分鐘接通;失敗碼意義見 錯誤碼表。

快速開始

5 分鐘完成接入

接入步驟

  1. 1取得 API Key — 前往 開戶頁 開戶(免審核,開戶即有錢包),登入商戶後台後自助產生 API Key
  2. 2後端換取 Token — 呼叫 /api/widget/token,每次開啟 Widget 前換取
  3. 3前端引入 SDK — <script src="/sdk.js">,然後呼叫 Stellabit.open()

安裝 SDK

在頁面 <head> 或 <body> 底部引入:

html
<script src="/sdk.js"></script>

SDK 載入後自動掛載全域物件 Stellabit,無需額外初始化。

取得 Token

每次客戶要開啟 Widget 前,需由後端呼叫此 API 換取代表該客戶身份的短期 JWT Token(有效期 1 小時),再傳給前端使用。 不可在前端直接呼叫(會暴露 API Key)。

http
POST /api/widget/token
x-api-key: $KEY
Content-Type: application/json

{
  "userId": "您商戶的客戶唯一 ID",
  "expiresIn": 3600
}

回應:

json
{
  "token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
  "expiresIn": 3600,
  "widgetUrl": "/widget/account?token=eyJ..."
}

⚠️ 注意事項

  • API Key 僅在後端使用,切勿暴露至前端
  • Token 有效期 1 小時,建議每次開啟 Widget 前重新換取
  • userId 應為您系統中該客戶的唯一識別符

OTC 兌換 (swap)

C2C 穩定幣兌換,是目前推薦的主要接入入口。swap 並非「買/賣」之外獨立的第三種功能, 而是把買入與賣出整合進同一個視窗:進入後頁面頂部會有「買入 USDT / 賣出 USDT」切換分頁(tab),客戶必須先選定買或賣,才能繼續後續流程。 底層下單 API(/api/v1/orders/topup 對應買入、/api/v1/orders/withdraw 對應賣出) 與舊版 buy/sell widget 相同, swap 是在前端把兩者合併為單一、可雙向輸入金額的 4 步流程:選買/賣 → 輸入金額 → 選渠道(支付渠道,API 中稱 merchant)→ 付款 → 完成。

html
<button onclick="Stellabit.open('swap', token)">買幣 / 賣幣</button>

流程說明

  1. 1進入後先選擇「買入 USDT」或「賣出 USDT」分頁
  2. 2客戶輸入欲換出 / 換入的金額
  3. 3系統列出符合條件的渠道報價
  4. 4客戶選擇渠道,建立訂單
  5. 5客戶依渠道指定方式付款
  6. 6渠道確認收款後交易完成

完成事件:stellabit:done

💡 關於舊版 buy / sell widget

系統內部仍保留獨立的 /widget/buy 與/widget/sell 頁面(較早期的實作,介面較簡化、無金額雙向互算), 但本文件不建議新商戶使用,僅作為既有整合的相容保留。新接入請一律使用 swap。

儲值 (deposit)

「儲值」是指客戶將 USDT 從外部錢包轉入商戶帳戶。預設鏈別為 TRC-20(TRON);若貴司商戶已開通 BEP20(BSC)或 ARB(Arbitrum One)充值, Widget 會提供鏈別切換。系統為每位客戶在每條鏈生成專屬充幣地址, 客戶掃碼或複製地址後,在自己的錢包 App 發起轉帳,系統偵測到鏈上交易確認後自動入帳(各鏈到帳進同一份站內餘額,不分鏈)。

html
<button onclick="Stellabit.open('deposit', token)">儲值 / 充幣</button>

充幣流程

  1. 1SDK 呼叫後,Widget 顯示客戶的專屬充幣地址(含 QR Code;多鏈開通時可切換鏈別)
  2. 2客戶用外部錢包掃碼或複製地址,發起鏈上轉帳
  3. 3系統偵測到鏈上交易並等待確認(TRC-20 掃描間隔預設 5 分鐘,約 5–10 分鐘;BEP20 15 個確認約 15–60 秒;ARB 300 個確認約 1–2 分鐘)
  4. 4交易確認後,商戶帳戶餘額自動更新
  5. 5Widget 顯示充幣成功,觸發 stellabit:done 事件

💡 重要提示

  • 僅接受 USDT,且必須依 Widget 顯示的鏈別轉入對應網路(TRC-20 地址只收 TRON USDT;0x 地址只收該鏈的 USDT),轉錯鏈或其他幣種無法取回
  • 每位客戶在每條鏈的充幣地址固定且唯一,可重複使用
  • 單筆低於 1 USDT 視為灰塵不入帳(金額不累計)

完成事件:stellabit:done(客戶可監聽此事件刷新餘額顯示)

提幣 (withdraw)

客戶將商戶帳戶的 USDT 提出至外部錢包。預設鏈別為 TRC-20;貴司商戶已開通時可選 BEP20(BSC)或 ARB(Arbitrum One)。 需要輸入提幣地址和金額,系統扣除帳戶餘額(含手續費)後發起鏈上轉帳;大額提幣可能進入人工審核。

html
<button onclick="Stellabit.open('withdraw', token)">提幣</button>

流程說明

  1. 1客戶選擇鏈別(預設 TRC-20),輸入對應格式的提幣地址和數量(已啟用 2FA 的客戶需輸入驗證碼)
  2. 2確認後系統立即扣除帳戶餘額(金額 + 手續費)
  3. 3後台發起鏈上轉帳
  4. 4鏈上確認後提幣完成

完成事件:stellabit:done

帳戶總覽 (balance-hub)

顯示客戶的帳戶餘額,並提供餘額劃轉(商戶帳戶 ↔ 交易帳戶)及內部轉帳功能。

html
<button onclick="Stellabit.open('balance-hub', token)">帳戶總覽</button>

功能

  • 查看 USDT 餘額(商戶帳戶、交易帳戶)
  • 劃入商戶(to_platform)
  • 同商戶內轉帳給其他客戶

💡 關於「從商戶轉入」(from_platform)

客戶端不提供「從商戶轉入」方向。商戶 → 客戶的入帳僅限您的後端以 API Key 發起, 並從商戶錢包餘額即時扣款,詳見「商戶系統對接」的「商戶劃轉 API」章節。

嵌入方式

方式呼叫方式適用場景
Popup ModalStellabit.open(action, token)最常用,按鈕觸發,Widget 覆蓋在頁面上方
iframe 嵌入<iframe src="/widget/swap?token=...">一體化頁面設計,Widget 嵌在頁面區塊內

Popup 用法

javascript
// 基本呼叫
Stellabit.open('swap', token)

Stellabit.open() 目前只接受 (action, token) 兩個參數, 不支援第三個選項物件(例如主題);若需要深色主題,請改用下方「主題設定」章節的 iframe URL 參數或 postMessage 方式。

iframe 用法

html
<iframe
  src="/widget/swap?token=YOUR_TOKEN&theme=light"
  width="480"
  height="640"
  frameborder="0"
  style="border-radius: 12px; box-shadow: 0 4px 24px rgba(0,0,0,0.1);"
></iframe>

主題設定

主題僅支援 iframe 嵌入模式(含 Popup 內部使用的 iframe),Stellabit.open() 本身不接受主題參數。

方式一:URL 參數(載入時套用,無閃爍)

javascript
// iframe src 加上 ?theme=dark
/widget/swap?token=...&theme=dark

方式二:postMessage 動態切換(適合跟隨系統主題)

javascript
iframe.contentWindow.postMessage({ type: 'stellabit:theme', theme: 'dark' }, '*')

事件監聽

Widget 透過 window.postMessage 與外層頁面溝通,無論是 Popup 還是 iframe 方式均適用。

javascript
window.addEventListener('message', function(event) {
  const { type, ...data } = event.data || {}

  switch (type) {
    case 'stellabit:done':
      // 客戶完成操作(充幣成功、交易完成、提幣發出等)
      // 建議:重新取得客戶餘額,更新 UI
      refreshUserBalance()
      break

    case 'stellabit:close':
      // 客戶主動關閉 Widget(未完成操作)
      break
  }
})
事件類型觸發時機附帶資料
stellabit:done交易或操作成功完成{ type, action }
stellabit:close客戶關閉 Widget{ type }

附錄:人工報價牌查詢(offers)

本節是「人工報價牌」線(渠道由商戶手動維護報價)。系統型渠道請走「商戶系統對接(主線)」的渠道列表與試算;兩條線完全分開,不會合併顯示。

端點: GET /api/v1/offers
列出貴商戶可見的渠道報價。以客戶 Token 呼叫時自動鎖定貴商戶範圍; 若未帶 Token,則必須以 platformId query 參數指定商戶,否則回空列表(不會洩漏其他商戶的報價)。

方向對照(重要)

type 是渠道視角的方向,與客戶操作方向相反:

客戶操作應查詢的 type對應下單端點
客戶買幣(法幣 → USDT)type=sellPOST /api/v1/orders/topup
客戶賣幣(USDT → 法幣)type=buyPOST /api/v1/orders/withdraw

Query 參數

參數必填說明
type❌buy | sell(渠道視角,見上表)
crypto❌USDT(目前唯一支援幣種;USDC 已停用,帶入會回 403 USDC_DISABLED)
currency❌THB | HKD | CNY | IDR
platformId❌商戶 UUID;未帶客戶 Token 時必填
limit / offset❌分頁;limit 預設 20、上限 100

請求與回應範例

bash
curl "/api/v1/offers?type=sell&crypto=USDT" \
  -H "Authorization: Bearer $TOKEN"
json
{
  "offers": [
    {
      "id": "a1b2c3d4-....",
      "merchantId": "....",
      "merchantName": "渠道 A",
      "type": "sell",
      "crypto": "USDT",
      "currency": "THB",
      "rate": "36.50000000",
      "minAmount": "100.00",
      "maxAmount": "50000.00",
      "paymentMethodId": "....",
      "methodType": "bank_transfer",
      "createdAt": "2026-08-01T00:00:00.000Z"
    }
  ],
  "total": 1
}

rate 為法幣/加密貨幣匯率(如 1 USDT = 36.5 THB),minAmount / maxAmount 為法幣金額限制。 所有金額欄位均為 decimal 字串,請勿用浮點數直接運算。

offerId 路徑下單(人工線專用)

以下買單/賣單端點帶 offerId,屬人工報價牌線;系統型渠道請用主線的試算與建單。

建立買單:POST /api/v1/orders/topup

建單時系統會從貴商戶錢包原子凍結等額 USDT(escrow),錢包可用餘額不足會直接拒單。 訂單有效期 30 分鐘,逾時自動取消。

http
POST /api/v1/orders/topup
Authorization: Bearer $TOKEN
Content-Type: application/json

{
  "offerId": "{type=sell 的報價 ID}",
  "fiatAmount": 1000,
  "refId": "貴司側冪等鍵(選填,≤128 字元)"
}
參數型別必填說明
offerIdstring (uuid)是type=sell 的報價 ID
fiatAmountnumber是法幣金額(需在報價 min–max 範圍內)
refIdstring ≤128否商戶側冪等鍵:同一 refId 重送不會重複建單(見下方冪等說明)

🔁 refId 冪等語義(建議後端建單一律攜帶)

帶 refId 建單時,若同一 refId 已建過訂單(含並發重送),系統回傳原訂單: HTTP 200 + 原單完整資料 + "idempotentHit": true,不會重複建單、不會重複凍結錢包 escrow。 適用於逾時重試、網路中斷後重送等場景。新建訂單維持回 201;不帶 refId 行為與舊版完全一致。 refId 在貴商戶內唯一(買單/賣單共用同一命名空間),但回查僅限同一客戶:同商戶其他客戶已用過的 refId 會回 409 REF_ID_CONFLICT(不回傳他人訂單任何欄位);同客戶重送但 offerId / 金額與原單不一致會回 409 REF_ID_MISMATCH。

成功回應(201):

json
{
  "success": true,
  "orderId": "....",
  "orderNo": "TP2608....",
  "status": "pending",
  "crypto": "USDT",
  "cryptoAmount": "27.39726027",
  "currency": "THB",
  "fiatAmount": "1000.00",
  "rate": "36.50000000",
  "expiresAt": "2026-08-12T02:30:00.000Z",
  "merchantTransactionUrl": "https://...渠道建單回傳的付款網址(可能一次性、有時效,請直接導向,不要快取或改寫)"
}
HTTP錯誤說明
400INSUFFICIENT_PLATFORM_BALANCE貴商戶錢包可用餘額不足(對客戶回通用文案;同時發送錢包不足 Webhook 給貴司)
400OFFER_NOT_FOUND報價不存在或已下架
400AMOUNT_BELOW_MIN / AMOUNT_ABOVE_MAX金額低於/超過報價 min–max 範圍(message 含具體界限)
400OFFER_RATE_UNAVAILABLE動態報價的匯率暫時不可用,請稍後再試
409REF_ID_CONFLICT / REF_ID_MISMATCHrefId 已被同商戶其他客戶使用 / 同客戶重送但參數(offerId、金額)與原單不一致;不回傳任何訂單資料,請改用新的 refId

客戶確認已付款:POST /api/v1/orders/:id/confirm-paid

僅適用於買單(topup)且狀態為 pending。呼叫後訂單轉為 paid,等待渠道確認。

http
POST /api/v1/orders/{orderId}/confirm-paid
Authorization: Bearer $TOKEN
Content-Type: application/json

{
  "paymentRef": "付款備註/末五碼(選填,亦接受欄位名 ref)"
}
  • 只能確認自己的訂單:訂單不存在或非本人一律回 404(避免訂單存在性探測)
  • 狀態不是 pending、或對賣單呼叫 → 400 Invalid status

建立賣單:POST /api/v1/orders/withdraw

建單時原子凍結客戶資金帳戶的 USDT,渠道付法幣給客戶後放行。 幣種由報價決定,body 傳入 crypto 欄位會被忽略。

http
POST /api/v1/orders/withdraw
Authorization: Bearer $TOKEN
Content-Type: application/json

{
  "offerId": "{type=buy 的報價 ID}",
  "cryptoAmount": 100,
  "refId": "貴司側冪等鍵(選填,≤128 字元)"
}
參數型別必填說明
offerIdstring (uuid)是type=buy 的報價 ID
cryptoAmountnumber是賣出幣量
refIdstring ≤128否商戶側冪等鍵:同一 refId 重送 → 回原單 200 + idempotentHit:true,不重複建單、不重複凍結客戶餘額(語義同買單,見上方說明)

成功回應(201)——同一份訂單資料同時掛在 order 與 data 兩個 key(相容舊版呼叫方):

json
{
  "success": true,
  "order": {
    "id": "....",
    "orderNo": "WD2608....",
    "status": "pending",
    "crypto": "USDT",
    "cryptoAmount": "100.00000000",
    "currency": "THB",
    "fiatAmount": "3650.00",
    "rate": "36.50000000"
  },
  "data": { "...同 order": "" }
}
HTTP錯誤說明
400INSUFFICIENT_BALANCE客戶資金帳戶可用餘額不足,無法建立賣單
400OFFER_NOT_FOUND / OFFER_RATE_UNAVAILABLE報價不存在或已下架 / 動態匯率暫時不可用
409REF_ID_CONFLICT / REF_ID_MISMATCH同買單:refId 被同商戶其他客戶使用 / 重送參數與原單不一致

商戶側建立賣單(相容端點):POST /api/v1/platform/withdraw

較早期提供給商戶後端的 server-to-server 賣單端點,僅接受商戶 API Key(header x-api-key,亦相容舊名 x-platform-key),客戶以 body 的 platformUserId 指定。 行為與上方 POST /api/v1/orders/withdraw 相同 (原子凍結該客戶站內餘額、渠道付法幣後放行),但不支援 refId 冪等,且 platformTxId 為必填。新對接請一律改用 /api/v1/orders/withdraw(API Key + x-user-id 亦可呼叫),本端點僅為既有整合相容保留。

http
POST /api/v1/platform/withdraw
x-api-key: $KEY
Content-Type: application/json

{
  "platformUserId": "您商戶的客戶唯一 ID",
  "offerId": "{type=buy 的報價 ID}",
  "cryptoAmount": 100,
  "platformTxId": "貴司側交易 ID(必填,僅記錄用、不做冪等)"
}

成功回應(201):{ success, orderId, orderNo, status: "pending", cryptoAmount, fiatAmount, currency, merchantTransactionUrl }; 餘額不足回 400 INSUFFICIENT_BALANCE(message 含 have / need)。 同組路由另有 GET /api/v1/platform/orders/:orderId(以 API Key 查詢 SOHO Wallet 上的訂單) 與 POST /api/v1/platform/topup-notify(舊版對帳回報,現行流程不需呼叫)。

鏈上充提(TRC-20)

本章各端點以 TRC-20(TRON)為預設鏈。多鏈(BEP20 / ARB)支援見「多鏈提幣(BEP20 / ARB)」與「多鏈充值(BEP20 / ARB)」章節, 既有呼叫(不帶 chain 參數)行為完全不變。

取得充幣地址:GET /api/wallet/deposit/address

每個客戶首次呼叫時自動產生專屬 TRON 地址,之後呼叫回傳同一地址(可重複充值)。 另有選填 chain 參數 (enum TRC20 | BEP20 | ARB,預設 TRC20,不帶時行為與現狀完全相同),BEP20 / ARB 充值地址見「多鏈充值(BEP20 / ARB)」章節。

bash
curl "/api/wallet/deposit/address?crypto=USDT" \
  -H "Authorization: Bearer $TOKEN"
json
{
  "data": {
    "address": "T....(34 碼 TRON 地址)",
    "crypto": "USDT",
    "network": "TRON TRC-20",
    "warning": "請僅發送 TRC-20 USDT,否則資產將永久丟失"
  }
}

提幣手續費/限額查詢:GET /api/wallet/withdraw/config

提幣前可先查詢現行手續費與限額(不需等到 400 錯誤才知道界限)。 回傳值與 POST /api/wallet/withdraw 實際執行檢查的值同源,適合前端顯示與送出前預檢。

bash
curl /api/wallet/withdraw/config \
  -H "Authorization: Bearer $TOKEN"
json
{
  "network": "TRC20",
  "configs": [
    {
      "chain": "TRC20",             // 鏈別(多鏈提幣新增欄位,見「多鏈提幣」章節)
      "crypto": "USDT",
      "fee": "1.00000000",          // 固定手續費
      "percentFee": "0.5000",       // 百分比手續費(%,0–100);手續費 = fee + amount × percentFee%
                                    // 扣除總額 = amount + 手續費;鏈上實收 = amount
      "minAmount": "10.00000000",   // 單筆最小提幣金額
      "maxAmount": null,            // 單筆最大金額(null = 無單筆上限)
      "dailyLimit": 10000,          // 每日提幣限額(UTC 日累計,排除失敗/駁回筆數)
      "reviewThreshold": 1000       // 超過此金額需人工審核(pending_review)
    }
  ]
}

鏈上提幣:POST /api/wallet/withdraw

從鏈上錢包提領至外部 TRON 地址。金額為 decimal 字串; 手續費、單筆最小/最大金額、每日限額與審核門檻可由上方 config 端點事前查詢; 當日累計(含本筆)超過審核門檻的提幣會進入人工審核(狀態 pending_review); 以平台 API Key + x-user-id 發起的提幣則一律進入人工審核,除非該平台已設定 IP 白名單(allowed_ips)且請求來源命中(v1.14.3)。 客戶已啟用 2FA 時需帶 x-2fa-token。 body 另有選填 chain 參數 (enum TRC20 | BEP20 | ARB,預設 TRC20,不帶時行為與現狀完全相同),BEP20 / ARB 提幣見「多鏈提幣(BEP20 / ARB)」章節。

http
POST /api/wallet/withdraw
Authorization: Bearer $TOKEN
x-2fa-token: {6 位驗證碼,客戶已啟用 2FA 時必填}
Content-Type: application/json

{
  "crypto": "USDT",
  "amount": "100",
  "toAddress": "T....(外部 TRON 地址)"
}

成功回應(201):

json
{
  "id": "....",
  "status": "pending",
  "amount": "100",
  "fee": "1.00000000",
  "netAmount": "100.00000000",
  "toAddress": "T....",
  "crypto": "USDT",
  "reviewRequired": false,
  "createdAt": "2026-08-12T02:00:00.000Z"
}
HTTP錯誤說明
400INVALID_ADDRESS / AMOUNT_BELOW_MIN / AMOUNT_ABOVE_MAX / WALLET_NOT_FOUND / INSUFFICIENT_BALANCE地址格式錯誤 / 低於最小金額 / 超過最大金額 / 尚無錢包 / 餘額不足(需涵蓋 amount + fee);error 欄位為 Bad Request,code 欄位為左列碼,message 含具體原因
400DAILY_LIMIT_EXCEEDED超過每日提幣限額(message 含限額與今日已用額度;error 欄位為舊值 DailyLimitExceeded 相容保留)
4032FA_REQUIRED / 2FA_INVALID客戶已啟用 2FA 但未帶/帶錯 x-2fa-token
403VAULT_OWNER_LOGIN_REQUIRED錢包帳號提幣僅限本人登入操作,客戶 Token / API Key 一律拒絕

📡 提幣狀態會主動推送 Webhook,不需輪詢

提幣完成 / 失敗 / 審核駁回時,系統會向貴司 Webhook URL 推送 wallet.withdraw.completed / failed / rejected 事件(含 tronTxHash,見「事件與 Payload」章節),後端對帳請以 Webhook 為準; GET /api/wallet/withdraw/history 保留作為補漏對帳與 UI 展示用途。 審核通過(approve)本身不發事件,最終結果以 completed / failed 為準。

歷史紀錄查詢

端點說明
GET /api/wallet/deposit/history充幣紀錄(含鏈上 txHash、確認狀態)
GET /api/wallet/withdraw/history提幣紀錄(含審核/處理狀態)
GET /api/wallet/history充提合併列表(每筆帶 type: deposit | withdrawal)

均支援 page / limit 分頁(limit 上限 100),deposit/withdraw history 另支援 crypto 過濾。

提幣地址簿

端點說明
GET /api/wallet/addresses列出已儲存地址(可用 crypto 過濾)
POST /api/wallet/addresses新增地址 {crypto, address, label?},每幣種上限 20 筆
DELETE /api/wallet/addresses/:id刪除地址(只能刪自己的,否則 404)

多鏈提幣(BEP20 / ARB)

鏈上提幣在既有 TRC-20(TRON)之外,支援 BEP20(BSC / BNB Smart Chain)與 ARB(Arbitrum One)USDT 提幣。 既有 API 僅做「加法」擴充——不帶 chain 參數的現有呼叫,請求、回應與錯誤碼行為完全不變, 貴司無需任何改動即可繼續使用 TRC-20。

✅ BEP20 / ARB 提幣已於主網上線

按商戶逐家開通(預設關閉,與充值側開通狀態相互獨立),如需使用請聯繫站主申請開通。 未開通前帶 chain=BEP20 / ARB 會回 400 UNSUPPORTED_CHAIN。充值側見「多鏈充值(BEP20 / ARB)」章節。

支援鏈清單

chain 值網路地址格式手續費可用性
TRC20TRON(TRC-20)T 開頭、34 碼1 USDT預設,所有商戶可用
BEP20BSC(BNB Smart Chain)0x + 40 碼 hex(EIP-55)1 USDT需商戶開通;僅支援 USDT
ARBArbitrum One0x + 40 碼 hex(EIP-55,與 BEP20 同格式、不同網路)1 USDT需商戶開通;僅支援 USDT

功能探測:GET /api/wallet/withdraw/config

configs[] 每條目新增 chain 欄位(加法)。 TRC20 條目恆在且排前;BEP20 / ARB 條目僅在貴司商戶開通該鏈後才會出現(附加在陣列尾部)—— 前端可以此作為功能探測:有對應鏈的條目才顯示該鏈提幣入口,無需寫死開關。 頂層 network: "TRC20" 欄位保留不動(相容)。

json
{
  "network": "TRC20",
  "configs": [
    {
      "chain": "TRC20",             // 新增欄位;既有條目恆為 TRC20 且排前
      "crypto": "USDT",
      "fee": "1.00000000",
      "minAmount": "10.00000000",
      "maxAmount": null,
      "dailyLimit": 10000,
      "reviewThreshold": 1000
    },
    {
      "chain": "BEP20",             // 僅商戶開通 BEP20 後出現(功能探測)
      "crypto": "USDT",
      "fee": "1.00000000",
      "minAmount": "10.00000000",
      "maxAmount": null,
      "dailyLimit": 10000,          // 日限額按鏈分別計算(TRC20 / BEP20 各自累計)
      "reviewThreshold": 1000
    }
  ]
}

另支援 ?chain=TRC20|BEP20|ARB query 過濾,只回指定鏈的條目。

⚠️ 若貴司程式假設「crypto 唯一」

BEP20 / ARB 開通後,configs[] 會同時存在多條 USDT 條目(TRC20 + BEP20 + ARB)。 若現有程式以「每幣種只有一條」的假設遍歷,請改以 (chain, crypto) 複合鍵識別, 或使用 ?chain= 過濾。

提幣:POST /api/wallet/withdraw 的 chain 參數

body 新增選填 chain 參數 (enum "TRC20" | "BEP20" | "ARB",預設 TRC20)。 其餘流程(餘額檢查、手續費、日限額、大額人工審核、2FA)與 TRC-20 提幣完全一致。

  • BEP20 / ARB 地址格式:0x + 40 碼 hex;混合大小寫時須通過 EIP-55 checksum 驗證,全小寫 / 全大寫視為未帶 checksum、予以接受(交易所地址常為全小寫)。兩鏈地址格式相同,請務必確認客戶提供的是目標鏈的地址
  • 回應與入帳的 toAddress 一律正規化為 EIP-55 checksum 格式
  • 手續費固定 1 USDT、單筆最小 10 USDT(實際值以 withdraw/config 回傳為準,兩者同源不會 drift)
  • BEP20 / ARB 僅支援 USDT(其他幣種回 400 UNSUPPORTED_CHAIN_CRYPTO);ARB 上的 USDT 為 6 位小數,金額仍以 decimal 字串傳遞,貴司無需處理精度差異
http
POST /api/wallet/withdraw
Authorization: Bearer $TOKEN
x-2fa-token: {6 位驗證碼,客戶已啟用 2FA 時必填}
Content-Type: application/json

{
  "crypto": "USDT",
  "amount": "100",
  "toAddress": "0x....(外部 BSC 地址,EIP-55)",
  "chain": "BEP20"
}

成功回應(201)結構與 TRC-20 提幣相同(toAddress 為 EIP-55 正規化後的地址)。 GET /api/wallet/withdraw/history 每筆新增 chain 欄位 (舊資料為 TRC20);鏈上 hash 沿用既有 tronTxHash 欄位名 (BEP20 / ARB 筆數存的是 0x hash),請搭配 chain 判讀。

新增錯誤碼

HTTP錯誤碼(code)說明
400UNSUPPORTED_CHAINchain 未開放(貴司商戶未開通該鏈);message 為 Chain BEP20 is not available for withdrawal(ARB 同理)
400UNSUPPORTED_CHAIN_CRYPTO該鏈支援但幣種未開(BEP20 / ARB 僅 USDT)
400CHAIN_TEMPORARILY_DISABLED運維暫停該鏈提幣,請稍後重試
400INVALID_ADDRESS(沿用)message 按 chain 區分:TRC20 → “Invalid TRON address (must start with T and be 34 characters)”(原文不變);BEP20 / ARB → “Invalid BEP20 address (must be a valid 0x EVM address, EIP-55 checksum)”(ARB 訊息以 ARB 取代 BEP20)

Webhook wallet.withdraw.* payload 變更

鏈上提幣事件(completed / failed / rejected)payload 新增兩個欄位(純加法, HMAC 簽名對原始 body 計算、驗簽不受影響):

欄位說明
chain新增,一律填("TRC20" | "BEP20" | "ARB");既有 TRC-20 事件也會帶
txHash新增,鏈無關交易 hash;有 hash 時填(TRC20 時與 tronTxHash 同值;BEP20 / ARB 為 0x hash)
tronTxHash保留(deprecated):TRC20 事件照舊填(既有消費方零影響);BEP20 / ARB 事件一律為 null(避免 0x hash 被誤當 TRON hash 使用);新對接請一律改讀 chain + txHash

BEP20 提幣完成事件範例:

json
{
  "eventId": "550e8400-e29b-41d4-a716-446655440005",
  "event": "wallet.withdraw.completed",
  "withdrawId": "uuid",
  "platformUserId": "您的客戶 ID",
  "crypto": "USDT",
  "amount": "100.00000000",
  "fee": "1.00000000",
  "netAmount": "100.00000000",
  "toAddress": "0x....(EIP-55)",
  "tronTxHash": null,               // BEP20 事件恆為 null(相容保留)
  "chain": "BEP20",
  "txHash": "0x....(BSC 交易 hash)",
  "status": "completed",
  "timestamp": "2026-01-01T00:00:00.000Z"
}

💡 對接建議

新對接請一律讀 chain + txHash; 區塊鏈瀏覽器連結請按 chain 分流(TRC20 → Tronscan,BEP20 → BscScan,ARB → Arbiscan)。 既有只讀 tronTxHash 的消費方在 TRC-20 事件上完全不受影響。

多鏈充值(BEP20 / ARB)

鏈上充值在既有 TRC-20(TRON)之外,支援 BEP20(BSC / BNB Smart Chain)與 ARB(Arbitrum One)USDT 充值: 每客戶專屬 0x 充值地址,轉入後自動入帳並推送 Webhook。既有 API 僅做「加法」擴充——不帶 chain 參數的現有呼叫,請求、回應與錯誤碼行為完全不變, 貴司無需任何改動即可繼續使用 TRC-20 充值。本章以 BEP20 為主要範例,ARB 除鏈名、確認數與瀏覽器外行為相同。

✅ BEP20 / ARB 充值已於主網上線

功能已完成主網全鏈路驗證,按商戶逐家開通 (預設關閉,與提幣側開通狀態相互獨立),如需使用請聯繫站主申請。 未開通前呼叫 chain=BEP20 / chain=ARB 會回 400 UNSUPPORTED_CHAIN,前端可以此判斷是否顯示入口。

取得 BEP20 充值地址:GET /api/wallet/deposit/address 的 chain 參數

query 新增選填 chain 參數 (enum "TRC20" | "BEP20" | "ARB",預設 TRC20)。 首次呼叫自動簽發專屬 0x 地址,之後回傳同一地址(固定、可重複充值); 與 TRC-20 地址互獨立。BEP20 與 ARB 由同一組 EVM 金鑰派生,同一客戶兩條 EVM 鏈的 0x 地址相同, 系統以 chain 區分入帳通道,客戶只需確認在正確網路轉入。僅支援 USDT (其他幣種回 400 UNSUPPORTED_CHAIN_CRYPTO)。ARB 回應的 network 為 "Arbitrum One"。

bash
curl "/api/wallet/deposit/address?crypto=USDT&chain=BEP20" \
  -H "Authorization: Bearer $TOKEN"
json
{
  "data": {
    "address": "0x....(42 碼 0x 地址,EIP-55)",
    "crypto": "USDT",
    "chain": "BEP20",
    "network": "BSC (BEP-20)",
    "warning": "請僅發送 BSC (BEP-20) USDT,否則資產將永久丟失"
  }
}

不帶 chain 的既有呼叫回傳 TRON 地址、既有欄位逐字不變,另新增chain: "TRC20" 欄位(加法)。

入帳規則

  • 最低入帳金額 1 USDT:單筆轉入低於 1 USDT 視為灰塵,不入帳也不退還(金額不累計,請勿拆小額多筆轉入)
  • 入帳確認數:BEP20 15 個區塊(BSC 出塊約每秒 1 塊,體感約 15–60 秒);ARB 300 個區塊(約 0.25 秒/塊,體感約 1–2 分鐘);均快於 TRC-20(v1.6.3 起掃描間隔預設 5 分鐘,約 5–10 分鐘)
  • 只認官方 USDT 合約的標準轉帳(BSC:BSC-USD,18 位小數;Arbitrum One:官方 USDT,6 位小數):假冒代幣、其他代幣或直接發送 BNB / ETH 一律不入帳,且可能無法取回
  • 到帳進入與 TRC-20 同一個主帳本餘額(chain 只是出入金通道屬性,餘額不分鏈)
  • 同一地址可重複充值;短時間多筆轉入逐筆入帳、逐筆發 webhook(含同一筆交易內多筆轉帳)

充值歷史:GET /api/wallet/deposit/history 新欄位

每筆新增(加法,既有欄位不變):

欄位說明
chain"TRC20" | "BEP20" | "ARB"(舊資料為 TRC20)
txHash鏈中立交易 hash(BEP20 / ARB 必帶 0x hash;TRC-20 舊資料可能為 null);新對接請讀此欄位,舊欄位 tronTxHash 保留不動
logIndexEVM 交易內的 log 序號(同一筆 tx 多筆轉帳時區分用;TRC-20 為 null)

另支援 ?chain=TRC20|BEP20|ARB query 過濾(不帶 = 全部,舊呼叫行為不變)。

Webhook wallet.deposit.completed payload 變更

充值到帳事件 payload 新增欄位(純加法,HMAC 簽名對原始 body 計算、驗簽不受影響), 規則與提幣事件(wallet.withdraw.*)一致:

欄位說明
chain新增,一律填("TRC20" | "BEP20" | "ARB");既有 TRC-20 事件也會帶
txHash新增,鏈無關交易 hash:BEP20 / ARB 事件必帶(0x hash);TRC-20 有 hash 時與 tronTxHash 同值
tronTxHash保留(deprecated):TRC-20 事件照舊有值才出現(既有消費方零影響);BEP20 / ARB 事件不帶此鍵(避免 0x hash 被誤當 TRON hash 使用);新對接請一律改讀 chain + txHash
amount(格式統一)一律為 8 位小數字串(如 "5.00000000"),與 wallet.withdraw.* 事件同格式;請勿依賴小數位數做字串比對,建議以 decimal 解析

BEP20 充值到帳事件範例:

json
{
  "eventId": "550e8400-e29b-41d4-a716-446655440006",
  "event": "wallet.deposit.completed",
  "depositId": "uuid",
  "platformUserId": "您的客戶 ID",
  "crypto": "USDT",
  "amount": "25.00000000",
  "chain": "BEP20",
  "txHash": "0x....(BSC 交易 hash)",
  "timestamp": "2026-01-01T00:00:00.000Z"
}

與 TRC-20 充值的行為對照

面向TRC-20(TRON)BEP20(BSC)ARB(Arbitrum One)
地址格式T 開頭、34 碼0x + 40 碼 hex(EIP-55)0x + 40 碼 hex(EIP-55,與 BEP20 同地址)
最低入帳1 USDT(低於不入帳)1 USDT(低於不入帳、不退還)1 USDT(低於不入帳、不退還)
到帳體感約 5–10 分鐘(v1.6.3 起掃描間隔預設 5 分鐘)15 確認,約 15–60 秒300 確認,約 1–2 分鐘
逐筆入帳短時間多筆可能合併為一筆(金額正確)逐筆入帳、逐筆 webhook(含 logIndex 區分)同 BEP20
webhook hash 欄位tronTxHash(可能缺)+ txHash 同值txHash 必帶;tronTxHash 不出現同 BEP20
支援幣種USDTUSDTUSDT

💡 對接建議

充值到帳以 Webhook 為準(不需輪詢);區塊鏈瀏覽器連結請按 chain 分流 (TRC20 → Tronscan,BEP20 → BscScan,ARB → Arbiscan)。商戶開通前, 前端可先依本章適配、以 UNSUPPORTED_CHAIN 錯誤碼作功能探測。

閃兌(幣幣兌換)

⚠ 選配模組(尚未開放),本章僅供預覽

跨鏈幣幣兌換模組。未啟用任何供應商時,客戶端一律回 503 SWAP_UNAVAILABLE, 建議先呼叫 availability 決定是否顯示入口。

端點認證說明
GET /api/swap/availability無閃兌是否開放
GET /api/swap/currencies無可兌換幣種清單(跨供應商聯集)
GET /api/swap/quotes無多供應商比價;query: from、to、amount
POST /api/swap/orders需要建單 {provider, from, to, amount, payoutAddress?, refundAddress?}
GET /api/swap/orders需要我的閃兌訂單(page / limit)
GET /api/swap/orders/:id需要訂單詳情;每次呼叫同步供應商最新狀態,適合輪詢
bash
curl "/api/swap/quotes?from=usdttrc20&to=btc&amount=100" \
  -H "Authorization: Bearer $TOKEN"
HTTP錯誤碼說明
503SWAP_UNAVAILABLE閃兌未開放(無啟用中的供應商)
400SWAP_VALIDATION參數不合法(幣種不支援、金額超出範圍等)
400INSUFFICIENT_BALANCEsell 方向扣帳時資金帳戶餘額不足
502SWAP_PROVIDER_ERROR供應商暫時無法服務,請稍後重試

2FA 驗證(Email OTP)

客戶可選擇性啟用 Email 2FA。啟用後,高風險操作(鏈上提幣、to_platform 劃轉)必須先取得 6 位驗證碼,並以 x-2fa-token header 帶入該次請求;未啟用 2FA 的客戶不受影響。

端點說明
GET /api/2fa/status查詢 2FA 狀態(enabled / verified / method / 遮罩後的 email)
POST /api/2fa/enable啟用:{method: "email", email} → 發送驗證碼
POST /api/2fa/verify驗證:{token, purpose}(啟用流程 purpose 用 enable_2fa)
POST /api/2fa/send-otp操作前索取驗證碼:{purpose: "withdraw" | "transfer" | "whitelist" | "enable_2fa"}
POST /api/2fa/disable關閉 2FA

高風險操作流程

  1. 1呼叫 POST /api/2fa/send-otp(purpose 對應操作:提幣用 withdraw、劃轉用 transfer)
  2. 2客戶自 Email 取得 6 位驗證碼
  3. 3發起操作時以 x-2fa-token header 帶入驗證碼
bash
curl -X POST /api/2fa/send-otp \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"purpose": "withdraw"}'

⚠️ 發送限流與鎖定

OTP 發送有每帳號限流;連續驗證失敗達上限會暫時鎖定。兩者均回 429 TOO_MANY_REQUESTS, 回應含 retryAfter(秒)與 Retry-After header,請依指示退避重試。

Stellabit — Developer Documentation