← 全部接入指南接入指南 · API / 服務端 / 手機端透過 MochiPay API 接入加密貨幣支付
從應用建立和查詢支付訂單。PHP Demo 1.2.0 支援 PHP 7.0–8.4，提供 order.php、callback.php、含兩種展示模式的 checkout.php、本地彈窗資源和英文 README。站內（預設）或 HPP 均使用同一支付訂單。
演示流程 · 示例配置 · 請用小額真實付款驗證自己的設定。
付款流程示意圖，站內支付與 HPP 使用同一筆訂單，最終狀態由伺服器驗證。檢視完整付款結果
此演示使用示例資料。請在自己的環境中用小額真實付款驗證這些結果；實際支付金額和確認要求由訂單決定。
01 · 準備 MochiPay 賬戶
- 建立賬戶 與 啟用訂閱.
- 開啟 錢包，選擇新增 HD 錢包 → 生成新錢包，私下備份助記詞並儲存，啟用測試使用的資產 / 網路。
- 在此處設定客戶能識別的顯示名稱 賬戶資料.
- 開啟 API 憑證 並複製 API Key 和已儲存的 API Secret。首次設定若未儲存金鑰，請重新生成並妥善儲存。重新生成現有金鑰會使使用舊金鑰的接入失效。
完成標準： 你的訂閱與收款錢包均有效，並已取得下方所需憑證。
檢視圖文賬戶設定 →選擇站內支付或 HPP
| 模式 | 客戶體驗 | 伺服器責任 |
|---|
| 站內支付（預設） | 在你自己的域名展示付款對話方塊，包含精確數量、地址、網路、二維碼及狀態。 | 建立並儲存付款繫結，透過自己的後端查詢，只返回安全的付款展示資訊。 |
|---|
| HPP | 跳轉到返回的 MochiPay payment_url。 | 儲存相同訂單繫結，並透過伺服器間通訊驗證回撥 / 返回。 |
|---|
結賬模式是接入端的偏好設定，並非 API 欄位。兩種連結使用同一訂單，切換模式時不要建立新訂單。經典 SaaS 僅支援 HPP。
支援全部六種方式：USDT_TRC20、USDC_ERC20、BTC_BITCOIN、ETH_ERC20、SOL_SOLANA 和 TRX_TRON。唯一金額方向預設為 UP，也支援 DOWN。每種提供的方式都需啟用對應收款錢包。
03 · 下單並支付測試訂單
開啟 order.php，用唯一商戶訂單編號及已配置支付方式建立小額演示訂單。選擇 ON_SITE 或 HPP，開啟建立結果的對應連結。結果也提供嵌入商城結賬和 PHP HPP 跳轉連結，兩者由 checkout.php 實現並使用同一訂單。
- 核對所選幣種和網路，並支付付款頁顯示的準確金額。
- 傳送 付款頁上的精確金額 傳送至顯示的收款地址，不能取整或複用其他訂單地址。
- 等待所需鏈上確認，並等 MochiPay 訂單狀態變為
PAID.
商城/API 示例可用美元標價。MochiPay 在建立訂單時鎖定匯率，唯一金額調整可能改變最終應付金額。請以收銀臺顯示金額付款。
成功檢查： MochiPay 訂單顯示 PAID 且已記錄交易，僅開啟瀏覽器返回頁不構成付款證明。
04 · 驗證結果與錢包收款
從應用按系統 order_id 查詢訂單。僅當驗證查詢返回 PAID，且匹配已儲存系統 ID、商戶編號、原始金額/幣種、所選資產/網路、收款地址、準確應付及預期實收金額時接受付款。以原子且冪等的本地事務履約。callback.php 使用私有演示記錄示範通知及瀏覽器返回驗證，不執行履約；請以生產資料庫和履約事務替換臨時記錄及回撥 TODO。閱讀附帶 README。
核對付款交易、收款地址與 MochiPay 訂單，檢視收款錢包或區塊鏈瀏覽器。資金已在您的收款錢包中，無需申請平臺提現。
使用相容錢包轉移資金，並等待鏈上確認。 閱讀收款錢包管理指南 →
錢包恢復與精確金額
在創建訂單之前堅持嘗試。目前的 PHP 演示在建立訂單之前保存了 request_id 和確切的有效負載。逾時後沒有儲存系統 ID，重試相同的有效負載和 request_id；相反，會查詢已知的 order_id。商家訂單參考可能會重複；使用系統訂單 ID 或儲存的請求 ID 來識別付款。在 PHP 或 JavaScript 浮點轉換之前將十進位回應值保留為字串；準確顯示pay_amount。捆綁的二維碼僅對地址進行編碼，因此客戶必須輸入顯示的金額。
開發自己的 API 客戶端時
使用 X-Mochi-Key 與 X-Mochi-Signature。建立訂單對準確的 JSON 正文做 HMAC-SHA256 簽名，並使用 Base64 編碼。查詢訂單對去掉開頭問號的準確查詢字串簽名。簽名金鑰必須儲存在服務端。
測試未完成時
無法建立支付選項或訂單
檢查訂閱狀態、已啟用收款錢包、支付方式程式碼、憑據及訂單幣種匯率對。外掛還需確認測試使用的商城範圍及顧客已啟用該支付方式。
付款仍在等待中或金額不足
核對交易的資產、網路、地址和準確應付金額，並等待所需確認數。請勿僅憑截圖或瀏覽器返回將商城訂單標記為已付款。
MochiPay 已付款，但商城 / 應用狀態未更新
確認通知/回撥端點能透過 HTTPS 公開訪問，且未被身份驗證或防火牆攔截。確認接入能查詢 MochiPay 並檢查錯誤日誌。僅收款連結更新 MochiPay，不會更新外部商城。
可選的開單重試去重
原有接入無需傳入 request_id 即可繼續使用。若要在超時後複用同一支付訂單，可先將可選 request_id 加入 JSON 正文，再按原方式計算 HMAC 簽名。
{"merchant_order_id":"STORE-1001","amount":25,"currency":"USD","payment_method":"USDT_TRC20","request_id":"STORE-1001:create:v1"}
使用 1–64 個 ASCII 字母、數字、點、底線、冒號或連字號。一個金鑰屬於一個商家和一個請求負載。重試時重複使用相同的金鑰和負載；回應保留現有欄位並傳回目前狀態的原始訂單。密鑰將被保留，不會自動過期。對於每個新結帳，請使用新的 request_id。 merchant_order_id可以保持不變：123、124、124建立三個獨立的系統訂單。較早的未付款訂單不會阻止創建。只有重試相同請求才會重複使用其 request_id 和未更改的負載。 WEB82.6 通告 request-id-v1；查詢已儲存的 request_id 以解決不確定的回應。重複的商家參考不是恢復密鑰。在整合包之前部署WEB82.6或更高版本； WEB82.7新增HPP取消/返回。
HTTP 409 REQUEST_IN_PROGRESS：按 Retry-After 指示稍後重試相同請求。HTTP 409 REQUEST_ID_CONFLICT：相同請求號傳入了不同內容。不要為了繞過超時而生成新請求號。ON_SITE 和 HPP 都可繼續使用返回的支付欄位或 payment_url。