请求示例和验签说明

请求方式：接口以 `GET` / `POST` 为主，请求体统一使用 `application/json`。

鉴权方式：开放接口通过请求头 + HMAC-SHA256 签名完成认证。

请求头

字段名称	字段类型	是否必填	说明
x-api-key	string	是	商户 API Key，使用商户后台 API 接入页面中的 mch_ 开头字符串。
x-merchant-uid	string	是	商户 UID。
x-timestamp	string	是	13 位毫秒时间戳，默认允许和服务器时间相差 5 分钟。
x-nonce	string	是	每次请求唯一的随机字符串，最长 128 位，重复使用会被拒绝。
x-signature	string	是	使用 HMAC-SHA256 生成的十六进制签名，签名原文由 Merchant UID、时间戳、nonce、请求方法、路径、规范化 query 和规范化 body 组成。

签名规则

请求体统一为 application/json；GET 接口没有 body 时，参与签名的 body 为空字符串。
签名路径必须是纯接口路径，例如 /openapi/payin/orders，不要带域名。
query 会按 key 升序处理；body 会按 JSON key 升序后再序列化。
签名失败常见原因是时间戳过期、nonce 重复、字段顺序不一致或多余空格。

签名原文示例

880001
1776193200000
2f5c7b147c3748f0a8b3d9bb38aa91a4
POST
/openapi/payin/orders

{"amount":"100.00","chainCode":"TRON","merchantOrderNo":"M202604150001","notifyUrl":"https://merchant.example.com/api/uugate/payin-notify","tokenSymbol":"USDT"}

完整请求示例

POST /openapi/payin/orders HTTP/1.1
Host: api.uugate.com
Content-Type: application/json
x-api-key: mch_xxxxxxxxxxxxxxxxxxxx
x-merchant-uid: 880001
x-timestamp: 1776193200000
x-nonce: 2f5c7b147c3748f0a8b3d9bb38aa91a4
x-signature: 6d7e96fdbf3ec37c1ec515540f46c6c19b08754973c43293e54644c2da910838

{
  "chainCode": "TRON",
  "tokenSymbol": "USDT",
  "merchantOrderNo": "M202604150001",
  "amount": "100.00",
  "notifyUrl": "https://merchant.example.com/api/uugate/payin-notify"
}

签名代码示例

Node.js 签名示例

import crypto from 'node:crypto';

const merchantUid = '880001';
const apiKey = 'mch_xxxxxxxxxxxxxxxxxxxx';
const timestamp = '1776193200000';
const nonce = '2f5c7b147c3748f0a8b3d9bb38aa91a4';
const method = 'POST';
const path = '/openapi/payin/orders';
const canonicalQuery = '';
const canonicalBody = JSON.stringify({
  amount: '100.00',
  chainCode: 'TRON',
  merchantOrderNo: 'M202604150001',
  notifyUrl: 'https://merchant.example.com/api/uugate/payin-notify',
  tokenSymbol: 'USDT',
});

const payload = [
  merchantUid,
  timestamp,
  nonce,
  method,
  path,
  canonicalQuery,
  canonicalBody,
].join('\n');

const signature = crypto.createHmac('sha256', apiKey).update(payload).digest('hex');
console.log(signature);

失败返回结构

字段名称	字段类型	是否必填	说明
code	number	是	业务错误码。
message	string	是	错误描述。
data	object \| null	是	错误附加数据。
requestId	string \| null	是	服务端请求追踪 ID。

失败返回示例

{
  "code": 20011,
  "message": "Invalid API signature",
  "data": null,
  "requestId": "9e0cf688-11fd-4cd2-83aa-61df77123456"
}