Skip to main content

​
快速开始

​
对接流程

  1. 创建支付应用 → 获取 Payment ID 和 Secret Key
  2. 用户下单 → 调用发起支付接口
  3. 跳转支付 → 用户在 NodeLoc 登录并支付
  4. 接收回调 → 浏览器跳转到你的回调地址
  5. 查询状态（可选）→ 主动查询支付结果

​
创建支付应用

​
访问管理页面

https://www.nodeloc.com/payment/applications

​
填写应用信息

字段说明示例
应用名称你的网站/商店名称”我的在线商店”
网站地址你的网站主页https://example.com
回调地址接收支付通知的URLhttps://example.com/payment/callback
描述应用说明（可选）“在线商店支付集成”

​
保存密钥

创建成功后会显示：
  • Payment ID: pay_xxxxxxxxxxxxxxxxxx
  • Secret Key: xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx
Secret Key 只显示一次，请立即保存！

​
发起支付

​
API 接口

POST https://www.nodeloc.com/payment/pay/:payment_id/process

​
请求参数

参数类型必填说明
amountInteger是支付金额（积分）
descriptionString是交易描述
order_idString是你的订单号（唯一标识）
signatureString是HMAC-SHA256 签名

​
签名算法

  1. 准备参数: amount, description, order_id
  2. 按键名排序: 字母顺序排列参数
  3. 拼接字符串: 格式 key1=value1&key2=value2&key3=value3
  4. 计算密钥: token_hash = SHA256(your_token) // 你的 token 是 tk_xxx 格式
  5. 生成签名: signature = HMAC-SHA256(token_hash, param_string)
重要:
  • your_token 是申请时获得的 token（格式：tk_xxx...）
  • token_hash 是 token 的 SHA256 哈希（64位十六进制字符串）
  • 不要直接用 token 作为 HMAC 密钥！
签名参数示例： 
amount=100&description=购买VIP会员&order_id=order_20251008_001

​
响应数据

成功时返回： 
{
  "payment_url": "https://www.nodeloc.com/payment/pay/txn_xxx",
  "transaction_id": "txn_xxx",
  "status": "pending",
  "amount": 100
}

​
跳转支付

将用户重定向到响应中的 payment_url，用户会：
  1. 自动跳转到登录页（如未登录）
  2. 登录后返回支付页面
  3. 确认订单并完成支付
  4. 支付成功后跳转到你的回调地址

​
处理回调

​
回调方式

重要：这是浏览器 GET 跳转，不是服务器 POST 请求！
支付成功后，用户浏览器会跳转到你设置的回调地址，所有参数以查询字符串形式传递。

​
回调参数（URL 查询参数）

参数类型说明
transaction_idString交易ID
external_referenceString你的订单号（即 order_id）
amountInteger支付金额（积分）
platform_feeInteger平台手续费（积分）
merchant_pointsInteger商家实际收到的积分
statusString交易状态（completed）
paid_atDateTime支付时间（ISO 8601）
signatureString回调签名（用于验证）

​
回调 URL 示例

https://example.com/payment/callback?
  transaction_id=txn_xxx&
  external_reference=order_123&
  amount=100&
  platform_fee=5&
  merchant_points=95&
  status=completed&
  paid_at=2025-10-08T12:00:00Z&
  signature=abc123...

​
验证签名

必须验证签名，防止伪造请求！
验证步骤：
  1. 提取签名参数: 从 URL 中获取 signature
  2. 提取其他参数: 所有参数除了 signature 本身
  3. 按键名排序: 字母顺序排列
  4. 拼接字符串: 格式 key1=value1&key2=value2...
  5. 计算签名: HMAC-SHA256(secret_key, param_string)
  6. 比对签名: 计算出的签名与接收到的签名必须完全一致
签名参数示例： 
amount=100&external_reference=order_123&merchant_points=95&paid_at=2025-10-08T12:00:00Z&platform_fee=5&status=completed&transaction_id=txn_xxx

​
处理订单

验证签名通过后：
  • ✅ 检查幂等性: 确保订单未被重复处理
  • ✅ 验证金额: 确认 amount 与订单金额一致
  • ✅ 更新订单状态: 标记为已支付
  • ✅ 执行业务逻辑: 发货、开通服务等
  • ✅ 显示确认页面: 向用户展示支付成功信息

​
查询状态

如果回调失败或需要主动确认支付状态，可以使用查询接口。

​
API 接口

POST https://www.nodeloc.com/payment/query/:payment_id

​
请求参数

参数类型必填说明
transaction_idString是交易ID
signatureString是HMAC-SHA256 签名

​
签名算法

与发起支付相同：
  1. 参数：transaction_id
  2. 拼接：transaction_id=txn_xxx
  3. 签名：HMAC-SHA256(secret_key, param_string)

​
响应数据

{
  "transaction_id": "txn_xxx",
  "status": "completed",
  "amount": 100,
  "platform_fee": 5,
  "merchant_points": 95,
  "description": "购买VIP会员",
  "external_reference": "order_123",
  "created_at": "2025-10-08T12:00:00Z",
  "updated_at": "2025-10-08T12:05:00Z",
  "paid_at": "2025-10-08T12:05:00Z",
  "expires_at": "2025-10-08T12:30:00Z",
  "expired": false,
  "error_message": null
}

​
交易状态

状态说明
pending等待用户支付
processing支付处理中
completed支付成功
failed支付失败
cancelled已取消
refunded已退款

​
建议使用场景

  • 定时任务检查待支付订单状态
  • 用户主动查询订单状态
  • 回调失败后的补救措施

​
安全建议

​
1. 保护密钥

  • ❌ 不要硬编码在代码中
  • ✅ 使用环境变量或密钥管理服务

​
2. 使用 HTTPS

  • ✅ 生产环境必须使用 HTTPS
  • ✅ 回调 URL 必须是 HTTPS 地址

​
3. 验证签名

  • ✅ 所有回调请求必须验证签名
  • ✅ 签名不匹配时拒绝请求

​
4. 防止重复处理

  • ✅ 检查订单状态，防止重复处理
  • ✅ 使用数据库事务确保原子性

​
5. 验证金额

  • ✅ 验证回调金额与订单金额一致
  • ✅ 金额不匹配时记录日志并告警

​
6. 日志记录

  • ✅ 记录所有支付相关操作
  • ✅ 记录所有回调请求（包括签名验证失败的）

​
常见问题

检查以下几点：
  1. 参数是否按键名字母顺序排序
  2. 参数拼接格式是否为 key=value&key=value
  3. Secret Key 是否正确
  4. 验证时是否排除了 signature 参数本身
  5. 字符编码是否一致（UTF-8）
可能原因：
  1. 回调 URL 设置错误
  2. 用户关闭了浏览器窗口
  3. 网络问题导致跳转失败
解决方案：使用查询接口定期检查订单状态
开发环境测试：
  1. 使用 ngrok 等工具暴露本地服务器
  2. 在 NodeLoc 创建测试应用
  3. 设置回调 URL 为 ngrok 地址
  4. 创建小金额订单测试
目前不支持自动退款，需要联系管理员手动处理。
是的，默认 30 分钟未支付会自动过期。

​
API 参考

​
发起支付

  • URL: POST /payment/pay/:payment_id/process
  • 认证: 签名验证
  • 请求: amount, description, order_id, signature
  • 响应: payment_url, transaction_id, status, amount

​
查询状态

  • URL: POST /payment/query/:payment_id
  • 认证: 签名验证
  • 请求: transaction_id, signature
  • 响应: 完整交易信息（见上文）

​
支付回调

  • 方式: 浏览器 GET 跳转
  • URL: 你设置的 callback_url
  • 认证: 签名验证
  • 参数: transaction_id, external_reference, amount, platform_fee, merchant_points, status, paid_at, signature
祝对接顺利！ 🚀