跳到主要内容

您的第一笔支付

一个完整的逐步教程，用于创建和处理您的第一笔 HashNut 支付。

概述​

在本教程中，您将：

  1. 设置您的开发环境
  2. 创建支付订单
  3. 处理支付
  4. 处理 Webhook 通知

时间: ~15 分钟
难度: 初级

前置要求​

  • ✅ 安装 已完成
  • ✅ 从 HashNut 控制台获取的 API 凭证
  • ✅ 带有测试代币的测试钱包
  • ✅ 开发环境已设置

步骤 1: 初始化客户端​

import { HashnutClient } from '@hashnut/sdk';

const client = new HashnutClient({
  baseUrl: 'https://testnet.hashnut.io',
  accessKeyId: process.env.HASHNUT_ACCESS_KEY_ID!,
  apiKey: process.env.HASHNUT_API_KEY!,
});

步骤 2: 创建支付订单​

// 创建订单
const order = await client.orders.create({
  merchantOrderId: `order-${Date.now()}`,
  chainCode: 'erc20',
  coinCode: 'usdt',
  amount: 0.01,
  callBackUrl: 'https://your-site.com/api/webhook',
  frontendCallbackUrl: 'https://your-site.com/payment/success',
});

console.log('Order created:', order.payOrderId);
console.log('Payment URL:', order.paymentUrl);

步骤 3: 重定向客户到支付页面​

// 在您的前端
window.location.href = order.paymentUrl;

或在 React 组件中:

<button onClick={() => window.open(order.paymentUrl, '_blank')}>
  Pay Now
</button>

步骤 4: 客户完成支付​

客户将：

  1. 看到带有订单详情的支付页面
  2. 连接他们的钱包
  3. 批准支付交易
  4. 等待区块链确认

步骤 5: 处理 Webhook 通知​

// Express.js webhook 端点
import express from 'express';
const app = express();

app.post('/api/webhook', express.raw({ type: 'application/json' }), async (req, res) => {
  try {
    // 验证 webhook 签名
    const isValid = client.webhooks.verify(req);
    if (!isValid) {
      return res.status(401).send('Invalid signature');
    }
    
    // 解析 webhook 数据
    const data = JSON.parse(req.body.toString());
    const { payOrderId, merchantOrderId, state } = data;
    
    // 查询订单状态以获取最新详情
    const order = await client.orders.query({
      payOrderId,
      merchantOrderId,
      accessSign: data.accessSign,
    });
    
    // 处理支付成功
    if (order.state === 4) {
      console.log('Payment successful!');
      // 更新您的数据库
      await updateOrderStatus(merchantOrderId, 'paid');
      // 履行订单
      await fulfillOrder(merchantOrderId);
    }
    
    res.send('success');
  } catch (error) {
    console.error('Webhook error:', error);
    res.status(500).send('failed');
  }
});

步骤 6: 测试完整流程​

本地测试设置​

  1. 使用 ngrok 进行本地 webhook 测试:
# 安装 ngrok
npm install -g ngrok

# 暴露本地服务器
ngrok http 3000

# 使用 HTTPS URL 作为您的 webhook URL
# https://abc123.ngrok.io/api/webhook
  1. 创建测试订单:
const order = await client.orders.create({
  merchantOrderId: 'test-order-1',
  chainCode: 'erc20',
  coinCode: 'usdt',
  amount: 0.01,
  callBackUrl: 'https://your-ngrok-url.ngrok.io/api/webhook',
  frontendCallbackUrl: 'http://localhost:3000/payment/success',
});

  1. 完成支付:

    • 打开支付 URL
    • 连接钱包
    • 使用测试代币完成支付

  2. 验证 webhook:

    • 检查您的服务器日志
    • 验证订单状态已更新
    • 确认支付已处理

完整示例​

这是一个完整的工作示例:

import express from 'express';
import { HashnutClient } from '@hashnut/sdk';

const app = express();
app.use(express.json());

const client = new HashnutClient({
  baseUrl: 'https://testnet.hashnut.io',
  accessKeyId: process.env.HASHNUT_ACCESS_KEY_ID!,
  apiKey: process.env.HASHNUT_API_KEY!,
});

// 创建订单端点
app.post('/api/create-order', async (req, res) => {
  try {
    const order = await client.orders.create({
      merchantOrderId: `order-${Date.now()}`,
      chainCode: 'erc20',
      coinCode: 'usdt',
      amount: 0.01,
      callBackUrl: `${process.env.WEBHOOK_URL}/api/webhook`,
      frontendCallbackUrl: `${process.env.FRONTEND_URL}/payment/success`,
    });
    
    res.json({ paymentUrl: order.paymentUrl });
  } catch (error) {
    res.status(500).json({ error: error.message });
  }
});

// Webhook 端点
app.post('/api/webhook', express.raw({ type: 'application/json' }), async (req, res) => {
  try {
    if (!client.webhooks.verify(req)) {
      return res.status(401).send('Invalid signature');
    }
    
    const data = JSON.parse(req.body.toString());
    const order = await client.orders.query({
      payOrderId: data.payOrderId,
      merchantOrderId: data.merchantOrderId,
      accessSign: data.accessSign,
    });
    
    if (order.state === 4) {
      // 支付成功 - 更新您的数据库
      console.log('Payment successful:', order.payOrderId);
    }
    
    res.send('success');
  } catch (error) {
    console.error('Webhook error:', error);
    res.status(500).send('failed');
  }
});

app.listen(3000, () => {
  console.log('Server running on http://localhost:3000');
});

故障排除​

常见问题​

问题: "Invalid signature"

  • ✅ 检查 apiKey 是否正确
  • ✅ 验证请求体是否正确字符串化
  • ✅ 确保所有必需的标头都存在

问题: "Order not found"

  • ✅ 验证 payOrderId 和 merchantOrderId 是否正确
  • ✅ 检查您是否使用正确的环境 (测试网 vs 生产环境)

问题: 未收到 Webhook

  • ✅ 检查 webhook URL 是否可访问 (使用 ngrok 进行本地测试)
  • ✅ 验证 webhook URL 使用 HTTPS
  • ✅ 检查服务器日志中的错误

下一步​

恭喜！ 🎉 您已创建了您的第一笔 HashNut 支付。探索 完整文档 以解锁更多功能！