下單介面|TokenEpay

下單介面:

建立一筆加密貨幣支付訂單。成功後返回系統訂單號、收款地址、應付金額與過期時間；使用者必須在有效期內向該地址轉入指定金額。

請求

項	值
請求方法	POST (僅支援POST, 不支援GET)
請求地址	{閘道域名}/api/pay/gateway?apikey={apikey}
Content-Type	application/x-www-form-urlencoded
字元集	UTF-8

POST請求參數

參數名	必填	類型	說明	示例
merchant_id	是	int	商戶 ID	10000
merchant_order	是	string	商戶訂單號，需保證唯一	T202611010001
amount	是	string	訂單金額，兩位小數。需在商戶的最小 / 最大單筆金額範圍內	100.00
pay_mode	是	string	支付方式：`1`=API 介面下單（通用）	1
chain_id	是	int	鏈 ID：`1`=ETH，`56`=BNB，`137`=POL，`728126428`=TRON	56
token_type	是	int	代幣類型：`1`=USDT，`2`=USDC	1
product_name	是	string	商品 / 訂單名稱，用於展示與對賬	vip
return_url	否	string	同步跳轉地址, 暫未啟用同步跳轉, 可空	https://example.com/pay/return
notify_url	是	string	非同步通知地址，必須是合法的 http/https 連結	https://example.com/pay/notify
ip	是	string	下單使用者的客戶端 IP，必須攜帶使用者真實IP，用於風控相關	203.0.113.10
parameters	否	string	自定義擴充套件參數，最長 200 個字元，通知時原樣帶回；不能是陣列 / 物件 / JSON 字串	order-123
address_id	否	string	指定收款錢包 ID，支援逗號分隔多個（如 `1,2,3`），多個時隨機選擇；不傳則由閘道在全部可用錢包中隨機	1,2
sign	是	string	參數簽名，規則見簽名規則，32 位小寫 MD5	adde550d…

可選參數與簽名

只要參數出現在 POST body 中，就必須參與簽名。不需要的可選參數請直接不傳，避免出現 address_id= 這類空值參與簽名造成困惑。

響應示例

{
  "code": 1,
  "msg": "訂單建立成功",
  "time": 1792945542,
  "data": {
    "system_order": "P202610260025421871",
    "merchant_order": "T202611010001",
    "amount": "100.00",
    "pay_amount": "100.37",
    "service_fee": "0.37",
    "network": "BNB Smart Chain",
    "token_name": "USDT",
    "chain_id": 56,
    "token_type": 1,
    "to_address": "0x4E5e48661B31........2c4425bBA6Fae0aF09",
    "status": 0,
    "timeout_minutes": 35,
    "expiry_time": 1792947642
  }
}

響應欄位

欄位	類型	說明
system_order	string	網關係統訂單號，回調與對賬的唯一標識
merchant_order	string	原樣返回商戶訂單號
amount	string	訂單金額（兩位小數）
pay_amount	string	使用者實際應付金額，已包含隨機微調小數，請按此金額收款
service_fee	string	本次金額微調差額
network	string	鏈名稱，如 `BNB Smart Chain`
token_name	string	代幣名稱，`USDT` / `USDC`
chain_id	int	鏈 ID
token_type	int	代幣類型，`1`=USDT，`2`=USDC
to_address	string	收款地址，使用者必須向該地址轉帳
status	int	訂單狀態，建立成功時為 `0`（待支付）
timeout_minutes	int	訂單有效期（分鐘）
expiry_time	int	過期時間（Unix 秒），到期後訂單不可支付

關鍵規則

冪等：同一商戶訂單號重複提交

原訂單已支付（狀態 1）或手動補單（狀態 2）：返回code= 10011，提示訂單已支付。
原訂單待支付（狀態 0）或已過期（狀態 3）：返回code= 10012，提示訂單已存在。
因此訂單過期後請使用新的 merchant_order 重新下單，不要複用舊單號。

金額與收款

使用者必須轉帳 pay_amount，而不是 amount。
金額多轉、少轉或轉錯代幣，都無法自動匹配，可能需要人工處理。
amount 需在商戶配置的最小 / 最大單筆金額範圍內，否則返回code= 10007。
下單時閘道會預先校驗商戶餘額；餘額不足以支付本次服務費時返回code= 10014。

地址選擇與有效期

未傳 address_id：在商戶全部“啟用且支援該鏈 / 代幣、未超限額”的錢包中隨機分配。
傳入 address_id：只在這些指定錢包中選擇，且必須屬於當前商戶；不可用的錢包會被跳過，全部不可用則返回code= 10018。
訂單到期後自動變為已過期，請按 expiry_time 做倒計時並及時引導使用者重新下單。