💳 原生收銀台整合

API 更新通知

最近 API 端點和參數有更新。請參考變更紀錄以了解詳情。

Native Checkout API：用戶可以掃描 QR code 或複製您網站/應用程式構建的結帳頁面上的地址來進行支付。

整合 Native Checkout API 以為您的網站/應用程式構建結帳頁面。用戶在您的網站/應用程式內支付。無需引導他們到外部頁面。完全掌控您用戶的結帳體驗。

📦 1. 建立訂單

介面說明：透過此介面提交支付訂單並獲取收款資訊。
介面地址：POST /api/order/create

請求參數

欄位	類型	必填	說明
out_trade_no	string	是	商家訂單 ID
currency_id	int	是	全域唯一貨幣 ID
`fiat_name`	string	否	法幣名稱 (USD / USDT / JPY / CHF / CAD / NOK / SEK / HKD / SGD / KRW / TWD / CNY / INR / BRL / MXN / ZAR / RUB / TRY / EUR / GBP / AUD / VND / THB)
fiat_amount	string	否	法幣金額 ("1.2")
token_amount	string	否	代幣金額
callback_url	string	否	回調 URL
time_out	int64	否	10位數過期時間戳，填寫 0，預設為 30 分鐘 (1753513764)

回應欄位說明

欄位	類型	說明	範例
trade_no	string	交易 ID	"20250629153045a7b3c9d2e5f8a1b4c6"
chain	string	區塊鏈網路	"Tron"
token	string	加密貨幣代幣	"TRX"
contract	string	代幣合約地址	"TRX"
amount	string	交易金額	"15.724197"
mode	string	支付模式	"address"
pay_address	string	收款人地址	"TSg8kWPE2s7z5Lon6bSnZZrYnquGHx2..."
time_expire	integer	過期時間戳	1753515371
decimal	integer	代幣精度	6
chain_id	integer	鏈 ID	3448148188
equity	integer	權益值	1
create_time	integer	建立時間戳	1753513571
amount_collected	string	已收金額	"0"
need_confirms	integer	需要的確認數	0
already_confirms	integer	目前確認數	0
entrust_url	string	支付 URL	"https://checkout.pay.halochat.io/20260....b876498e0771e1"
referer	string	推薦人資訊	""
chain_info	object	鏈資訊	`{"token": "TRX", "rpc": "...", ...}`

成功回應範例

{
  "code": 0,
  "msg": "success",
  "data": {
    "trade_no": "20260317173635066d54f5b6c7269d41",
    "chain": "Tron",
    "token": "TRX",
    "contract": "TRX",
    "amount": "16.556743",
    "mode": "address",
    "pay_address": "THgSjcyhyxfzrjtS7VYw1vnHvb7QkMsY...",
    "time_expire": 1773741995,
    "decimal": 6,
    "chain_id": 3448148188,
    "equity": 1,
    "create_time": 1773740196,
    "amount_collected": "",
    "need_confirms": 0,
    "already_confirms": 0,
    "entrust_url": "https://checkout.pay.halochat.io/20260317173635066d54f5b6c7269d41",
    "referer": "",
    "chain_info": {
      "token": "TRX",
      "abi": "",
      "rpc": "https://nile.trongrid.io",
      "browser_url": "https://nile.tronscan.org/#/transaction",
      "decimal": 6,
      "logo": "https://halo-n.oss-ap-southeast-1.aliyuncs.com/png/202505/45d1f4b5-b80f-4331-af78-ec557f97d832.png",
      "series": "Tron",
      "monitor_chain_id": 3448148188
    }
  }
}

🔍 2. 查詢訂單

介面說明：使用此介面查詢訂單狀態。
介面地址：POST /api/order/detail

請求參數

欄位	類型	必填	說明
trade_no	string	是	交易 ID

回應欄位說明

欄位	類型	說明	範例
trade_no	string	交易 ID (平台)	"20250629153045a7b3c9d2e5f8a1b4c6"
out_trade_no	string	商家訂單 ID	"202401011753513569"
chain	string	區塊鏈網路	"Tron"
token	string	加密貨幣代幣	"TRX"
contract	string	代幣合約地址	"TRX"
fiat_name	string	法幣名稱	"USD"
fiat_amount	string	應付法幣金額	"5"
amount	string	應付加密貨幣金額	"15.724197"
mode	string	支付模式	"address"
pay_address	string	收款加密貨幣地址	"TSg8kWPE2s7z5Lon6bSnZZrYnquGHx2bsj"
status	string	交易狀態	"TO-BE-PAID"
time_expire	integer	過期時間戳 (Unix)	1753515371
decimal	integer	代幣精度	6
chain_id	integer	鏈 ID	3448148188
equity	integer	權益值	1
create_time	integer	建立時間戳 (Unix)	1753513571
amount_collected	string	已收金額	"0"
need_confirms	integer	需要的確認數	0
already_confirms	integer	目前確認數	0
entrust_url	string	支付 URL (如適用)	""
referer	string	推薦人資訊	""
chain_info	object	鏈資訊	`{"token": "TRX", "rpc": "...", ...}`

成功回應範例

{
  "code": 0,
  "msg": "success",
  "data": {
    "trade_no": "20260317173635066d54f5b6c7269d41",
    "out_trade_no": "ORDER_1773740195363",
    "chain": "Tron",
    "token": "TRX",
    "contract": "TRX",
    "fiat_name": "USD",
    "fiat_amount": "5",
    "amount": "16.556743",
    "mode": "address",
    "pay_address": "THgSjcyhyxfzrjtS7VYw1vnHvb7QkMsY7w",
    "status": "TO-BE-PAID",
    "time_expire": 1773741995,
    "decimal": 6,
    "chain_id": 3448148188,
    "equity": 1,
    "create_time": 1773740196,
    "amount_collected": "0",
    "need_confirms": 0,
    "already_confirms": 0,
    "entrust_url": "",
    "referer": "",
    "chain_info": {
      "token": "TRX",
      "abi": "",
      "rpc": "https://nile.trongrid.io",
      "browser_url": "https://nile.tronscan.org/#/transaction",
      "decimal": 6,
      "logo": "",
      "series": "",
      "monitor_chain_id": 0
    }
  }
}

💱 3. 價格匯率

介面說明：獲取 TOKEN 與法定貨幣之間的當前匯率。
介面地址：POST /api/order/exchange-rates

請求參數

欄位	類型	必填	說明
currency_id	int	是	全域唯一貨幣 ID
`fiat_name`	string	是	法幣縮寫 (USD / USDT / JPY / CHF / CAD / NOK / SEK / HKD / SGD / KRW / TWD / CNY / INR / BRL / MXN / ZAR / RUB / TRY / EUR / GBP / AUD / VND / THB)
fiat_amount	string	是	法幣金額

回應欄位說明

欄位	類型	說明
amount	string	金額
exchange_rate	string	匯率

成功回應範例

{
  "code": 0,
  "msg": "success",
  "data": {
    "amount": "0.00001971",
    "exchange_rate": "100"
  }
}

📋 4. 應用代幣列表（含餘額）

介面說明：回傳目前應用（X-Appid）已啟用收款之加密資產，以及依地址聚合的餘額（與 POST /api/account/balance 相同口徑）。並非平台全部幣種目錄；全系統支援代幣請見 §5 代幣列表。
介面地址：POST /api/currency/app-token-list
請求參數：請求體為 {}，鑑權標頭與其他 API 相同。

回應欄位說明

根物件：

欄位	類型	說明
code	integer	業務碼，`0` 表示成功
msg	string	訊息
data	array	目前應用已啟用收款之代幣與餘額

data[] 元素：

欄位	類型	說明
currency_id	integer	全域唯一貨幣 ID
chain	string	鏈名稱
network	string	網路名稱
token	string	代幣符號
contract	string	合約地址
chain_id	integer	鏈 ID
logo	string	代幣 Logo URL
decimal	integer	代幣精度
balance	string	總餘額（十進位字串）
operable_balance	string	可操作餘額
frozen_amount	string	凍結金額
status	integer	狀態：1 — 啟用，2 — 停用
transaction_enabled	boolean	是否啟用收款（本介面回傳均為 `true`）

成功回應範例

{
  "code": 0,
  "msg": "success",
  "data": [
    {
      "currency_id": 46,
      "chain": "Tron",
      "network": "Nile",
      "token": "JST",
      "contract": "TF17BgPaZYbxxxxhriubPDsA7ArKoLX3",
      "chain_id": 3448148188,
      "logo": "https://halo-n.oss-ap-southeast-1.aliyuncs.com/png/202505/xxx-c3f3-4d5d-a9b5-0143d78326f9.png",
      "decimal": 18,
      "balance": "0.785074013",
      "operable_balance": "0.785074013",
      "frozen_amount": "0",
      "status": 1,
      "transaction_enabled": true
    }
  ]
}

📋 5. 代幣列表

介面說明：獲取系統支援的 Token 列表。應用內已啟用收款之代幣與餘額請使用 §4 應用代幣列表。
介面地址：POST /api/currency/token-list
請求參數：無

回應欄位說明

欄位	類型	說明
currency_id	int	全域唯一貨幣 ID。
chain	string	鏈
network	string	網路
token	string	代幣
contract	string	合約地址。如果目前主要貨幣與貨幣名稱相同，該值將與貨幣名稱一致。
chain_id	int	鏈 ID。僅乙太坊系列有值。
logo	string	標誌
decimal	int	精度

成功回應範例

{
  "code": 0,
  "msg": "success",
  "data": [
    {
      "currency_id": 46,
      "chain": "Tron",
      "token": "JST",
      "network": "Nile",
      "contract": "TF17BgPaZYbxxxxhriubPDsA7ArKoLX3",
      "chain_id": 3448148188,
      "logo": "https://halo-n.oss-ap-southeast-1.aliyuncs.com/png/202505/xxx-c3f3-4d5d-a9b5-0143d78326f9.png",
      "decimal": 18
    }
  ]
}

💸 6. 提現

介面說明：商家可透過此介面將現金提取到指定地址。
介面地址：POST /api/payout/create

請求參數

欄位	類型	必填	說明
currency_id	int	是	全域唯一貨幣 ID
amount	string	是	貨幣基礎金額
to_address	string	是	收款人地址
callback_url	string	否	回調地址 (預設為商家 APPID 設定的回調地址)
google_code	string	否	Google 驗證碼 (如果目前應用程式啟用了驗證，則為必填)

成功回應範例

{
  "code": 0,
  "msg": "success",
  "data": {
    "cost": "0.801502",
    "actual_receipt": "0.001",
    "trade_no": "202603171746187e582d1b789b27ea55",
    "estimated_transfer": "0"
  }
}

📊 7. 查詢轉帳狀態

介面說明：查詢提現的訂單狀態。
介面地址：POST /api/payout/detail

請求參數

欄位	類型	必填	說明
trade_no	string	是	交易單號

回應欄位說明

欄位	類型	說明
trade_no	string	交易 ID
service_charge	string	服務費
gas	string	GAS 費用
token	string	貨幣
amount	string	金額
target_address	string	收款人地址
start_time	int	開始時間
created_time	int	建立時間
status	string	交易狀態 (CONFIRMING-PROGRESS: 確認中, PAID: 成功, FAIL: 失敗, CANCEL: 已取消, PROGRESS: 處理中)

成功回應範例

{
  "code": 0,
  "msg": "success",
  "data": {
    "service_charge": "0.000002",
    "gas": "0.8015",
    "amount": "0.001",
    "status": "TRANSFER",
    "target_address": "TDYiTL3pke3T9BsoTotbKb922WsXQCmSxv",
    "start_time": 1773740882,
    "created_time": 1773740882,
    "trade_no": "202603171748020a09cbb09b4846bc99",
    "token": "DK7bKg181cC7pBgX3PxSIH2WdklZ5IPT"
  }
}

💰 8. 檢查餘額

透過此 API 擷取應用程式的單一貨幣餘額資訊。

介面地址：POST /api/account/balance

請求參數

欄位	類型	必填	說明
currency_id	int	是	全域唯一貨幣 ID

回應欄位說明

欄位	類型	說明
currency_id	int	全域唯一貨幣 ID
balance	string	剩餘數量
balance_usdt	string	轉換為 USDT 的剩餘數量價值
operable_balance	string	可操作數量 (如果錢包地址中的主貨幣金額過低無法收集，該錢包地址將無法使用。請參考個人中心 => 網路設定取得最小可操作閾值。)
operable_balance_usdt	string	可操作數量的價值
chain	string	鏈名稱
network	string	網路
token	string	代幣
contract	string	合約地址 (主代幣為縮寫代幣名稱)

成功回應範例

{
  "code": 0,
  "msg": "success",
  "data": {
    "currency_id": 46,
    "balance": "0.785074013",
    "operable_balance": "0.785074013",
    "operable_balance_usdt": "0.043642",
    "balance_usdt": "0.043642",
    "chain": "Tron",
    "network": "Nile",
    "token": "JST",
    "contract": "TF17BgPaZYbz8oxbjhriubPDsA7ArKoLX3"
  }
}

🖼️ 9. 靜態支付 QR Code

介面說明：透過 API 申請獨立的靜態支付地址。它將回調對應 APPID 的 CallBack 介面地址。
介面地址：POST /api/payment-qr-code/create

請求參數

欄位	類型	必填	說明
name	string	是	QR code 名稱
currency_id	int	是	全域唯一貨幣 ID
amount	string	否	預設支付金額 (可以為 "0")

回應欄位說明

欄位	類型	說明	範例
id	int	唯一 QR code ID	115
address	string	靜態支付地址	"TXd8UKLtLqk5V15v7e3W43ZdNw6berp6DP"

成功回應範例

{
  "code": 0,
  "msg": "success",
  "data": {
    "id": 115,
    "address": "TXd8UKLtLqk5V15v7e3W43ZdNw5berp6DP"
  }
}

💡

這需要 QR code 應用程式的 APPID 來向此 API 發出請求。

📌 檢視錯誤代碼

📦 1. 建立訂單​

請求參數​

回應欄位說明​

成功回應範例​

🔍 2. 查詢訂單​

請求參數​

回應欄位說明​

成功回應範例​

💱 3. 價格匯率​

請求參數​

回應欄位說明​

成功回應範例​

📋 4. 應用代幣列表（含餘額）​

回應欄位說明​

成功回應範例​

📋 5. 代幣列表​

回應欄位說明​

成功回應範例​

💸 6. 提現​

請求參數​

成功回應範例​

📊 7. 查詢轉帳狀態​

請求參數​

回應欄位說明​

成功回應範例​

💰 8. 檢查餘額​

請求參數​

回應欄位說明​

成功回應範例​

🖼️ 9. 靜態支付 QR Code​

請求參數​

回應欄位說明​

成功回應範例​

📦 1. 建立訂單

請求參數

回應欄位說明

成功回應範例

🔍 2. 查詢訂單

請求參數

回應欄位說明

成功回應範例

💱 3. 價格匯率

請求參數

回應欄位說明

成功回應範例

📋 4. 應用代幣列表（含餘額）

回應欄位說明

成功回應範例

📋 5. 代幣列表

回應欄位說明

成功回應範例

💸 6. 提現

請求參數

成功回應範例

📊 7. 查詢轉帳狀態

請求參數

回應欄位說明

成功回應範例

💰 8. 檢查餘額

請求參數

回應欄位說明

成功回應範例

🖼️ 9. 靜態支付 QR Code

請求參數

回應欄位說明

成功回應範例