建立加密貨幣充值訂單
客戶用 USDT 或 USDC 在鏈上付款,到帳後記入你的 USDT 餘額。每張訂單有一個專屬收款地址,回傳平台收銀台地址(頁面上只有加密貨幣付款),也回傳收款地址和應付數量,方便你自己做付款頁。到帳後平台回調通知你。
POST
/api/open/order/createCryptoDeposit完整地址 = 介面地址 + 這個路徑。介面地址在商戶後台「開發者 → API 與回調」檢視。
需要:IP 白名單、開放介面已開通、加密貨幣充值已為你開通(找平台營運人員開通)、設定了入金回調地址(或本單傳 callbackUrl)。
也可以繼續用建立入金訂單,傳 paymentType = 101 / 102 / 103,效果和本介面一樣。
支援的網路和幣種
| network | 幣種 | paymentType(入金介面用) |
|---|---|---|
TRC20(TRON) | USDT | 101 |
BEP20(BNB Smart Chain) | USDT | 102 |
BEP20(BNB Smart Chain) | USDC | 103 |
USDC 按 1:1 折成 USDT 入帳。每筆折成 USDT 不低於 100(以查詢收款方式回傳的 minAmount 為準)。
請求參數
加密前的 JSON:
| 參數 | 類型 | 必填 | 說明 |
|---|---|---|---|
merchantNo | string | 是 | 商戶號,和請求外層的一樣 |
merchantOrderNo | string | 強烈建議 | 你的商戶訂單號,最長 50 位,同一個商戶不能重複(和入金訂單一起查重,40007)。不傳時平台隨機生成 |
amount | number | 是 | 金額,大於 0、最多 6 位小數 |
currencyType | string | 是 | USDT / USDC:amount 就是要收的幣數量;法幣程式碼(如 CNY):按下單時的匯率折成幣,匯率鎖定在訂單上 |
payCoin | string | 否 | 收哪種幣:USDT / USDC。不傳時:currencyType 是幣就收這種幣,是法幣就收 USDT |
network | string | 是 | TRC20 或 BEP20 |
redirectUrl | string | 否 | 付款完成後收銀台「回傳商戶」按鈕的地址 |
callbackUrl | string | 否 | 本單的回調地址,不傳用商戶後台的入金回調地址 |
json
{
"merchantNo": "你的商戶號",
"merchantOrderNo": "C20261021001",
"amount": 200,
"currencyType": "USDT",
"network": "TRC20",
"redirectUrl": "https://shop.example.com/pay/done"
}回傳
| 欄位 | 類型 | 說明 |
|---|---|---|
url | string | 收銀台地址(只有加密貨幣付款),把客戶帶過去 |
orderNo | string | 平台訂單號(CD 開頭) |
merchantOrderNo | string | 你的商戶訂單號 |
payAddress | string | 本單專屬收款地址,只用於這一單 |
payNetwork | string | TRC20 / BEP20 |
payCoin | string | USDT / USDC |
payAmount | number | 客戶應付的幣數量。按法幣下單時是折算後向上取整到 2 位 |
expireAt | string | 付款截止時間,UTC+8,yyyy-MM-dd HH:mm:ss |
json
{
"code": 0,
"message": "success",
"data": {
"url": "https://收銀台域名/crypto/?orderId=…&checkoutToken=…",
"orderNo": "CD20261021120000123456",
"merchantOrderNo": "C20261021001",
"payAddress": "T…(本單專屬地址)",
"payNetwork": "TRC20",
"payCoin": "USDT",
"payAmount": 200,
"expireAt": "2026-10-21 13:00:00"
}
}收銀台地址裡帶有這筆訂單的訪問憑證,只發給這位客戶本人,不要公開。
自己做付款頁時要提醒客戶
- 只能轉對應網路的對應幣種,轉錯網路或幣種的錢無法自動找回;
- 按
payAmount轉帳,手續費由客戶的錢包另付,到帳數量不要少於應付數量; - 收款地址只用於這一單,不要保存下來重複使用。
到帳規則
| 情形 | 結果 |
|---|---|
| 到帳 ≥ 應付 | 按實際到帳入帳,多付的照樣入帳(查單 overpaid = true) |
| 到帳 < 應付,但這一筆折成 USDT ≥ 最低額 | 按實際到帳入帳(查單 underpaid = true) |
| 這一筆折成 USDT < 最低額 | 不自動入帳,平台人工處理 |
| 分幾次付 | 每一筆各自判斷、各自入帳、各自回調 |
| 付款截止後 24 小時內到帳 | 照樣自動入帳並回調 |
| 超過 24 小時才到帳、風控審核中 | 訂單顯示「待釋放」,平台人工處理 |
入帳要等區塊確認:TRC20 19 個塊(約 1 分鐘),BEP20 15 個塊(約 15 秒);單筆 ≥ 10000 USDT 的訂單確認數加倍。
常見錯誤
| code | 原因 |
|---|---|
| 40016 | 加密貨幣充值沒為你開通;network 不是 TRC20 / BEP20;payCoin 不是 USDT / USDC;這個網路暫不支援這種幣(如 TRC20 + USDC) |
| 40019 | amount 不大於 0、超過 6 位小數,或折成 USDT 低於最低額 |
| 40010 | currencyType 是法幣但這個法幣不可用 / 沒有匯率 |
| 40017 | 你沒開通這個法幣 |
| 40007 | 商戶訂單號重複 |
| 40000 | 商戶訂單號超過 50 位 |
其他通用錯誤(簽名、IP 白名單等)見錯誤碼。
訂單狀態
| orderState | 含義 |
|---|---|
| 1 | 待付款 |
| 2 | 待釋放(鏈上已看到轉帳,在等區塊確認;或到帳在人工審核) |
| 6 | 已釋放(已記入你的餘額,會回調你) |
| 3 | 成功(這張單每一筆到帳的回調你都回復了 success) |
| 4 | 已取消 |
| 5 | 已過期(截止前沒有到帳) |
用查詢訂單隨時可以查到當前狀態和鏈上明細。