10 分鐘接通
給第一次接的商戶工程師:照下面四步,從拿 Key 到收到「訂單完成」通知。每步一個 curl,細節都連到後面各節。想先不碰真實渠道,可直接跳到最後一段「先用沙盒渠道試」。
API Key 只放在貴司後端,不要放進前端或客戶端程式。下面的 curl 都用環境變數,先在終端機貼上這兩行(換成您自己的值),之後每個 curl 整行可直接複製執行;JSON 內的 {…} 請換成上一步回應的值。
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:渠道 → 試算 → 建單
先列出可用渠道(詳見):
curl "https://stellabit.cc/api/v1/channels?currency=THB" \
-H "x-api-key: $KEY"回應節錄(200):
{ "channels": [ { "channelId": "渠道 ID", "name": "渠道名稱", "fiat": "THB", "referenceRate": "36.52" } ], "serverTime": "..." }客戶選好渠道與金額後試算,取得報價單號 quoteId(詳見):
curl -X POST https://stellabit.cc/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):
{ "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 形狀):
curl -X POST https://stellabit.cc/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": "365.20", "merchantTransactionUrl": "https://渠道付款頁/...", "channelOrderId": "渠道單號", "quoteId": "..." }把客戶導向 merchantTransactionUrl 付款;不要快取或改寫這個網址。報價過期會回 409 QUOTE_EXPIRED,回應已附 newQuote:讓客戶確認新價後,直接用 newQuote.quoteId 重送建單即可,不必再打一次試算(範例)。
③ 收「訂單完成」通知(或查單)
客戶付完款、渠道回打後,支付中心會 POST 通知到步驟①填的網址,事件為 topup.completed(渠道端看到的同一件事叫 order.completed)。請用 HMAC 驗簽(header X-Stellabit-Signature,以原始 body 計算)確認來源再入帳。也可以主動查單:
curl https://stellabit.cc/api/v1/orders/{orderId} \
-H "x-api-key: $KEY" \
-H "x-user-id: $USER_ID"回應節錄(200):
{ "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 為準,查單只用來補漏與畫面顯示(見 訂單狀態與查詢、重試與冪等)。
④ 提幣、餘額、流水
客戶餘額(詳見):
curl https://stellabit.cc/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前往 開戶頁 開戶(免審核,開戶即有錢包)。
- 2登入商戶後台,進入 /console/integration(對接設定),自助產生 API Key;API Key 只顯示一次,請保存在商戶後端。
- 3同一頁設定接收通知的 Webhook URL,並可發送測試推送(見「Webhook 通知」)。
- 4(選用)在同一頁設定 API Key 的 IP 白名單(見「IP 白名單」)。
⚠️ API Key 安全
API Key 等同商戶全部客戶的操作權限,只能放在商戶後端;瀏覽器端請使用短效期的客戶 Token(見「總覽與認證」)。
認證方式與請求標頭詳見「商戶系統對接 → 總覽與認證」。
接第一個渠道
商戶要有至少一個「上工中」的渠道,客戶才有得選。渠道由商戶在後台替渠道建立與維護(渠道本身不登入後台)。
- 1到 /console/channels/new 選「系統型渠道」(渠道有自己的系統;類型建立後不能切換)。
- 2依設定精靈六步完成:基本資料 → 渠道給的東西(詢價網址、建單網址、通知網址,必要時欄位映射)→ 手續費(選填:一個費用 %,正=多收、負=讓利)→ 測試連線(詢價+建單) → 憑證與資料卡 → 上線。
- 3「憑證與資料卡」會產生渠道 Key+渠道 Secret(只顯示一次)與 Webhook Secret,連同「渠道對接規格」一頁一併交給渠道的技術人員。
- 4渠道完成實作後,在後台按「測試連線」(test-quote)與「回打測試」(test-callback),全部通過再上線。
渠道沒有系統、由商戶手動維護報價與確認收款的「人工報價渠道」另走 /console/channels/new/manual,屬參考中的「人工報價牌」附錄,與主線完全分開。
不想看文字?支付流程圖與各欄位的白話說明也在 /console/channels/flow。
渠道需要實作什麼,見「渠道對接規格」。
十步支付流程
三方:客戶/商戶系統/支付渠道,其中商戶系統=商戶+支付中心(不含渠道)。流程分兩張圖:先看示意圖掌握全貌,需要實作時再看開發圖。兩張都是通用流程(不綁定特定渠道),之下為文字版逐步說明。
示意圖(三泳道:客戶/商戶系統/支付渠道)
給產品、營運與初次接觸的人:一眼看懂一筆單從探價、下單、付款到回打確認怎麼走。支付中心在商戶系統內運作,所以不單獨畫成一條泳道。
開發圖(四泳道:客戶/商戶/支付中心/支付渠道)
給工程師:把商戶系統拆成「商戶」與「支付中心」兩條泳道,標出每一步呼叫的端點、各設定欄位用在哪、錯誤分支與渠道單號(channelOrderId)的流向。
時間由上往下。實線=呼叫,虛線=回應/通知。灰色圓點為該步驟用到的設定欄位。
① 商戶 → 支付中心
商戶向支付中心取渠道列表(含參考匯率)
① 支付中心 → 渠道
支付中心向各渠道探參考匯率(快取 45 秒),渠道回參考匯率
② 客戶 → 商戶
客戶選渠道、輸入金額
③ 商戶 → 支付中心
商戶向支付中心試算
③ 支付中心 → 渠道
支付中心向渠道詢價,渠道回「參考匯率」(含有效期);支付中心回商戶參考匯率+報價單號+有效期
③ 商戶
商戶自訂客戶匯率或直接定法幣數額(與參考匯率的差距須在手續費上限內)
依渠道手續費設定或每筆指定;渠道只收法幣數額,客戶匯率不會送給渠道
④ 客戶 → 商戶
客戶確認,商戶帶報價單號+客戶匯率或法幣數額下單
報價過期→回新參考匯率,客戶再確認一次
⑤ 支付中心
建單並凍結商戶錢包
⑤ 支付中心 → 渠道
支付中心向渠道建單(法幣數額=商戶定;同步 POST 建單網址,8 秒內回應,帶簽章與 Idempotency-Key)
失敗或逾時:解凍商戶錢包,回商戶 503 CHANNEL_CREATE_FAILED
⑥ 渠道 ⇢ 支付中心
渠道回付款網址(+渠道單號);支付中心回訂單給商戶(單號+付款網址)
商戶把客戶導向該付款網址(放在 merchantTransactionUrl,可能一次性、有時效)
⑥ 商戶 ⇢ 客戶
商戶導客戶前往付款網址
⑦ 客戶 → 渠道
客戶開啟付款網址付款、渠道收款
⑧ 渠道 → 支付中心
渠道回打支付中心(帶我方單號+渠道單號)
⑨ 支付中心 ⇢ 商戶
核對金額、劃帳;⑩ 通知商戶(含渠道單號)
等值→完成 多付→完成並請渠道退差額 少付→作廢重建
渠道要做的三件事
1. 提供詢價介面(Quote URL)
照詢價介面規格實作,回價格與有效期
2. 提供建單介面(Create Order URL)
收支付中心簽章的建單請求,回付款網址(固定付款頁每次回同一個網址即可)
3. 完成後回打(Callback)
拿到渠道 Key+渠道 Secret 後,照說明文件的簽章規則回打支付中心
不經手資金、不碰私鑰
流程十步(四泳道:客戶/商戶/支付中心/渠道)
- 1商戶向支付中心取渠道列表(GET /api/v1/channels,含參考匯率 referenceRate)
- 2客戶在貴司介面選渠道、輸入金額
- 3商戶向支付中心試算(POST /api/v1/quotes)→ 支付中心向渠道詢價 → 回參考匯率+報價單號(quoteId)+有效期
- 4商戶自訂客戶匯率或法幣數額(可選;與參考匯率的價差須在上限 maxSpreadPct 內;未指定時依預設價差:每筆指定 > 渠道預設 > 商戶預設 > 參考價原價)。渠道只認法幣數額,建給渠道的 fiatAmount = 商戶定的數額;商戶與渠道的差額雙方自行結算,平台不介入
- 5客戶確認,商戶帶 quoteId 下單(POST /api/v1/orders/topup;可選帶 customerRate 自訂價;賣單 customerRate/fiatAmount 皆可)
- 6支付中心建單、凍結商戶錢包,並向渠道建單(同步 POST 建單網址,8 秒內回應)
- 7渠道回付款網址(+渠道單號 channelOrderId);支付中心回訂單給商戶(訂單編號+付款網址 merchantTransactionUrl+金額/有效期);商戶導客戶前往該付款網址
- 8客戶在付款網址付款,渠道收款
- 9渠道回打支付中心(渠道 Key+渠道 Secret 簽章;帶我方單號 orderId,建議同時帶渠道單號 channelOrderId)
- 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 + 客戶 ID | x-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 | 錯誤碼 | 行為 |
|---|---|---|
| 403 | VAULT_OWNER_TOKEN_FORBIDDEN | 不得為錢包帳號簽發 widget token(POST /api/widget/token 直接拒絕) |
| 403 | VAULT_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
| 欄位 | 類型 | 必填 | 說明 |
|---|---|---|---|
userId | string | ✅ | 您商戶的客戶唯一 ID |
expiresIn | number | ❌ | Token 有效期(秒),預設 3600,範圍 60–86400 |
Response
{
"token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
"expiresIn": 3600,
"widgetUrl": "https://stellabit.cc/widget/account?token=eyJ..."
}完整範例
POST https://stellabit.cc/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 計」。渠道只認法幣數額,渠道報價不等於成交價:貴司可自訂給客戶的匯率或法幣數額(見「④ 下單」),貴司與渠道之間的差額由雙方自行結算,平台不介入。
curl "https://stellabit.cc/api/v1/channels?currency=THB&type=buy&crypto=USDT" \
-H "x-api-key: $KEY" \
-H "x-user-id: $USER_ID"回應(200):
{
"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 用環境變數,先貼上這兩行即可整行複製:
export KEY=貼上您的商戶API_Key
export USER_ID=customer-001curl -X POST https://stellabit.cc/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):
{
"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_AMOUNT | 100 | 參考價探價用的 USDT 數量(全站固定) |
| REFERENCE_CACHE_TTL_SEC | 45 | 參考價快取秒數 |
| REFERENCE_PROBE_MAX_PER_MIN | 6 | 每個渠道每分鐘最多探價次數 |
| QUOTE_HOLD_MAX_MS | 300000 | 報價最長保留時間(5 分鐘) |
| QUOTE_ORDER_MIN_REMAINING_MS | 30000 | 下單時報價至少要剩的時間(30 秒) |
| QUOTE_RATE_LIMIT_USER_PER_MIN | 10 | 每客戶每分鐘試算次數 |
| QUOTE_RATE_LIMIT_PLATFORM_PER_MIN | 120 | 每商戶每分鐘試算次數 |
渠道自己的上線/下線開關見 /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 不變。
// 買單:渠道參考匯率 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": "..." }curl -X POST https://stellabit.cc/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):
{
"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 沿用):
# 上面 409 回應節錄:newQuote.quoteId = "新的報價單號"
curl -X POST https://stellabit.cc/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)範例:
curl -X POST https://stellabit.cc/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):
{
"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 皆可、二擇一,其餘規則與錯誤碼同上)範例:
curl -X POST https://stellabit.cc/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):
{
"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"
}| 新路徑參數 | 型別 | 必填 | 說明 |
|---|---|---|---|
channelId | string (uuid) | 否 | 系統型渠道;省略 → 商戶預設渠道(後台「設定」);兩者皆無 → 400 CHANNEL_REQUIRED |
cryptoAmount | string(decimal) | 是 | 要買/賣的幣數(字串,數字亦收;精度超過幣種上限 → 400 INVALID_AMOUNT_PRECISION) |
crypto / network / currency | string | crypto、currency 建議帶 | crypto 例 USDT;network 例 TRC20;currency 例 THB(未帶時用渠道預設) |
externalOrderId | string ≤128 | 否 | 貴司系統單號,透傳給渠道詢價 |
refId | string ≤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
curl https://stellabit.cc/api/v1/orders/{orderId} \
-H "Authorization: Bearer $TOKEN"回應為 { "order": { ... } }, 只能查自己的訂單,否則 404。商戶常用欄位如下:
{
"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-Type | application/json |
X-Platform-Id | 您的商戶 ID |
X-Event | 事件類型(同 body 中的 event,僅供參考;程式判斷請以 body 的 event 為準) |
X-Stellabit-Signature | HMAC-SHA256 簽名,格式 sha256=<hex> |
訂單事件 Payload
{
"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
{
"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 欄位不同):
{
"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,資金已入您的錢包):
{
"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 劃轉已被拒絕,請儲值錢包後重試):
{
"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 說明
{
"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:
X-Stellabit-Signature: sha256=<hex(HMAC_SHA256(apiKey, rawBody))>⚠️ 務必使用原始 body 驗簽
簽名是對「原始 JSON 字串」計算的。請在 JSON 解析之前取得原始 body 進行驗簽——若先 parse 再 stringify,欄位順序或空白差異會導致驗簽失敗。 比對簽名時請使用 timing-safe 比較函式,避免時序攻擊。
Node.js(Express)範例
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 範例
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收到通知後,先查詢該
eventId是否已處理過 - 2已處理過 → 直接回 200,不重複執行業務邏輯
- 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
請求範例
curl -X POST https://stellabit.cc/api/platform/webhook-test \
-H "x-api-key: $KEY"您的接收端會收到
{
"eventId": "550e8400-e29b-41d4-a716-446655440002",
"event": "test",
"test": true,
"timestamp": "2026-01-01T00:00:00.000Z",
"platformId": "您的商戶 ID"
}測試請求同樣帶 X-Stellabit-Signature 簽名,可直接用來驗證驗簽程式碼。
回應
{
"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 狀態碼
- 發送成功與否、重試狀態(嘗試次數)
- 發送時間
請求範例
curl https://stellabit.cc/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)
curl https://stellabit.cc/api/account/balance \
-H "x-api-key: $KEY" \
-H "x-user-id: $USER_ID"② 客戶前端(Authorization: Bearer 客戶 Token)
curl https://stellabit.cc/api/account/balance \
-H "Authorization: Bearer $TOKEN"回應
{
"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 的鏈上提幣總額)。
{
"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)
curl "https://stellabit.cc/api/account/ledger?source=transfer_out&page=1&limit=50" \
-H "x-api-key: $KEY" \
-H "x-user-id: $USER_ID"② 客戶前端(Authorization: Bearer 客戶 Token)
curl "https://stellabit.cc/api/account/ledger?page=1&limit=20" \
-H "Authorization: Bearer $TOKEN"錢包餘額查詢
端點: GET /api/platform/vault
查詢貴司商戶錢包的即時餘額,含凍結金額(如進行中訂單的 escrow 凍結)。 僅需 API Key,無需 x-user-id。API 路徑與回應欄位沿用舊名 vault(金庫=錢包),內容即商戶錢包餘額。
請求範例
curl https://stellabit.cc/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)。系統在同一筆交易內原子性地 「扣錢包餘額 → 為客戶入帳」,錢包餘額不足時直接拒絕、不會產生部分入帳。
POST https://stellabit.cc/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": "備註(選填)"
}成功回應:
{
"success": true,
"direction": "from_platform",
"crypto": "USDT",
"amount": "100",
"duplicate": false,
"message": "已從商戶金庫劃入客戶資金帳戶"
}💡 以 refId 冪等
建議每次劃轉帶上您系統的唯一交易 ID 作為 refId。 相同 refId 重複呼叫會回 duplicate: true 且不重複入帳,網路重試時不會造成重複劃轉。
錯誤碼
| HTTP | 錯誤碼 | 說明 |
|---|---|---|
| 403 | PLATFORM_API_KEY_REQUIRED | from_platform 劃轉僅限商戶以 API Key 發起;客戶 JWT(含 Widget Token)呼叫會被拒絕 |
| 400 | INSUFFICIENT_PLATFORM_BALANCE | 商戶錢包餘額不足,回應含 vaultBalance / required,並同時發送錢包餘額不足 Webhook 通知。v1.14 起建單門檻為「可用餘額 ≥ 凍結金額+平台費欠繳」,有欠繳時 message 會註明(含平台費欠繳 N);充值後欠繳自動抵扣 |
| 400 | PLATFORM_VAULT_NOT_BOUND | 商戶尚未綁定錢包帳號,請聯繫站主完成綁定 |
錢包餘額不足時的回應範例:
{
"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 請求(同步、單次、不重試):
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:
// 放行:劃轉照常執行
{ "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 清除、停用機制):
PUT https://stellabit.cc/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 帶入。
POST https://stellabit.cc/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 | 錯誤碼 | 說明 |
|---|---|---|
| 400 | TRANSFER_CONFIRM_REJECTED | 貴司設定了劃轉前確認 URL 且明確拒絕(回應含 reason),客戶餘額零異動 |
| 400 | TRANSFER_CONFIRM_UNAVAILABLE | 劃轉前確認連線失敗/逾時 → fail-closed 拒絕,客戶餘額零異動 |
| 400 | PLATFORM_VAULT_NOT_BOUND | 商戶尚未綁定錢包帳號 |
| 403 | 2FA_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 指定,兩者擇一必填。
POST https://stellabit.cc/api/account/transfer/peer
Authorization: Bearer $TOKEN
Content-Type: application/json
{
"toUserId": "收款方客戶 ID(或改用 toEmail)",
"crypto": "USDT",
"amount": "50",
"note": "備註(選填)"
}| HTTP | 錯誤 | 說明 |
|---|---|---|
| 404 | Recipient not found | 收款方不存在(toEmail 只能解析到同商戶已註冊 Email 的客戶) |
| 400 | Cannot transfer to yourself | 不可轉給自己 |
| 400 | Transfer Failed | 餘額不足等,message 含具體原因 |
兩種劃轉都是內部帳本操作:即時完成、同一交易內原子執行,不會產生部分入帳。 建議帶 refId 做冪等(to_platform / from_platform),重試時不會重複劃轉。
API Key IP 白名單(選用)
選用安全機制(opt-in):為您的 API Key 綁定來源 IP 白名單。設定後, 只有白名單內的 IP 能以此 API Key 調用商戶 API,其他來源一律回 403。 未設定(預設)則不限制,行為與現在完全相同。建議所有正式接入的商戶啟用, 可大幅降低 API Key 洩漏後被盜用的風險。
設定方式
於商戶後台(「Webhook 設定」區塊)填寫,或以 API 設定:
PUT https://stellabit.cc/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 發起的請求回:
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) | 含義 |
|---|---|---|
| 401 | Invalid token | 客戶 Token 無效或已過期 → 重新簽發 Token |
| 401 | Unauthorized | API Key 缺失/無效 |
| 400 | Missing x-user-id | API Key 認證路徑未帶 x-user-id header |
| 403 | API_KEY_IP_FORBIDDEN | API Key 來源 IP 不在白名單(回應含 sourceIp) |
| 403 | VAULT_OWNER_TOKEN_FORBIDDEN | 不得為錢包帳號簽發 widget token |
| 403 | VAULT_OWNER_LOGIN_REQUIRED | 錢包帳號資金操作僅限本人登入 |
| 403 | PLATFORM_API_KEY_REQUIRED | from_platform 劃轉僅限 API Key 發起 |
| 403 | 2FA_REQUIRED | 需要 2FA 驗證碼(先呼叫 send-otp) |
| 403 | 2FA_INVALID | 2FA 驗證碼無效或已過期 |
| 403 | USDC_DISABLED | 帶入 crypto=USDC(目前僅支援 USDT,USDC 已停用) |
| 409 | REF_ID_CONFLICT / REF_ID_MISMATCH | 建單 refId 已被同商戶其他客戶使用 / 同客戶重送但參數與原單不一致(見「買賣訂單」章節) |
| 400 | AMBIGUOUS_PRICE_SOURCE | offerId 路徑與 channelId/cryptoAmount/currency 等新路徑欄位同時出現 |
| 400 | CHANNEL_REQUIRED | 新路徑沒帶 channelId,且商戶未設預設渠道 |
| 400 | INVALID_AMOUNT_PRECISION | 金額小數位數超過允許精度 |
| 404 | CHANNEL_NOT_FOUND | channelId 不存在或不屬於此商戶 |
| 422 | CHANNEL_NOT_QUOTABLE | 該渠道未設詢價 URL,或未發放渠道 Key+Secret(不是系統型渠道) |
| 422 | CHANNEL_QUOTE_REJECTED | 渠道回 available=false(回應帶 reason 透傳,例 AMOUNT_OUT_OF_RANGE/CURRENCY_NOT_SUPPORTED/TEMPORARILY_UNAVAILABLE);不建單、不凍結 |
| 503 | CHANNEL_QUOTE_UNAVAILABLE | 詢價逾時(3 秒)/連不上/回應簽章錯誤/回應不合法;不建單、不凍結,可稍後以同一 refId 重送 |
| 422 | OFFER_CHANNEL_REQUIRES_QUOTE | offerId 指向系統型渠道的報價牌;請改用 channelId+cryptoAmount 新路徑 |
| 422 | MANUAL_CONFIRM_NOT_ALLOWED | 系統型渠道的訂單只能由渠道回打確認,商戶後台不可人工確認 |
| 400 | INSUFFICIENT_BALANCE | 客戶資金帳戶餘額不足 |
| 400 | INSUFFICIENT_PLATFORM_BALANCE | 商戶錢包餘額不足(有平台費欠繳時,需餘額 ≥ 金額+欠繳,message 含欠繳數字) |
| 400 | PLATFORM_VAULT_NOT_BOUND | 商戶尚未綁定錢包帳號 |
| 400 | TRANSFER_CONFIRM_REJECTED | 劃轉前確認被商戶拒絕(含 reason) |
| 400 | TRANSFER_CONFIRM_UNAVAILABLE | 劃轉前確認無法連線,fail-closed 拒絕 |
| 400 | DAILY_LIMIT_EXCEEDED | 超過每日提幣限額(error 欄位為舊值 DailyLimitExceeded) |
| 400 | OFFER_NOT_FOUND | 報價不存在或已下架 |
| 400 | AMOUNT_BELOW_MIN / AMOUNT_ABOVE_MAX | 金額低於下限 / 超過上限(建單依報價 min–max;提幣依提幣設定) |
| 400 | OFFER_RATE_UNAVAILABLE | 動態報價匯率暫時不可用 |
| 400 | ORDER_CREATION_FAILED | 建單失敗(其他未分類原因,見 message) |
| 400 | INVALID_ORDER_STATUS | 訂單狀態不允許此操作(如對非 pending 訂單 confirm-paid) |
| 400 | INVALID_AMOUNT | 金額格式/數值無效 |
| 400 | INVALID_ADDRESS | 地址格式錯誤(提幣/地址簿);提幣 message 按 chain 給對應格式提示,見「多鏈提幣」章節 |
| 400 | UNSUPPORTED_CHAIN / UNSUPPORTED_CHAIN_CRYPTO / CHAIN_TEMPORARILY_DISABLED | 多鏈充提:鏈未開放(貴司商戶未開通 BEP20 / ARB)/ 該鏈不支援此幣種 / 該鏈暫停提幣(見「多鏈提幣(BEP20 / ARB)」章節) |
| 400 | WALLET_NOT_FOUND | 尚未產生該幣種鏈上錢包(先呼叫 deposit/address) |
| 400 | ADDRESS_BOOK_FULL | 提幣地址簿已滿(每幣種上限 20) |
| 400 | SELF_TRANSFER_FORBIDDEN | 不可站內轉帳給自己 |
| 400 | TRANSFER_FAILED | 劃轉/轉帳失敗(其他未分類原因,見 message) |
| 400 | SWAP_VALIDATION | 閃兌參數驗證失敗(幣種/金額超出供應商範圍等) |
| 400 | OTP_INVALID | 2FA 驗證碼無效或已過期(/api/2fa/verify) |
| 400 | TWOFA_ENABLE_FAILED / OTP_SEND_FAILED | 啟用 2FA / 發送驗證碼失敗(見 message) |
| 403 | IDENTITY_MISMATCH | body 帶的 tradingPlatformId/platformUserId 與認證身分不符 |
| 404 | ORDER_NOT_FOUND | 訂單不存在或非本人訂單(含閃兌訂單) |
| 404 | RECIPIENT_NOT_FOUND | 站內轉帳收款人不存在 |
| 404 | ADDRESS_NOT_FOUND | 地址簿項目不存在或非本人 |
| 429 | TOO_MANY_REQUESTS | OTP 限流/鎖定,依 retryAfter 退避 |
| 503 | SWAP_UNAVAILABLE | 閃兌未開放 |
| 502 | SWAP_PROVIDER_ERROR | 閃兌供應商暫時無法服務 |
備註:401(Invalid token / Unauthorized)與參數驗證 400(Validation Error + details)目前不帶 code 欄位, 請分別以 HTTP 狀態碼與 details 陣列判斷。
錯誤碼
| HTTP | 錯誤碼(code) | 出現在 | 含義與處理 |
|---|---|---|---|
| 400 | AMOUNT_REQUIRED | 試算 | cryptoAmount 與 fiatAmount 都沒帶 |
| 400 | INVALID_AMOUNT_PRECISION | 試算 | 金額小數位超出限制 |
| 404 | CHANNEL_NOT_FOUND | 試算/下單 | 渠道不存在、未綁定、已下線或不在上工中名單;請重新取渠道列表 |
| 422 | REFERENCE_RATE_UNAVAILABLE | 試算 | 帶法幣金額但目前沒有參考價可換算;改用 cryptoAmount 或稍後再試 |
| 422 | CHANNEL_NOT_QUOTABLE | 試算 | 渠道目前不能報價(非系統型渠道或條件不符) |
| 422 | CHANNEL_QUOTE_REJECTED | 試算 | 渠道不報價(例如金額超出範圍),reason 原樣透傳 |
| 429 | QUOTE_RATE_LIMITED | 試算 | 試算太頻繁(每客戶 10 次/分、每商戶 120 次/分),依 retryAfter 稍後再試 |
| 503 | CHANNEL_QUOTE_UNAVAILABLE | 試算/下單 | 渠道詢價逾時或失敗,不建單、不凍結;可稍後重試 |
| 404 | QUOTE_NOT_FOUND | 下單 | 報價單不存在,或不屬於這個商戶/客戶 |
| 409 | QUOTE_ALREADY_USED | 下單 | 報價單已被使用(不同客戶或已建過單) |
| 409 | QUOTE_EXPIRED | 下單 | 報價過期,回應附 newQuote 與 previousRate,請客戶再確認 |
| 409 | QUOTE_MISMATCH | 下單 | 同時帶的 channelId/金額等與報價單不一致 |
| 400 | AMBIGUOUS_PRICE_SOURCE | 下單 | 帶 quoteId 又帶 offerId,價格來源不明確 |
| 422 | RATE_AMOUNT_CONFLICT | 下單 | customerRate 與 fiatAmount 都帶但互相不一致(二擇一) |
| 422 | SPREAD_EXCEEDS_LIMIT | 下單 | 客戶匯率/法幣數額與參考匯率的價差超過 maxSpreadPct 上限(回應含 hint、maxSpreadPct、referenceRate) |
| 409 | REF_ID_MISMATCH | 下單 | 同 refId 重送,但 customerRate/fiatAmount 與原單不同 |
| 400 | INSUFFICIENT_PLATFORM_BALANCE | 下單 | 商戶錢包餘額不足(含平台費欠繳時 message 會註明),報價單退回未使用 |
測試環境
測試環境為獨立部署的完整站台,與正式環境(https://stellabit.cc)帳號、資料互不相通。接入開發期間請將所有 Base URL 指向測試環境:
| 項目 | 測試環境 | 正式環境 |
|---|---|---|
| API Base URL | https://test.stellabit.cc | https://stellabit.cc |
| SDK script | https://test.stellabit.cc/sdk.js | https://stellabit.cc/sdk.js |
| Widget Demo | https://test.stellabit.cc/widget-demo | https://stellabit.cc/widget-demo |
| 商戶開戶 | https://test.stellabit.cc/register | https://stellabit.cc/register |
| Swagger 文件 | (測試環境不對外開放) | https://stellabit.cc/api-docs |
測試環境使用真實主網(TRON / BSC / Arbitrum,非測試鏈),測試儲值時請使用小額 USDT。 兩個環境跑同一版程式,API 契約一致(Swagger 以正式環境為準)。 測試環境支援全部流程:簽 token、Widget 嵌入、儲值、買賣訂單、雙向劃轉、Webhook(含 webhook-test 端點)。
測試環境與正式環境完全獨立
- 兩個環境的資料庫完全獨立:帳號、客戶、餘額、訂單互不相通
- API Key 互不通用:測試環境產生的 Key 無法在正式環境使用(反之亦然),跨環境呼叫會得到 401
- 測試時請將 API Base URL(token、劃轉、查詢、SDK script 等)全部指向 test.stellabit.cc;正式上線時再全部切換為正式環境域名
⚠️ 常見 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、建單、劃轉 |
| Header | Authorization: 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登入商戶後台,進入「管理 Key」頁面。
- 2填寫標籤,勾選需要的 scope(最小權限原則),可選填 IP 白名單(IPv4/IPv6/CIDR,最多 20 筆)與到期時間。
- 3若帳號已啟用 TOTP,輸入驗證碼後建立。
- 4明文 Key(mk_…)只顯示一次,請立即交給 Agent 保存;可隨時在後台吊銷。
管理 API 端點
路徑前綴 /api/merchant/v1。🔒 = 高敏感操作,商戶保險絲開啟時回 202 待人類確認(見下節)。
| 方法 | 路徑 | scope | 用途 |
|---|---|---|---|
GET | /me | (無) | Key 自身:id/label/prefix/last4/scopes、保險絲狀態、限流資訊(limit/remaining/resetAt)、platform {id,name}、maxSpreadPct、defaultSpreadPct(手續費 %,字串|null) |
GET | /channels | channels:read | 渠道列表(同後台 GET /api/platform/channels 回應) |
POST | /channels | channels:write | 建渠道(body 同後台;system 型可帶 fieldMappings) |
GET | /channels/:id | channels:read | 渠道詳情 |
PATCH | /channels/:id | channels:write | 改資料、三網址(quoteUrl/createOrderUrl/callbackUrl)、payUrlHostAllowlist、手續費 defaultSpreadPct(單一費用 %,字串|null,最多 3 位小數、可負=讓利;null=沿用商戶層;|值|>maxSpreadPct 422 SPREAD_EXCEEDS_LIMIT);改 URL 自動下線 |
DELETE | /channels/:merchantId | channels:write | 解綁(409 CHANNEL_HAS_OPEN_ORDERS) |
POST | /channels/:merchantId/pause | channels:write | 停用 |
POST | /channels/:merchantId/resume | channels:write | 啟用 |
GET | /channels/:id/onboarding-status | channels:read | 上線檢查結果 |
PATCH | /channels/:id/online | channels:write | body {isOnline:boolean} 上線/下線(須通過檢查) |
POST | /channels/:id/test-quote | channels:write | 測試詢價(真打) |
POST | /channels/:id/test-create-order | channels:write | 測試建單(真打,不產生訂單) |
POST | /channels/:id/test-callback | channels:write | 發回打測試單號 |
POST | /channels/:id/webhook-test | channels:write | 測試推送 |
POST | /channels/:id/quote-test | channels:read | 詢價試算(不持久化) |
GET | /channels/:id/webhook-logs | channels:read | 推送紀錄(limit/offset) |
GET | /channels/:id/quote-logs | channels:read | 詢價紀錄(page/limit) |
GET | /channels/:id/field-mappings | channels:read | 欄位映射 |
PUT | /channels/:id/field-mappings | mappings:write | 整組取代 body {mappings:[{mappingType,ourField,merchantField,notes?}]} |
POST | /channels/:id/field-mappings | mappings:write | 新增一筆 |
PATCH | /channels/:id/field-mappings/:mappingId | mappings:write | 改一筆 |
DELETE | /channels/:id/field-mappings/:mappingId | mappings:write | 刪一筆 |
POST | /channels/:id/field-mappings/suggest | channels: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/credentials | integration:read | 回打憑證(masked:keyLast4、issuedAt、hasSecret) |
POST | /channels/:id/credentials/rotate 🔒 | integration:write | 輪替回打憑證(一次性回明文) |
PUT | /channels/:id/allowed-ips 🔒 | integration:write | 渠道回打 IP 白名單 |
GET | /webhook | integration:read | 商戶 Webhook URL |
PUT | /webhook 🔒 | integration:write | 改 Webhook URL body {webhookUrl} |
PUT | /default-spread | integration:write | 改商戶層手續費 body {defaultSpreadPct}(單一費用 %,字串|null;最多 3 位小數、可負=讓利);系統依方向套用(客戶買 ref×(1+pct/100)、客戶賣 ref×(1−pct/100));建單未帶 customerRate/fiatAmount 時套用,|值|>maxSpreadPct 回 422 SPREAD_EXCEEDS_LIMIT |
PUT | /max-spread-pct | integration:write | 改最大價差(目前值由 GET /me 的 maxSpreadPct 讀取)body {maxSpreadPct:"5.00"}(0–100、2 位小數);商戶自訂客戶匯率/法幣數額與渠道參考匯率的差距上限,超過下單回 422 SPREAD_EXCEEDS_LIMIT |
GET | /webhook-logs | integration:read | 商戶推送紀錄 |
POST | /webhook-test | integration:write | 測試推送到商戶 Webhook |
GET | /allowed-ips | integration:read | 交易 API Key IP 白名單 |
PUT | /allowed-ips 🔒 | integration:write | 改白名單 body {allowedIps:string[]|null} |
GET | /api-key | integration: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 | /orders | orders:read | 訂單列表 ?status&channelId&limit&offset |
GET | /orders/:id | orders:read | 訂單詳情 |
GET | /account | account:read | 金庫餘額+平台費(同後台 /api/platform/account) |
GET | /account/ledger | account: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:
{ "success": true, "status": "pending_approval", "approvalId": "…", "actionType": "channel.credentials.rotate", "expiresAt": "…" }- 1收到 202 與 approvalId。
- 2通知人類到後台「待確認」確認(需 TOTP);24 小時未處理即過期(expired)。
- 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。
錯誤格式
{ "success": false, "error": "<CODE>", "code": "<CODE>", "message": "...", "hint": "英文下一步建議", "docs": "/docs/agent-guide#<code 小寫>" }hint 為下一步建議,docs 指向 /docs/agent-guide 中該錯誤碼的說明。缺 scope 時為 403 INSUFFICIENT_SCOPE 並帶 requiredScope。錯誤碼表
| code | HTTP | 說明 |
|---|---|---|
MISSING_MANAGEMENT_KEY | 401 | 未帶 Authorization: Bearer <管理 Key> |
INVALID_MANAGEMENT_KEY | 401 | 管理 Key 無效(例如誤用交易 API Key 打管理 API) |
MANAGEMENT_KEY_REVOKED | 401 | 管理 Key 已被吊銷,請在後台重新建立 |
MANAGEMENT_KEY_EXPIRED | 401 | 管理 Key 已過期,請在後台重新建立 |
IP_NOT_ALLOWED | 403 | 來源 IP 不在此 Key 的 allowedIps 內 |
INSUFFICIENT_SCOPE | 403 | 缺少 scope;回應含 requiredScope 欄位 |
RATE_LIMITED | 429 | 每把 Key 每分鐘 120 次;依 Retry-After 稍後重試 |
IDEMPOTENCY_MISMATCH | 409 | 同一 Idempotency-Key 但 body 不同 |
IDEMPOTENCY_IN_PROGRESS | 409 | 同一 Idempotency-Key 的請求仍在處理中 |
VALIDATION_ERROR | 400 | 請求參數不合法 |
CHANNEL_NOT_FOUND | 404 | 找不到渠道(或不屬於此商戶) |
APPROVAL_NOT_FOUND | 404 | 找不到待確認記錄 |
APPROVAL_NOT_PENDING | 409 | 待確認記錄已不是 pending(已處理或過期) |
CHANNEL_NOT_SYSTEM | 400 | 此操作僅限 system 型渠道 |
URL_REQUIRED | 400 | 上線前須先設定必要網址 |
WEBHOOK_URL_BLOCKED | 400 | Webhook URL 被安全檢查擋下(內網/不允許的位址) |
MAPPING_DUPLICATE | 409 | 欄位映射重複 |
CHANNEL_HAS_OPEN_ORDERS | 409 | 渠道仍有未結訂單,無法解綁 |
最小可用範例(curl)
建渠道 → 設欄位映射 → 上線 → 查上線檢查結果。
BASE=https://stellabit.cc
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 分開是為了方向分離:任一把外洩只影響一個方向,且可各自重新產生。
rate 欄位=參考匯率(不含客戶匯率)。 商戶與渠道之間的差額由雙方自行結算,平台不計算、不介入。① 詢價端點(支付中心 → 渠道)
渠道在後台填入的「詢價 URL」必須是 https。渠道沒有詢價介面就不能設為系統型渠道。每張單、每次試算都即時詢價,不快取、不重試;逾時 3 秒(連線加讀取合計)、不跟隨轉址,逾時或失敗一律視為渠道暫時不可報價。
請求(POST {詢價 URL})Headers:
| Header | 值 |
|---|---|
Content-Type | application/json |
X-Stellabit-Event | quote.request |
X-Stellabit-Merchant | 渠道 id |
X-Stellabit-Signature | sha256= + hex(HMAC_SHA256(Webhook Secret, rawBody)) |
請求 Body:
| 欄位 | 型別 | 說明 |
|---|---|---|
requestId | uuid | 本次詢價 id,渠道可用來去重;回應必須原樣帶回 |
type | buy | sell | buy=客戶買幣(充值單);sell=客戶賣幣(提現單) |
crypto | string | 例 USDT |
network | string? | 例 TRC20 |
cryptoAmount | string(decimal) | 客戶要買/賣的幣數 |
currency | string | 法幣:THB | HKD | CNY | IDR |
externalOrderId | string? | 商戶系統帶來的外部單號(若有) |
timestamp | int | unix 秒;渠道應拒絕 ±300 秒外的請求 |
回應:HTTP 2xx,並帶 header X-Channel-Timestamp(unix 秒,與支付中心時間差須在 ±300 秒內)與 X-Channel-Signature = sha256= + hex(HMAC_SHA256(渠道 Secret, {timestamp}.{requestId}.{rawResponseBody}))。簽章不過,視同詢價失敗。
可報價:
{
"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 為準 |
quoteId | 1–64 字元,同一渠道不可重複使用 |
expiresAt | ISO 8601。渠道承諾此價到此時有效;須晚於現在 60 秒以上(否則該次詢價視為渠道不接受),超過 30 分鐘以 30 分鐘計 |
不報價(同樣要簽章):
{ "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-Signature | sha256= + 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。
{
"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):
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))
}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 '')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);缺則沿用我方訂單有效期 |
{ "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 https://stellabit.cc/api/v1/callback/topup-confirm |
| 提現單:渠道已付法幣給客戶 | POST https://stellabit.cc/api/v1/callback/withdraw-fiat-sent |
| (選用)渠道自行上線/下線 | PATCH https://stellabit.cc/api/channel/me/online { "isOnline": true|false } |
必帶 Headers(Key 與簽章兩道都要過):
| Header | 說明 |
|---|---|
x-api-key | 渠道 Key |
X-Channel-Timestamp | unix 秒;與支付中心時間差須 ≤ 300 秒 |
X-Channel-Nonce | 16–64 字元,限 A–Z a–z 0–9 _ -;每通唯一,10 分鐘內不可重用(防重放) |
X-Channel-Signature | sha256= + 小寫 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 計算,請勿在簽完後再重新序列化。
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 至少帶一個 |
fiatAmount | channel_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 回應範例:
{ "success": true, "orderId": "…", "orderNo": "OD2026110700001", "status": "completed", "idempotent": false, "overpaid": false, "overpaidAmount": null }驗證失敗的回應
| HTTP | code | 原因 |
|---|---|---|
| 401 | MISSING_API_KEY / INVALID_API_KEY | 沒帶或查不到渠道 Key(商戶 API Key 不被接受) |
| 403 | CHANNEL_INACTIVE / IP_NOT_ALLOWED | 渠道已停用;來源 IP 不在白名單 |
| 401 | CHANNEL_CREDENTIALS_NOT_ISSUED | 商戶尚未產生渠道 Key+Secret |
| 401 | MISSING_SIGNATURE | 缺 X-Channel-Timestamp/Nonce/Signature |
| 401 | TIMESTAMP_OUT_OF_WINDOW | 時間差超過 300 秒 |
| 401 | INVALID_SIGNATURE | 簽章不符,或 nonce 格式不合 |
| 401 | NONCE_REUSED | nonce 已用過 |
| 503 | NONCE_STORE_UNAVAILABLE | 防重放服務暫時不可用,稍後重試(重試請換新 nonce 與 timestamp) |
| 422 | CALLBACK_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,視為成功。
常見叫法對照
| 標準名 | 渠道常見的叫法(舉例) | 說明 |
|---|---|---|
| orderId | out_trade_no、merchant_order_id、order_id、trade_no | 支付中心訂單 id(uuid),回打與 channelOrderId 至少帶一個 |
| channelOrderId | trade_no、platform_order_id、order_id | 渠道自己的訂單號(選填;回打可作反查備援) |
| orderNo | order_no、order_sn、reference | 訂單編號,給人看的 |
| payUrl | pay_url、cashier_url、checkout_url、pay_link | 渠道建單回的付款網址,必填,https |
| fiatAmount | amount、total_fee、pay_amount、real_amount | 法幣金額;回打時為實收/實付 |
| cryptoAmount | coin_amount、usdt_amount、quantity | 幣數 |
| rate | price、exchange_rate | 1 幣 = ? 法幣(詢價回應:參考匯率;建單請求:參考匯率) |
| quoteId | quote_id、price_id、offer_id(渠道自己的報價單號) | 渠道報價單號,同渠道不可重複 |
| expiresAt | expire_time、valid_until、expired_at | 報價有效期,ISO 8601 |
| paymentRef | transaction_id、bank_ref、receipt_no | 渠道側單號,選填 |
| status 值:completed | SUCCESS、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 公開網址(反向代理或隧道皆可):
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建商戶帳號:到
/register開戶、設定 2FA,登入後進/console/dashboard;到「系統對接」拿 API Key、填通知網址(可填沙盒渠道的 /webhook)。 - 2用精靈串接沙盒渠道:「渠道 → 新增渠道 → 系統型渠道」。第②步三個網址填:詢價
{public-url}/quote、建單{public-url}/create-order、通知{public-url}/webhook(全部 https)。第③步測詢價、測建單全綠後,第④步按「發憑證」。 - 3把資料卡貼進 /__setup:資料卡的值對照填入——渠道 Key→「渠道 Key」;渠道 Secret→「渠道 Secret」與「詢價簽章 Secret」;驗證金鑰 Webhook Secret→「Webhook Secret」,儲存。沒填的話,第③步雖然會綠(此步不驗簽章),真正詢價與建單會因簽章不符失敗。
- 4回打測試要用最新發的單號:精靈按「發測試單號」,把單號貼到 /__setup 的「回打測試」送出,精靈顯示「已收到渠道的回打測試」即通過。重新發過單號,就要用最新那個;舊的會失敗。勾「我已完成設定」後上線。
- 5欄位映射練習:把 mode 切到
price,回精靈第②步(或渠道的「欄位映射」)新增:rate→price、expiresAt→expire_time、fiatAmount→pay_amount、建單的 payUrl→pay_link、channelOrderId→trade_no、建單的 expiresAt→expire_time。渠道欄位名要與渠道文件逐字一致,含底線(expire_time不是expireTime),多一個空白或少一個底線都對不上。 - 6下單:用 Widget 參考頁(見「Widget:快速開始」;
/widget/buy?token=…¤cy=THB),或照「10 分鐘接通」步驟②的三個 curl(渠道 → quotes → orders/topup)。渠道必須已「上線」才列得出來。 - 7付款頁按「模擬付款」:建單回應的
merchantTransactionUrl就是沙盒渠道的 /pay/:token 付款頁;按下去,沙盒渠道會用渠道 Key/Secret 簽章回打支付中心,頁面顯示回打結果。 - 8後台看結果:「總覽」看錢包變動;訂單列表看訂單狀態與渠道單號(channelOrderId);「系統對接」的發送紀錄看到 topup.completed 通知。
- 9切 500 看失敗回滾:mode 切到
500再下單:詢價回 503 CHANNEL_QUOTE_UNAVAILABLE、建單回 503 CHANNEL_CREATE_FAILED;單會取消、錢包解凍,不會有扣款。切回 ok 後恢復。
沙盒渠道的 /__setup 沒有身分驗證,只在測試環境使用;Key/Secret 不要貼到公開處,用完請關閉服務。
快速開始
5 分鐘完成接入
接入步驟
- 1取得 API Key — 前往 開戶頁 開戶(免審核,開戶即有錢包),登入商戶後台後自助產生 API Key
- 2後端換取 Token — 呼叫
/api/widget/token,每次開啟 Widget 前換取 - 3前端引入 SDK —
<script src="https://stellabit.cc/sdk.js">,然後呼叫Stellabit.open()
安裝 SDK
在頁面 <head> 或 <body> 底部引入:
<script src="https://stellabit.cc/sdk.js"></script>SDK 載入後自動掛載全域物件 Stellabit,無需額外初始化。
取得 Token
每次客戶要開啟 Widget 前,需由後端呼叫此 API 換取代表該客戶身份的短期 JWT Token(有效期 1 小時),再傳給前端使用。 不可在前端直接呼叫(會暴露 API Key)。
POST https://stellabit.cc/api/widget/token
x-api-key: $KEY
Content-Type: application/json
{
"userId": "您商戶的客戶唯一 ID",
"expiresIn": 3600
}回應:
{
"token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
"expiresIn": 3600,
"widgetUrl": "https://stellabit.cc/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)→ 付款 → 完成。
<button onclick="Stellabit.open('swap', token)">買幣 / 賣幣</button>流程說明
- 1進入後先選擇「買入 USDT」或「賣出 USDT」分頁
- 2客戶輸入欲換出 / 換入的金額
- 3系統列出符合條件的渠道報價
- 4客戶選擇渠道,建立訂單
- 5客戶依渠道指定方式付款
- 6渠道確認收款後交易完成
完成事件:stellabit:done
💡 關於舊版 buy / sell widget
系統內部仍保留獨立的 /widget/buy 與/widget/sell 頁面(較早期的實作,介面較簡化、無金額雙向互算), 但本文件不建議新商戶使用,僅作為既有整合的相容保留。新接入請一律使用 swap。
儲值 (deposit)
「儲值」是指客戶將 USDT 從外部錢包轉入商戶帳戶。預設鏈別為 TRC-20(TRON);若貴司商戶已開通 BEP20(BSC)或 ARB(Arbitrum One)充值, Widget 會提供鏈別切換。系統為每位客戶在每條鏈生成專屬充幣地址, 客戶掃碼或複製地址後,在自己的錢包 App 發起轉帳,系統偵測到鏈上交易確認後自動入帳(各鏈到帳進同一份站內餘額,不分鏈)。
<button onclick="Stellabit.open('deposit', token)">儲值 / 充幣</button>充幣流程
- 1SDK 呼叫後,Widget 顯示客戶的專屬充幣地址(含 QR Code;多鏈開通時可切換鏈別)
- 2客戶用外部錢包掃碼或複製地址,發起鏈上轉帳
- 3系統偵測到鏈上交易並等待確認(TRC-20 掃描間隔預設 5 分鐘,約 5–10 分鐘;BEP20 15 個確認約 15–60 秒;ARB 300 個確認約 1–2 分鐘)
- 4交易確認後,商戶帳戶餘額自動更新
- 5Widget 顯示充幣成功,觸發
stellabit:done事件
💡 重要提示
- 僅接受 USDT,且必須依 Widget 顯示的鏈別轉入對應網路(TRC-20 地址只收 TRON USDT;0x 地址只收該鏈的 USDT),轉錯鏈或其他幣種無法取回
- 每位客戶在每條鏈的充幣地址固定且唯一,可重複使用
- 單筆低於 1 USDT 視為灰塵不入帳(金額不累計)
完成事件:stellabit:done(客戶可監聽此事件刷新餘額顯示)
提幣 (withdraw)
客戶將商戶帳戶的 USDT 提出至外部錢包。預設鏈別為 TRC-20;貴司商戶已開通時可選 BEP20(BSC)或 ARB(Arbitrum One)。 需要輸入提幣地址和金額,系統扣除帳戶餘額(含手續費)後發起鏈上轉帳;大額提幣可能進入人工審核。
<button onclick="Stellabit.open('withdraw', token)">提幣</button>流程說明
- 1客戶選擇鏈別(預設 TRC-20),輸入對應格式的提幣地址和數量(已啟用 2FA 的客戶需輸入驗證碼)
- 2確認後系統立即扣除帳戶餘額(金額 + 手續費)
- 3後台發起鏈上轉帳
- 4鏈上確認後提幣完成
完成事件:stellabit:done
帳戶總覽 (balance-hub)
顯示客戶的帳戶餘額,並提供餘額劃轉(商戶帳戶 ↔ 交易帳戶)及內部轉帳功能。
<button onclick="Stellabit.open('balance-hub', token)">帳戶總覽</button>功能
- 查看 USDT 餘額(商戶帳戶、交易帳戶)
- 劃入商戶(to_platform)
- 同商戶內轉帳給其他客戶
💡 關於「從商戶轉入」(from_platform)
客戶端不提供「從商戶轉入」方向。商戶 → 客戶的入帳僅限您的後端以 API Key 發起, 並從商戶錢包餘額即時扣款,詳見「商戶系統對接」的「商戶劃轉 API」章節。
嵌入方式
| 方式 | 呼叫方式 | 適用場景 |
|---|---|---|
| Popup Modal | Stellabit.open(action, token) | 最常用,按鈕觸發,Widget 覆蓋在頁面上方 |
| iframe 嵌入 | <iframe src="https://stellabit.cc/widget/swap?token=..."> | 一體化頁面設計,Widget 嵌在頁面區塊內 |
Popup 用法
// 基本呼叫
Stellabit.open('swap', token)Stellabit.open() 目前只接受 (action, token) 兩個參數, 不支援第三個選項物件(例如主題);若需要深色主題,請改用下方「主題設定」章節的 iframe URL 參數或 postMessage 方式。
iframe 用法
<iframe
src="https://stellabit.cc/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 參數(載入時套用,無閃爍)
// iframe src 加上 ?theme=dark
/widget/swap?token=...&theme=dark方式二:postMessage 動態切換(適合跟隨系統主題)
iframe.contentWindow.postMessage({ type: 'stellabit:theme', theme: 'dark' }, '*')事件監聽
Widget 透過 window.postMessage 與外層頁面溝通,無論是 Popup 還是 iframe 方式均適用。
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=sell | POST /api/v1/orders/topup |
| 客戶賣幣(USDT → 法幣) | type=buy | POST /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 |
請求與回應範例
curl "https://stellabit.cc/api/v1/offers?type=sell&crypto=USDT" \
-H "Authorization: Bearer $TOKEN"{
"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 分鐘,逾時自動取消。
POST https://stellabit.cc/api/v1/orders/topup
Authorization: Bearer $TOKEN
Content-Type: application/json
{
"offerId": "{type=sell 的報價 ID}",
"fiatAmount": 1000,
"refId": "貴司側冪等鍵(選填,≤128 字元)"
}| 參數 | 型別 | 必填 | 說明 |
|---|---|---|---|
offerId | string (uuid) | 是 | type=sell 的報價 ID |
fiatAmount | number | 是 | 法幣金額(需在報價 min–max 範圍內) |
refId | string ≤128 | 否 | 商戶側冪等鍵:同一 refId 重送不會重複建單(見下方冪等說明) |
🔁 refId 冪等語義(建議後端建單一律攜帶)
帶 refId 建單時,若同一 refId 已建過訂單(含並發重送),系統回傳原訂單: HTTP 200 + 原單完整資料 + "idempotentHit": true,不會重複建單、不會重複凍結錢包 escrow。 適用於逾時重試、網路中斷後重送等場景。新建訂單維持回 201;不帶 refId 行為與舊版完全一致。 refId 在貴商戶內唯一(買單/賣單共用同一命名空間),但回查僅限同一客戶:同商戶其他客戶已用過的 refId 會回 409 REF_ID_CONFLICT(不回傳他人訂單任何欄位);同客戶重送但 offerId / 金額與原單不一致會回 409 REF_ID_MISMATCH。
成功回應(201):
{
"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 | 錯誤 | 說明 |
|---|---|---|
| 400 | INSUFFICIENT_PLATFORM_BALANCE | 貴商戶錢包可用餘額不足(對客戶回通用文案;同時發送錢包不足 Webhook 給貴司) |
| 400 | OFFER_NOT_FOUND | 報價不存在或已下架 |
| 400 | AMOUNT_BELOW_MIN / AMOUNT_ABOVE_MAX | 金額低於/超過報價 min–max 範圍(message 含具體界限) |
| 400 | OFFER_RATE_UNAVAILABLE | 動態報價的匯率暫時不可用,請稍後再試 |
| 409 | REF_ID_CONFLICT / REF_ID_MISMATCH | refId 已被同商戶其他客戶使用 / 同客戶重送但參數(offerId、金額)與原單不一致;不回傳任何訂單資料,請改用新的 refId |
客戶確認已付款:POST /api/v1/orders/:id/confirm-paid
僅適用於買單(topup)且狀態為 pending。呼叫後訂單轉為 paid,等待渠道確認。
POST https://stellabit.cc/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 欄位會被忽略。
POST https://stellabit.cc/api/v1/orders/withdraw
Authorization: Bearer $TOKEN
Content-Type: application/json
{
"offerId": "{type=buy 的報價 ID}",
"cryptoAmount": 100,
"refId": "貴司側冪等鍵(選填,≤128 字元)"
}| 參數 | 型別 | 必填 | 說明 |
|---|---|---|---|
offerId | string (uuid) | 是 | type=buy 的報價 ID |
cryptoAmount | number | 是 | 賣出幣量 |
refId | string ≤128 | 否 | 商戶側冪等鍵:同一 refId 重送 → 回原單 200 + idempotentHit:true,不重複建單、不重複凍結客戶餘額(語義同買單,見上方說明) |
成功回應(201)——同一份訂單資料同時掛在 order 與 data 兩個 key(相容舊版呼叫方):
{
"success": true,
"order": {
"id": "....",
"orderNo": "WD2608....",
"status": "pending",
"crypto": "USDT",
"cryptoAmount": "100.00000000",
"currency": "THB",
"fiatAmount": "3650.00",
"rate": "36.50000000"
},
"data": { "...同 order": "" }
}| HTTP | 錯誤 | 說明 |
|---|---|---|
| 400 | INSUFFICIENT_BALANCE | 客戶資金帳戶可用餘額不足,無法建立賣單 |
| 400 | OFFER_NOT_FOUND / OFFER_RATE_UNAVAILABLE | 報價不存在或已下架 / 動態匯率暫時不可用 |
| 409 | REF_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 亦可呼叫),本端點僅為既有整合相容保留。
POST https://stellabit.cc/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)」章節。
curl "https://stellabit.cc/api/wallet/deposit/address?crypto=USDT" \
-H "Authorization: Bearer $TOKEN"{
"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 實際執行檢查的值同源,適合前端顯示與送出前預檢。
curl https://stellabit.cc/api/wallet/withdraw/config \
-H "Authorization: Bearer $TOKEN"{
"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)」章節。
POST https://stellabit.cc/api/wallet/withdraw
Authorization: Bearer $TOKEN
x-2fa-token: {6 位驗證碼,客戶已啟用 2FA 時必填}
Content-Type: application/json
{
"crypto": "USDT",
"amount": "100",
"toAddress": "T....(外部 TRON 地址)"
}成功回應(201):
{
"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 | 錯誤 | 說明 |
|---|---|---|
| 400 | INVALID_ADDRESS / AMOUNT_BELOW_MIN / AMOUNT_ABOVE_MAX / WALLET_NOT_FOUND / INSUFFICIENT_BALANCE | 地址格式錯誤 / 低於最小金額 / 超過最大金額 / 尚無錢包 / 餘額不足(需涵蓋 amount + fee);error 欄位為 Bad Request,code 欄位為左列碼,message 含具體原因 |
| 400 | DAILY_LIMIT_EXCEEDED | 超過每日提幣限額(message 含限額與今日已用額度;error 欄位為舊值 DailyLimitExceeded 相容保留) |
| 403 | 2FA_REQUIRED / 2FA_INVALID | 客戶已啟用 2FA 但未帶/帶錯 x-2fa-token |
| 403 | VAULT_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 值 | 網路 | 地址格式 | 手續費 | 可用性 |
|---|---|---|---|---|
TRC20 | TRON(TRC-20) | T 開頭、34 碼 | 1 USDT | 預設,所有商戶可用 |
BEP20 | BSC(BNB Smart Chain) | 0x + 40 碼 hex(EIP-55) | 1 USDT | 需商戶開通;僅支援 USDT |
ARB | Arbitrum One | 0x + 40 碼 hex(EIP-55,與 BEP20 同格式、不同網路) | 1 USDT | 需商戶開通;僅支援 USDT |
功能探測:GET /api/wallet/withdraw/config
configs[] 每條目新增 chain 欄位(加法)。 TRC20 條目恆在且排前;BEP20 / ARB 條目僅在貴司商戶開通該鏈後才會出現(附加在陣列尾部)—— 前端可以此作為功能探測:有對應鏈的條目才顯示該鏈提幣入口,無需寫死開關。 頂層 network: "TRC20" 欄位保留不動(相容)。
{
"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 字串傳遞,貴司無需處理精度差異
POST https://stellabit.cc/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) | 說明 |
|---|---|---|
| 400 | UNSUPPORTED_CHAIN | chain 未開放(貴司商戶未開通該鏈);message 為 Chain BEP20 is not available for withdrawal(ARB 同理) |
| 400 | UNSUPPORTED_CHAIN_CRYPTO | 該鏈支援但幣種未開(BEP20 / ARB 僅 USDT) |
| 400 | CHAIN_TEMPORARILY_DISABLED | 運維暫停該鏈提幣,請稍後重試 |
| 400 | INVALID_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 提幣完成事件範例:
{
"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"。
curl "https://stellabit.cc/api/wallet/deposit/address?crypto=USDT&chain=BEP20" \
-H "Authorization: Bearer $TOKEN"{
"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 保留不動 |
logIndex | EVM 交易內的 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 充值到帳事件範例:
{
"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 |
| 支援幣種 | USDT | USDT | USDT |
💡 對接建議
充值到帳以 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 | 需要 | 訂單詳情;每次呼叫同步供應商最新狀態,適合輪詢 |
curl "https://stellabit.cc/api/swap/quotes?from=usdttrc20&to=btc&amount=100" \
-H "Authorization: Bearer $TOKEN"| HTTP | 錯誤碼 | 說明 |
|---|---|---|
| 503 | SWAP_UNAVAILABLE | 閃兌未開放(無啟用中的供應商) |
| 400 | SWAP_VALIDATION | 參數不合法(幣種不支援、金額超出範圍等) |
| 400 | INSUFFICIENT_BALANCE | sell 方向扣帳時資金帳戶餘額不足 |
| 502 | SWAP_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呼叫
POST /api/2fa/send-otp(purpose 對應操作:提幣用 withdraw、劃轉用 transfer) - 2客戶自 Email 取得 6 位驗證碼
- 3發起操作時以
x-2fa-tokenheader 帶入驗證碼
curl -X POST https://stellabit.cc/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,請依指示退避重試。