示范商城
HashNut 提供完整可运行的示范商户应用，演示完整的支付对接流程。可以作为你自己实现的参考。
| 组件 | 语言 | 仓库 |
|---|---|---|
| Demo 后端 (Go) | Go + Gin | hashnut-demo-go |
| Demo 后端 (Java) | Java + Spring Boot | hashnut-demo |
| Demo 前端 | React + TypeScript | hashnut-demo-web |
两个后端实现相同的 API 接口，前端通用。
架构
浏览器 (localhost:5173) Demo 后端 (localhost:1800) HashNut API
| | |
| GET /api/products | |
|---------------------------------->| |
| GET /api/chains | |
|---------------------------------->| (从数据库读取) |
| | |
| POST /api/orders | |
| {productId, blockChain, tokenSymbol} | |
|---------------------------------->| SDK.createOrder() |
| |------------------------------->|
| | payOrderId + receiptAddress |
| payUrl (跳转到 HashNut 支付页) |<-------------------------------|
|<----------------------------------| |
| | |
| (用户在 HashNut 页面支付) | |
| | POST /api/notify (回调通知) |
| |<-------------------------------|
| | 更新订单状态 |
| | |
| 跳转到 /payment-result | |
| (前端显示支付成功) | |快速开始 (Go)
bash
# 1. 克隆
git clone https://github.com/nuttybounty/hashnut-demo-go.git
cd hashnut-demo-go
# 2. 建库
psql -U postgres -c "CREATE DATABASE demo_shop;"
# 编辑 migrate.sql，填入你的 API 密钥到 t_hashnut_api_key
psql -U postgres -d demo_shop -f migrate.sql
# 3. 按需编辑 etc/application.yaml
# 4. 启动
go run main.go快速开始 (Java)
bash
# 1. 克隆
git clone https://github.com/nuttybounty/hashnut-demo.git
cd hashnut-demo
# 2. 建库
psql -U postgres -c "CREATE DATABASE demo_shop;"
# 编辑 migrate.sql，填入你的 API 密钥到 t_hashnut_api_key
psql -U postgres -d demo_shop -f migrate.sql
# 3. 按需编辑 src/main/resources/application.yml
# 4. 启动（SDK 通过 JitPack 自动下载）
mvn spring-boot:run启动前端
两个后端提供相同的 API，前端通用：
bash
git clone https://github.com/nuttybounty/hashnut-demo-web.git
cd hashnut-demo-web
npm install
npm run dev打开浏览器访问 http://localhost:5173。
数据库配置
Demo 使用 PostgreSQL，包含以下表：
| 表 | 用途 |
|---|---|
t_coin_info | 支持的链和币种（前端显示用） |
t_hashnut_api_key | 每条链的 splitter 地址 + API 密钥 |
products | 商品（只有价格，不绑定链/币种） |
orders | 订单（记录用户选择的链+币种） |
运行前编辑 migrate.sql 配置支持的链：
sql
-- 前端显示哪些链和币种
INSERT INTO t_coin_info (block_chain, token_symbol, chain_label, coin_label, contract_address, decimals) VALUES
('ETH', 'usdt', 'Ethereum', 'USDT', '0xdAC17F958D2ee523a2206206994597C13D831ec7', 6),
('TRON', 'usdt', 'Tron', 'USDT', 'TR7NHqjeKQxGTCi8q8ZY4pL8otSzgjLj6t', 6);
-- 每条链的 API 密钥（每条链有自己的 splitter）
INSERT INTO t_hashnut_api_key (block_chain, splitter, access_key_id, secret_key) VALUES
('ETH', '0x你的ETH分账合约', '你的access-key-id', '你的secret-key'),
('TRON', 'T你的Tron分账合约', '你的access-key-id', '你的secret-key');本地开发 ngrok 配置
让 HashNut 后端能向你的本地机器发送支付通知：
bash
ngrok http 1800然后在 HashNut 商户后台配置 API Key：
| 字段 | 本地开发 | 正式生产 |
|---|---|---|
| notifyURL | https://xxxxx.ngrok-free.dev/api/notify | https://你的域名/api/notify |
| callbackURL | http://localhost:5173/payment-result | https://你的域名/payment-result |
TIP
notifyURL 是服务器到服务器的回调 — 必须公网可达（使用 ngrok）。
callbackURL 是浏览器跳转 — 本地开发用 localhost:5173，因为浏览器直接跳转到本地。
关键实现细节
多链支持
商品不绑定特定链。前端让用户选择支付链和币种，将 blockChain + tokenSymbol 传给后端。后端从数据库查找对应的 splitter 和 API 密钥。
Webhook 处理
/api/notify 端点接收 HashNut 的支付通知。你的处理逻辑需要：
- 解析 JSON（
payOrderId、state、payTxId） - 更新数据库中的订单状态
- 返回字符串
"success"（HTTP 200）确认收到
如果不返回 "success"，HashNut 会重试通知。
支付页面跳转
创建订单后，后端返回 payUrl 指向 HashNut 支付页面。前端跳转用户到该页面。支付完成后，用户被跳转回你的 callbackURL，带有 state 和 merchantOrderId 等查询参数。