接入概覽

iBitPay 開放介面讓你的系統直接向客戶收取法幣（入金）、向收款人支付法幣（出金），平台按匯率用 USDT 和你結算。

接入步驟

1. 開通：聯繫平台開通商戶帳號和開放介面。
2. 拿到介面地址和密鑰：登入商戶後台，在「開發者 → API 與回調」檢視介面地址、公鑰和私鑰（要先通過安全驗證和資金密碼）。介面地址和兩把鑰匙都不要公開，見安全建議。
3. 設定 IP 白名單：把呼叫介面的伺服器出口 IP 填進白名單。不在白名單裡的請求會被拒絕（40005）。
4. 設定回調地址：分別填入金回調地址、出金回調地址（必須是 https）。也可以在每筆訂單裡單獨指定。
5. 聯調：聯繫平台把你的商戶先接到測試交易員，用小額訂單把下單、回調、查詢走通，再正式開放給客戶。

介面地址

介面地址在商戶後台「開發者 → API 與回調」裡，和密鑰在同一頁。每個介面的完整地址 = 介面地址 + 文件裡寫的路徑，例如「介面地址 + /api/open/order/createBuyOrder」。

通用約定

• 請求：全部是 POST，Content-Type: application/json。業務參數先加密，再放進請求體，格式見請求格式與加密。

• 回傳：HTTP 狀態碼都是 200，以回傳內容裡的 code 為準：

  { "code": 0, "message": "success", "data": { } }

  code 為 0 表示成功，其他值見錯誤碼。message 是英文說明。回傳的內容不加密。

• 欄位名：回傳的欄位名是小駝峰（如 merchantOrderNo）；請求參數的欄位名不區分大小寫。

• 金額：法幣金額必須大於 0、最多兩位小數。回傳裡的數字最多保留兩位小數（匯率也是）。建議用十進制類型處理金額，不要用浮點數直接比較。

• 時間：回傳的時間格式是 yyyy-MM-dd HH:mm:ss，時區 UTC+8，不帶時區標記。

• 空值：回傳裡沒有值的文字欄位是空字串 ""，不是 null。

• 商戶訂單號：每筆訂單都請自己生成並保存一個唯一的 merchantOrderNo。查詢、對帳、核對回調都靠它，同一個號不能重複下單（40007），這也能防止網路超時後重試造成重複出款。

• 頻率：平台有防刷限制，短時間內請求過多會被暫時封禁 IP。建議每秒不超過 10 次請求，查詢類介面不要輪詢過密，到帳以回調為準。

一筆入金的流程

1. 你的系統呼叫建立入金訂單，拿到收銀台地址，把客戶帶過去。
2. 客戶在收銀台按頁面上的收款帳戶付款。
3. 平台確認收到錢後，訂單變成「已釋放」（6），平台向你的入金回調地址發通知。
4. 你收到回調後，先用查詢訂單複核狀態和金額，再給客戶入帳，然後回傳 success。
5. 平台收到 success，訂單變成「成功」（3）。USDT 在訂單釋放時已經記入你的餘額。

自建收銀台的流程見建立入金訂單（自建收銀台）。

一筆出金的流程

1. （可選）呼叫查詢收款方式，知道每個法幣要填哪些收款資訊。
2. 呼叫建立出金訂單。平台按出金匯率從你的 USDT 餘額里扣款並凍結。
3. 出款處理成功（4）或被拒絕（5）後，平台向你的出金回調地址發通知；被拒絕的會退回 USDT。
4. 你收到回調後用查詢訂單複核，再更新自己的訂單。

介面列表

分類	介面	路徑
收款	建立入金訂單（收銀台）	/api/open/order/createBuyOrder
收款	建立入金訂單（自建收銀台）	/api/open/order/createBuyOrder2
收款	標記已付款	/api/open/order/complete2
收款	取消訂單	/api/open/order/cancel2
收款	獲取入金匯率	/api/open/order/getBuyRate
出款	建立出金訂單	/api/open/order/createSellOrder
出款	獲取出金匯率	/api/open/order/getSellRate
出款	查詢收款方式	/api/open/order/getPaymentMethods
查詢	查詢訂單	/api/open/order/getDetail
查詢	查詢餘額	/api/open/order/getBalance
查詢	查詢資金流水	/api/open/order/getFlows
查詢	查詢黑名單	/api/open/blocked/user/list