HashNut 為企業提供安全、高效的數字資產支付基礎設施。企業只需整合 HashNut API，即可在網站及 App 接受數字資產支付。
資金直接進入商戶自託管錢包，商戶擁有資金 100% 控制權，資金安全級別高於傳統銀行及數字銀行。
私隱保護能力遠高於傳統支付體系及其他數字資產支付方案。
HashNut 支付引擎是一套完整的分布式 Web3 支付基礎設施，幫助企業在網站及手機 App 中無縫接受數字資產支付。
只有交易上鏈，本質仍是 Web 2.5。
全球首個、目前唯一真正面向企業的 Web3 解決方案。
支付由可信智能合約程式碼執行。
Claim 與 Withdraw 均由商戶主動發起，結算控制權始終掌握在企業手中。
HashNut 無法訪問或管理商戶資金，這是實現 100% 資金安全的架構基礎。
可對商戶及支付用戶提供全面私隱保護，保護能力遠高於傳統支付體系及其他數字資產支付方案。
查看完整行業覆蓋及支付場景。
查看應用場景
用戶只需點擊支付，即可完成交易
可通過掃描二維碼，或向專屬收款地址轉賬。
全球唯一在 DeFi 支付中同時整合批發商、代理及合作夥伴功能的解決方案。
企業最快 5 分鐘即可自主完成設定，效率業內領先。
全球首個、目前唯一完整的企業級 DeFi 解決方案，實現 100% 資金安全與即時結算。
兼容主流錢包、公鏈及代幣類型。
一鍵式支付體驗，可媲美微信支付，顯著優於其他數字資產支付方案。
支援幾乎所有主流錢包、公鏈、數字資產及央行數字貨幣（CBDC）生態。
支付流程可與商戶後台系統無縫對接，同步訂單、發票、物流及財務數據，形成完整連貫的業務流程。
同步訂單、發票、物流及財務數據。
資金直接進入商戶自託管錢包，商戶擁有資產 100% 控制權。
客戶從自己的錢包發送訂單指定的數字資產。
HashNut 檢測鏈上轉賬，並返回已確認的支付狀態。
零賬期。
選擇一種支付場景，查看客戶結賬、鏈上驗證及支付確認後的商戶業務流程。
HashNut 支付引擎可作為金融行為的核心入口，進一步拓展業務邊界及商業空間。
客戶向訂單指定的收款地址付款。
支付由智能合約管理，並進入由商戶控制的地址。
商戶發起 Claim，將已確認的收款地址餘額歸集至分賬合約。
商戶發起提款，將資金轉至指定地址。
數字資產支付正在快速增長。
年度最具創新區塊鏈項目，總冠軍。
總決賽入圍獎。
金融科技應用方案金獎，由香港特區政府及香港銀行學會相關機構評選。
年度初創企業大獎；商業解決方案優異獎。
傑出企業支付解決方案獎。
與香港城市大學數據科學學院開展聯合實習合作。
技術團隊成員包括來自微信支付、Monero 及 Visa 的前首席架構師、技術負責人和資深開發人員。
商務團隊成員包括 VISA Direct 前全球負責人、Cisco 前總經理，以及聯想聯合創始人。
NutPersonal 將支付、資產轉移與錢包管理整合到同一個個人體驗中，同時兼容現有錢包及數字資產。
用戶可自行選擇法幣或數字資產支付，支援 Visa、Mastercard、Google Pay、Apple Pay 等方式。
透過 HashNut 兌換及跨鏈基礎設施，可使用不同鏈上的不同代幣完成支付。
無需輸入複雜的區塊鏈地址，直接向暱稱付款，讓日常數字資產轉賬更簡單。
根據錢包活動生成資金流報告，更清晰地瞭解個人數字資產流動。
將個人錢包匯入 NutPersonal，在同一個入口管理資產與付款。
NutPersonal 可整合多個錢包，用於統一資產管理及支付。
可將錢包分組，並在付款時組合使用不同錢包中的資產。
NutPersonal 同時支援代理體系、品牌自訂錢包體驗，並可與 HashNut 支付引擎連接。
可直接通過 NutPersonal 建立多級代理體系，並在同一個介面統一管理。
可按企業品牌主題、Logo 及所需功能自訂 NutPersonal 錢包。
NutPersonal 可與 HashNut 支付引擎協同，用於支付及財務數據管理。
HashNut 企業及個人錢包產品均可為合作夥伴提供白標方案。
前往 App Store 或 Google Play 下載 HashNut App。
NutCard 可在任何國家使用，並支援您選擇的任何加密資產。
NutCard 為持卡用戶提供更簡潔的 KYC 開通流程。
NutCard 支援區域代理合作模式，協助合作夥伴拓展當地業務。
專屬管理後台，幫助合作夥伴高效管理業務營運及收益。
針對營運及商務需求，為合作夥伴提供一對一支援。
通過合作夥伴激勵及獎勵機制，支援區域業務持續拓展。
為在當地市場發展 NutCard 的合作夥伴提供區域網絡支援。
進入當前 NutCard 申請流程。
完成商戶帳戶設定，驗證完整資金路徑，接入支付 API，並為 HashNut 正式上線做好準備。
HashNut 是面向企業的數字資產支付基礎設施。客戶在鏈上向訂單指定的收款地址付款，HashNut 檢測支付狀態並同步至商戶業務流程，結算控制權始終由商戶掌握。
HashNut V4 採用 EOA 架構，並使用 2-of-2 MPC 收款地址。實施當前系統時，請確保 V4 帳戶、SDK 與 API 資料使用同一版本體系。
V4 商戶工具、SDK 與 API 行為應配套使用，不要在 V4 整合中混用 V3 介面示例。
go get github.com/nuttybounty/hashnut-sdk-go/v4HashNut 帳戶設定、支付處理、結算及 API 整合中使用的核心術語。
同一條鏈上的一個商戶錢包對應一個獨立 HashNut 商戶帳戶。每條鏈均擁有獨立的分賬合約、API 憑證及收款地址池。
分賬合約是 Claim 與 Withdraw 結算流程的核心智能合約。客戶付款先進入收款地址，再由商戶發起 Claim，將已確認餘額歸集到分賬合約。
由 MPC 控制、臨時分配給支付訂單的地址。客戶將訂單要求的數字資產發送到該訂單顯示的收款地址。
由商戶執行的桌面客戶端，用於處理設定及結算所需的錢包與 MPC 操作，包括部署、建立收款地址、代幣授權、Claim、Withdraw 與 Sweep。商戶私鑰及客戶端密碼始終保留在商戶本地電腦。
| 名稱 | 用途 |
|---|---|
accessKeyId | 商戶級伺服器請求使用的公開 API Key 標識。 |
secretKey | 私有 HMAC 簽名密鑰。必須儲存在伺服器端，絕不能暴露在前端程式碼中。 |
accessSign | 建立訂單時返回、與該訂單綁定的憑證，用於文檔所列的訂單級操作。 |
整數狀態值，從 INIT(0) 依次經過已支付 / 已確認狀態，直至 FINISH(4)；失敗、過期和取消使用負數終態。 SUCCESS(3) 是首個可安全履約的狀態。
Claim 將收款地址中已確認的餘額歸集到分賬合約。 Withdraw 將商戶可提款份額釋放到預設的提款地址。 Sweep 將 MPC 控制的收款地址中剩餘的原生 Gas 代幣歸集回商戶錢包。
請將資金位置與訂單狀態分開理解。支付成功並不代表商戶已經將資金提款。
客戶將訂單要求的數字資產發送到該訂單指定的收款地址。
資金進入訂單指定、由 MPC 控制的收款地址。HashNut 會自動檢測付款，結算操作則獨立進行。
商戶發起 Claim，將已確認的收款地址餘額歸集到分賬合約。
商戶發起 Withdraw，將分賬合約中的可提款份額轉至預設提款地址。
PAID 或 SUCCESS 反映的是訂單支付狀態；Claim 與 Withdraw 反映的是資金在結算路徑中的位置。兩者是有意分離的不同流程。
瞭解訂單如何從建立逐步進入可安全履約的狀態，以及通知在這一過程中扮演的角色。
文檔中會觸發 Webhook 的狀態包括 PAID, SUCCESS, FAILED，以及 EXPIRED。不要假設每次狀態變化都會觸發 Webhook。先驗證通知，再透過 Query Order 獲取權威的當前狀態。
當 Query Order 返回的權威狀態為 SUCCESS(3) 或更後的已支付終態，例如 FINISH(4)。履約操作必須具備冪等性，避免重復通知造成重復交付。
先準備好商戶側工具，並明確哪些設定可以後續再補。建議從小規模開始，完整驗證流程後再擴展到正式環境。
| 項目 | 用途 |
|---|---|
| HashNut MPC Client | 部署並管理結算基礎設施、收款地址、Claim、Withdraw 及相關私鑰操作。 |
| HashNut Dashboard | 建立和管理訂單、維護 API Key，並管理商戶設定。 |
| 項目 | 用途 |
|---|---|
| Windows 或 macOS 電腦 | 用於執行 HashNut MPC Client。 |
| 商戶錢包 | 支付 Gas，並作為一條鏈上一個獨立商戶帳戶的錢包。 |
| MetaMask or TronLink | 支援的 EVM 鏈使用 MetaMask；TRON 商戶後台登入使用 TronLink。 |
| 網絡原生代幣 | 準備足夠的鏈上原生代幣，用於支付後續操作所需 Gas。 |
| 提款地址 | Withdraw 後商戶份額最終到達的地址。 |
| 應用 URL | notifyUrl 用於伺服器通知， callbackUrl 用於瀏覽器返回。這兩個地址後續均可更新。 |
| notifyUrl | callbackUrl | |
|---|---|---|
| 方向 | HashNut → 商戶伺服器 | 客戶瀏覽器 → 商戶前端 |
| 是否需要公開網絡訪問？ | 是 | 不需要。本地開發時可使用 localhost。 |
| 用途 | 支付狀態通知 | 用戶體驗 / 瀏覽器返回 |
| 能否作為付款憑證？ | 先驗證通知，再 Query Order | 否 |
notifyUrl 用於伺服器到伺服器通信，callbackUrl 用於瀏覽器跳轉，兩者方向相反。
建立首個帳戶，並生成 5 個收款地址。
建立小額訂單並完成支付、Claim 與 Withdraw。
使用 Demo Shop 及 API 整合流程進行驗證。
驗證完成後再擴充收款地址池。
設定正式環境 URL、IP 限制、監控及營運責任。
在本地初始化商戶錢包，並為一條鏈上的一個商戶帳戶建立核心支付基礎設施。
在 Windows 或 macOS 上執行客戶端。商戶側私鑰操作均在客戶端本地完成，商戶錢包私鑰和 MPC Client 密碼必須保留在商戶電腦中。
根據電腦選擇當前 V4 MPC Client 的 Windows、macOS Intel 或 macOS Apple Silicon 版本。操作帳戶時，請將客戶端與本地 keys.db 工作區儲存在一起。
導入錢包後會建立本地 MPC 工作區，其中包括 keys.db。請在完成設定前做好備份。
一條鏈 + 一個商戶錢包 = 一個獨立 HashNut 帳戶。
Withdraw 後，商戶份額將發送到這個地址。
先使用小規模收款地址池完成驗證，再擴充容量。
notifyUrl 與 callbackUrl 後續可以更新，因此測試階段可先使用臨時開發地址。
設定流程會建立分賬合約、MPC 基礎設施、收款地址及 API 憑證。
| 儲存 | 原因 |
|---|---|
keys.db | 客戶端使用的本地 MPC 密鑰材料，請安全備份。 |
| 商戶錢包私鑰 | 需要獨立於 keys.db 儲存，請單獨備份。 |
| 帳戶資訊導出文件 | 用於記錄已建立帳戶及基礎設施的營運資訊。 |
accessKeyId | 商戶級 API 請求使用的公開標識。 |
secretKey | 伺服器端 HMAC 簽名密鑰，生成後請立即安全儲存。 |
開發者需要的是 API 憑證及帳戶標識。涉及商戶錢包私鑰的操作應始終由帳戶負責人通過商戶側 MPC Client 完成。
正式上線前，請端到端驗證帳戶、支付檢測、結算路徑及 API Key 均可正常工作。
確認已部署的帳戶結構及結算設定。
透過 Dashboard 或 Demo Shop 完成一筆小額真實付款。
將已支付收款地址中的餘額歸集到分賬合約。
將商戶份額轉至預設提款地址。
使用 Demo Shop 與伺服器整合，驗證訂單建立、查詢及通知流程。
支付檢測、Claim 與 Withdraw 是不同階段。進行小額真實驗證時，請按此順序逐步檢查。
在帳戶承載真實業務量之前，先確認一鍵設定建立的基礎設施設定無誤。
對照設定時儲存的 Account Info，核對分賬合約、網絡、提款地址、收款地址池及 API Key 記錄。
首次驗證時，請確認預期的小規模收款地址池已經建立，並歸屬於正確的商戶帳戶和鏈。
商戶發起 Withdraw 後，資金會進入預設的提款地址。之後更換用於操作帳戶的錢包，並不會自動改變這個提款目的地。
提款地址屬於生產級關鍵設定。首次端到端測試前要確認一次，正式上線前再確認一次。
建立一筆小額支付訂單，完成客戶付款，並確認 HashNut 能正確檢測到這筆支付。
測試金額保持小額即可。這裡要驗證的是完整路徑，而不是交易金額。
開啟支付資訊，將指定資產發送到訂單分配的收款地址，然後等待 HashNut 檢測並確認交易，直至訂單狀態正常推進。
0xA4...19C透過 Dashboard 和 Query Order 確認權威訂單狀態。不要把瀏覽器跳轉結果當作付款憑證。
將已獲授權的收款地址餘額歸集到分賬合約。Claim 由商戶主動發起。
確認已付款的收款地址中有預期的代幣餘額，並已完成歸集所需的代幣授權。
Claim 不會把商戶份額直接發送到最終提款地址，而是先將已授權餘額從收款地址歸集到分賬合約。下一步才是 Withdraw。
將分賬合約中商戶可提款的份額釋放到預設提款地址。
發起交易前，請再次核對預設提款地址。
確認目標錢包收到預期的商戶份額。到這裡，從客戶付款到商戶結算的核心資金路徑就已經完整驗證。
使用 API 憑證和 Demo Shop，確認訂單建立、訂單查詢及通知處理已經正確連通。
Demo Shop 是商戶設定與應用整合之間的驗證工具。用它確認 API Key 能夠跑通完整支付流程。
將 accessKeyId 和 secretKey 儲存在伺服器端設定中。 secretKey 絕不能暴露在前端程式碼中。
Create Order 調用成功並不代表整合已經完成。還要確認 Query Order 正常、通知簽名得到驗證、應用會向 HashNut 查詢權威狀態，並且履約操作具備冪等性。
只有在首個帳戶和整合流程都完成驗證後，再提高併發支付能力。
每個收款地址會臨時分配給一個未結束的支付訂單，因此收款地址池的容量決定了該商戶帳戶可以同時保持多少個未結束訂單。
當前公開指引建議先用 5 個收款地址完成驗證，確認流程無誤後再擴容。正式環境可根據支付頻率，將地址池擴展到 50、100、200 等便於管理的規模。
透過 MPC Client，在同一個分賬合約和商戶帳戶下建立更多收款地址。同時確保所選鏈上有足夠的原生代幣，用於地址管理操作所需的 Gas。
從已驗證的測試流程進入生產設定、監控、容量規劃及營運責任管理。
正式上線後，日常工作會從“設定”轉向“監控”：未結束訂單、支付異常、Claim、Withdraw、收款地址容量、原生代幣 Gas 及異常升級處理。
整合階段讓本地通知處理介面可從公開網絡訪問，同時明確區分伺服器通知與瀏覽器返回。
notifyUrl 是伺服器到伺服器的介面。當訂單進入文檔規定的可通知狀態時，HashNut 必須能夠透過公開網絡訪問該地址。
確認該路由正在監聽，並以安全方式記錄收到的請求。
使用你習慣的開發隧道或反向代理服務，生成一個臨時的公開網絡 HTTPS 地址。
例如：隧道域名加上你的通知路徑。
完成付款，並確認伺服器收到預期通知。
驗證通知後，再透過 Query Order 獲取權威的當前狀態。
進入正式環境時，將臨時隧道替換為穩定的生產 HTTPS 介面。保持 notifyUrl 並與以下內容區分 callbackUrl：notify 的方向是 HashNut → 伺服器，callback 的方向是客戶瀏覽器 → 前端。
瀏覽器返回只是客戶體驗的一部分，不能作為付款憑證。
先完整跑通一次支付，再把同樣的客戶流程和伺服器流程整合進自己的產品。
透過 Demo Shop 體驗客戶支付流程，同時驗證商戶帳戶及 API 行為。
開啟 demo.hashnut.io ↗透過一筆 58 美元的簡單購買流程，瞭解哪些環節屬於客戶體驗，哪些環節由 HashNut 支付系統處理。
客戶照常使用你的產品體驗，只有進入支付環節時才需要出現 HashNut。
使用當前正在驗證的商戶帳戶 / API Key。
確認金額、資產、網絡及收款地址均正確。
從客戶錢包發送指定資產。
觀察支付檢測及確認過程。不要根據 callbackUrl 執行履約。
確認商戶伺服器可以查詢 HashNut 訂單，並正確識別 SUCCESS / FINISH。
如果要完成完整帳戶驗證，再從商戶側執行 Claim 和 Withdraw。
客戶支付體驗可以使用商戶自己的品牌並嵌入產品，但伺服器仍負責建立訂單、驗證通知、查詢權威狀態，以及確保只履約一次。
完成帳戶及資金路徑驗證後，再將商戶伺服器接入 HashNut。
商戶伺服器負責業務訂單及 HashNut API 調用。客戶資金則直接從客戶錢包進入鏈上指定收款地址。
此時商戶帳戶及資金路徑應已完成驗證。開發者接收的是伺服器設定，而不是商戶錢包私鑰或 MPC 密鑰。
BSC0x91...2AFaccessKeyId
secretKey
notifyUrl
callbackUrl
使用設定階段生成的帳戶標識與 API 憑證，不要接收商戶錢包私鑰。
將 accessKeyId 與 secretKey 儲存在伺服器端密鑰存儲中。
使用 secretKey 對 UUID + timestamp + 請求體執行 HMAC-SHA256 計算，並將結果進行 Base64 編碼。
將商戶訂單與返回的 payOrderId 與 accessSign.
向客戶展示金額、資產、網絡及指定收款地址。
先驗證通知，再透過 Query Order 獲取權威的當前訂單狀態。
僅在確認狀態為 SUCCESS / FINISH 後履約，並確保操作具備冪等性。
go get github.com/nuttybounty/hashnut-sdk-go/v4callbackUrl 只是瀏覽器返回機制，不能作為付款憑證。支付結果應以已驗證的伺服器通知和權威 Query Order 結果為準。
將測試與正式環境嚴格分開，並確保憑證、帳戶上下文及 URL 與當前環境一致。
在進入正式環境並承載真實業務量之前，先在 Sandbox / 測試環境驗證訂單建立、支付狀態處理及完整資金路徑。
用於整合開發、小額驗證訂單及端到端測試。
僅在商戶帳戶、回調、收款地址容量及營運流程均完成驗證後使用。
使用當前 V4 帳戶或 SDK 版本提供的 Base URL 及環境參數。V3 介面地址不能用於 V4 整合。
API 請求成功還不夠。進入正式環境前，要完整驗證 Create Order → 客戶付款 → 通知 → Query Order → Claim → Withdraw，並確認收款地址容量和 Gas 的責任歸屬。
商戶級 API 請求必須在伺服器端簽名，並確保 secretKey 不進入前端程式碼或客戶端包。
| 憑證 | 用途 |
|---|---|
accessKeyId | 商戶級請求使用的公開標識。 |
secretKey | 商戶伺服器本地使用的 HMAC 密鑰。絕不要發送 secretKey 本身。 |
accessSign | 建立訂單時返回、與訂單綁定的憑證，用於文檔規定的訂單級操作。 |
sign = Base64(
HMAC-SHA256(secretKey, uuid + timestamp + requestBody)
)const crypto = require('node:crypto');
function signRequest(secretKey, uuid, timestamp, requestBody) {
const input = uuid + timestamp + requestBody;
return crypto
.createHmac('sha256', secretKey)
.update(input)
.digest('base64');
}本示例按照文檔中的簽名公式實現。請求 Header 名稱及介面結構應始終與當前 V4 API 參考保持一致。
bindIp 用於限制哪些伺服器 IP 可以使用該 API Key。 * 表示不限制 IP。整合階段可以臨時使用，但正式環境應盡可能限制為實際伺服器 IP。
建立與自身業務訂單對應的 HashNut 支付訂單，並將返回的標識與業務記錄一並持久化。
merchantOrderId = A1042payOrderId + accessSign| 欄位 | 說明 |
|---|---|
merchantOrderId | 你的訂單標識。在對應的商戶 / 鏈 / channel 範圍內必須保持唯一。 |
merchantChannel | 同一商戶上下文中的分組。文檔規定的預設值為： default. |
expireDuration | 訂單有效期，單位為秒。文檔預設值： 172800 （48 小時）；最大值： 259200 （72 小時）。 |
payOrderId | HashNut 建立訂單後返回的全局唯一支付訂單標識。 |
accessSign | 建立支付訂單時返回、與訂單綁定的憑證。 |
商城 payOrderId 與 accessSign 應在建立後立即與商戶訂單建立映射。訂單級操作以及通知延遲或重復時的恢復流程都會用到這些資訊。
始終將 Query Order 作為 HashNut 支付訂單當前狀態的權威查詢。
文檔規定的訂單級操作使用 payOrderId + accessSign ，無需為每次查詢重新計算商戶 HMAC。
最重要的狀態是 SUCCESS(3)。後續查詢也可能返回 FINISH(4)，這仍屬於已支付狀態。當權威查詢達到安全的已支付狀態後，只履約一次。
將 Confirm Payment 納入伺服器端訂單生命週期，並在履約前確認當前訂單狀態。
Confirm Payment 是 V4 API 中的訂單級操作，應將它視為支付訂單生命週期的一部分，而不是客戶履約的事實來源。
Create Order 會返回一個 accessSign 與訂單綁定。文檔規定的訂單級操作使用返回的訂單標識及訂單憑證，而不是暴露商戶 secretKey 。
執行任何確認相關操作後，Query Order 仍然是當前狀態的權威查詢。只有當查詢到的訂單進入 SUCCESS (3) 或 FINISH (4).
如果你的 V4 整合需要 Confirm Payment，請只在商戶伺服器端執行。不要把瀏覽器返回 URL、按鈕點擊，甚至交易哈希的存在本身當作履約憑證。
使用當前 V4 API 規範提供的介面路徑和請求欄位，不要把舊版 HashNut API 混入 V4 實現。
只有在訂單當前狀態允許時才能取消未付款訂單，並將最終狀態記錄到業務系統。
文檔規定的訂單生命週期允許訂單從 INIT (0) 到 CANCELED (-3) ，當商戶取消訂單時進入該狀態。 CANCELED 為終態。
請將你的 merchantOrderId、HashNut payOrderId 和返回的訂單憑證一起儲存。
不要因為結賬頁面還開著，就假設客戶尚未付款。
文檔規定的狀態轉換是 INIT → CANCELED。
在業務流程中將 CANCELED 視為終態。
如果客戶仍需付款，應建立新的支付訂單，不要嘗試恢復已經進入 CANCELED 終態的舊訂單。
使用當前 V4 API 規範提供的介面路徑、請求欄位及認證方式。
在結賬、通知處理、履約、對帳及營運環節中，統一解釋支付訂單狀態。
| 值 | 名稱 | 說明 |
|---|---|---|
0 | INIT | 訂單已建立，等待客戶付款。 |
1 | 已支付 | 已檢測到鏈上支付交易，正在等待確認。 |
2 | CONFIRMING | 交易正在等待達到所需區塊確認數。 |
3 | SUCCESS | 付款已確認，是首個可安全履約的狀態。 |
4 | FINISH | 支付後處理已經完成，仍屬於已支付狀態。 |
-1 | FAILED | 付款驗證失敗。 |
-2 | EXPIRED | 付款完成前訂單已過期。 |
-3 | CANCELED | 訂單已由商戶取消。 |
付款不足會為剩餘金額建立補款記錄。客戶可以多次補款，直至累計支付金額覆蓋訂單總額。
通過伺服器到伺服器的方式接收支付狀態變化，完成驗證後，再查詢權威訂單狀態並決定是否履約。
| notifyUrl | callbackUrl | |
|---|---|---|
| 方向 | HashNut → 商戶伺服器 | 客戶瀏覽器 → 商戶前端 |
| 可訪問性 | HashNut 必須能夠訪問 | 本地開發時可使用 localhost |
| 用途 | 支付狀態信號 | 將客戶返回商戶體驗 |
| 付款憑證 | 先驗證通知，再 Query Order | 絕不能作為付款憑證 |
在 notifyUrl 接收伺服器到伺服器的通知。
按照文檔中的簽名算法驗證 HashNut 簽名。
透過 HashNut / 商戶訂單標識定位對應業務訂單。
調用 Query Order 獲取權威的當前狀態。
僅在確認進入安全的已支付狀態後履約，並確保操作具備冪等性。
按照當前 V4 通知規範返回預期響應。
當前本地參考資料中記錄的可通知狀態包括 PAID, SUCCESS, FAILED，以及 EXPIRED。不要假設每一次狀態變化都會產生通知。
整合設計必須能夠處理通知延遲、重復事件、部分付款、訂單過期及臨時 API 故障，避免重復履約或訂單丟失。
| 情況 | 響應 |
|---|---|
| 重復通知 | 通知處理及履約都必須具備冪等性。 |
| 通知缺失 / 延遲 | 通過以下資訊 Query Order payOrderId + accessSign. |
| 瀏覽器先於通知返回 | 不要信任 callbackUrl，應查詢伺服器端訂單狀態。 |
| 付款不足 | 按照已設定策略處理補款記錄 / 剩餘金額。 |
| 訂單過期 | 建立新訂單，不要嘗試恢復已過期訂單。 |
| 臨時 API 故障 | 採用有上限的退避重試，並保持商戶訂單為待處理狀態，不要樂觀履約。 |
記錄 merchantOrderId、payOrderId、訂單狀態、通知接收時間、Query Order 結果及履約結果。不要記錄 secretKey 或商戶私鑰。
正式流量進入商戶帳戶前，將應用流程與資金路徑一起完整驗證。
商戶伺服器建立 HashNut 支付訂單，並儲存返回的標識。
客戶看到應付金額、資產、網絡及收款地址。
客戶完成鏈上交易。
商戶伺服器驗證通知消息。
伺服器確認狀態為 SUCCESS / FINISH。
商戶應用只交付一次商品或服務。
確認預期的已支付餘額。
將已授權餘額歸集到分賬合約。
將商戶份額轉至預設提款地址。
確認商戶訂單、鏈上付款、HashNut 訂單狀態及結算記錄相互一致。
只有應用流程和資金路徑都完成端到端驗證後才能上線，同時應驗證通知延遲或重復等情況下的恢復行為。
上線後持續監控訂單狀態、結算、容量、原生代幣 Gas 及異常，確保支付流程保持健康。
營運人員無需查看應用程式碼，只需持續回答四個關鍵問題，就能判斷線上支付是否執行正常。
支付目前處於什麼狀態？
INIT · PAID · CONFIRMING · SUCCESS · FINISH哪些資金可以歸集？
收款地址餘額 · Claim · Withdraw是否還有空閒收款地址？
未結束訂單 · 可用地址 · Gas哪些問題需要人工處理？
狀態不一致 · Gas · 容量 · 對帳| 領域 | 主要負責人 |
|---|---|
| 客戶 / 訂單狀態問題 | 營運 + 開發者 |
| Claim / Withdraw | 帳戶負責人 / 已授權營運人員 |
| 收款地址容量 | 營運 |
| 原生代幣 Gas | 營運 / 帳戶負責人 |
| API 認證 / 通知失敗 | 開發者 |
| keys.db / 商戶錢包備份 | 帳戶負責人 |
按狀態監控未結束訂單和近期已付款訂單，排查異常記錄。當商戶系統與 HashNut 狀態看起來不同步時，使用 Query Order 核實。
| 狀態 | 營運含義 |
|---|---|
| INIT | 訂單仍處於開啟狀態，等待客戶付款。 |
| PAID / CONFIRMING | 已檢測到付款，但尚未進入首個可安全履約狀態。 |
| SUCCESS | 付款已確認。通過權威查詢驗證後，應用可以履約一次。 |
| FINISH | 後續已支付狀態 / 支付後處理完成。 |
| FAILED / EXPIRED / CANCELED | 終態異常，需要商戶側處理，而不是執行履約。 |
將 merchantOrderId, payOrderId、當前狀態、已支付金額、時間戳及履約狀態都應能在商戶系統中查詢。
將 Claim 和 Withdraw 作為受控的商戶側操作，並逐筆核對資金變化是否符合收款地址及分賬合約的預期餘額。
將已授權的代幣餘額從收款地址歸集到分賬合約，由商戶主動發起。
將分賬合約中商戶可提款份額釋放到預設提款地址。平台份額單獨處理。
在當前客戶端流程支援的情況下，將 MPC 控制收款地址中剩餘的原生 Gas 代幣回收到商戶錢包。
小團隊中同一個人可以承擔多項職責，但生產流程仍應明確記錄誰有權發起結算操作，以及這些操作如何復核。
為未結束訂單保留充足的收款地址容量，同時為商戶側鏈上操作準備足夠的原生代幣 Gas。
收款地址可以跨訂單重用，但已經分配給活動訂單的地址不能同時用於另一筆活動訂單。應提前監控剩餘容量，避免需求耗盡地址池。
當前公開指引建議首次驗證使用 5 個地址，進入生產後按實際併發需求擴展到 50、100、200 等便於管理的規模。容量應依據同時未結束的訂單量，而不是歷史累計交易量。
| 鏈類型 | 商戶側 Gas |
|---|---|
| Ethereum / EVM | 相關部署及商戶側鏈上操作所需的網絡原生代幣。 |
| BSC | BNB |
| Polygon | POL / 當前網絡原生代幣 |
| TRON | TRX |
不要等到營運操作因 Gas 不足失敗後才充值。應把原生代幣餘額納入日常營運檢查。
盡早發現問題，區分支付狀態問題與結算問題，並帶上足夠上下文，將異常交給正確負責人處理。
| 現象 | 可能負責人 / 首要檢查項 |
|---|---|
| 客戶表示已付款，但訂單仍停留在 INIT | 先檢查鏈上交易、網絡 / 資產及收款地址，再由開發者 / HashNut 排查支付檢測。 |
| 訂單長時間停留在 PAID / CONFIRMING | 檢查鏈上確認數及網絡狀態。 |
| 通知缺失 | 開發者直接查詢訂單，並檢查 notifyUrl 是否可訪問及相關日誌。 |
| Claim 無法歸集代幣 | 檢查代幣授權及收款地址餘額。 |
| Withdraw 目標地址異常 | 停止操作，核對預設提款地址後再重試。 |
| 收款地址池容量不足 | 在未結束訂單耗盡地址池前，由營運人員提前擴容。 |
| MPC Client 無法建立新地址 | 檢查本地客戶端、keys.db、商戶錢包、網絡及 Gas。 |
排查時請提供商戶帳戶 / 鏈、merchantOrderId、payOrderId、當前訂單狀態、適用時的交易哈希、時間戳、嘗試執行的操作及完整報錯。絕不要發送 secretKey 或私鑰。
如果後端使用 Go，請採用 V4 Go SDK。
go get github.com/nuttybounty/hashnut-sdk-go/v4SDK 可以減少請求構建工作，但憑證安全、商戶訂單映射、通知驗證、權威訂單查詢、冪等履約及營運日誌仍由商戶伺服器負責。
V4 package 路徑必須與 V4 API 行為配套使用，不要把 V3 介面示例混入整合。
Java 後端請使用 V4 Java SDK，同時確保 API 憑證和付款驗證始終留在伺服器端。
使用當前 V4 Java SDK 版本提供的 package 坐標及程式碼示例。
瞭解一條鏈上一個商戶錢包所建立的各個組成部分，以及它們與支付、結算及 API 訪問之間的關係。
每條鏈都有獨立的商戶帳戶、分賬合約、API Key 和收款地址池。不要認為一條鏈上的設定會自動建立或控制另一條鏈。
備份維持商戶帳戶營運所需的商戶側資產，並將伺服器憑證與錢包密鑰分開儲存。
本地 MPC 材料與帳戶資訊用途不同。兩者都需要儲存，但錢包密鑰與應用憑證必須分開管理。
keys.db商戶側客戶端使用的本地 MPC 密鑰材料。
用於理解並整合商戶帳戶的設定及標識資訊。
0x91...2AF0x72...891AKID••••91••••••••••••| 資產 | 規則 |
|---|---|
keys.db | 請安全備份。MPC Client 本地工作區後續執行 MPC 控制的地址操作時仍需要它。 |
| 商戶錢包私鑰 | 與 keys.db 分開備份，不要交給開發者。 |
| 帳戶資訊 | 將導出的帳戶記錄與商戶營運文檔一並儲存。 |
accessKeyId | 儲存在伺服器設定中。 |
secretKey | 儲存在伺服器端密鑰存儲中，並在生成時立即安全記錄。 |
帳戶負責人負責保護商戶錢包材料及本地 MPC 資產；開發者負責保護應用 API 密鑰。小團隊中兩項職責可以由同一個人承擔，但不同密鑰仍應分開存儲和處理。
確保商戶支付行為和應用路由設定清晰、可修改，並符合生產安全要求。
| 設定 | 說明 |
|---|---|
notifyUrl | 用於接收 HashNut 支付狀態通知的公開網絡伺服器介面。 |
callbackUrl | 客戶完成支付體驗後返回瀏覽器的 URL。本地開發時可以使用 localhost。 |
bindIp | API Key 的伺服器 IP 允許清單。 * 表示不限制。 |
| 設定 | 文檔規定行為 |
|---|---|
merchantChannel | 文檔規定的預設 channel 值為 default. |
expireDuration | 預設 172800 秒（48 小時），最長 259200 秒（72 小時）。 |
| 收款地址容量 | 先以小規模完成驗證，帳戶和整合流程跑通後再擴容。 |
正式上線前，請確認生產 URL、IP 限制、提款地址、容量、Gas、通知處理及營運責任均已設定完成。任何設定變更都應留有記錄並經過測試，再承載有意義的支付量。
Buy one demo item with 0.01 USDT. After the payment is confirmed, take over the same order as the merchant and complete the settlement.
Connect your website or app through HashNut’s payment infrastructure.
告訴我們您的支付場景、渠道合作機會或戰略合作方向。
瞭解您使用 HashNut 服務時，我們如何收集、使用、共享及管理相關資訊。
適用於訪問及使用 HashNut 網站、應用、產品與服務的相關條款。
瞭解 HashNut 如何識別、評估及管理業務中的洗錢及恐怖主義融資風險。