Request Example and Signature Verification

Request method: APIs mainly use `GET` / `POST`; JSON requests use `application/json`.

Authentication: OpenAPI requests are verified with request headers and HMAC-SHA256 signatures.

Request Headers

Field	Type	Required	Description
x-api-key	string	Yes	Merchant API Key. Use the value beginning with mch_ from the merchant API settings page.
x-merchant-uid	string	Yes	Merchant UID.
x-timestamp	string	Yes	13-digit millisecond timestamp. The default allowed clock drift is 5 minutes.
x-nonce	string	Yes	Unique random string for each request, up to 128 characters. Reuse is rejected.
x-signature	string	Yes	Hex signature generated with HMAC-SHA256. The payload contains Merchant UID, timestamp, nonce, method, path, canonical query, and canonical body.

Signature Rules

Requests use application/json. For GET APIs with no body, the body part in the signature is an empty string.
The signature path must be the raw API path, for example /openapi/payin/orders, without the domain.
Query parameters are sorted by key; JSON body keys are sorted before serialization.
Common signature failures include expired timestamps, repeated nonce values, inconsistent field order, or extra spaces.

Signature Payload Example

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"}

Full Request Example

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"
}

Signature Code Example

Node.js Signature Example

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);

Error Response Fields

Field	Type	Required	Description
code	number	Yes	Business error code.
message	string	Yes	Error message.
data	object \| null	Yes	Additional error data.
requestId	string \| null	Yes	Server request trace ID.

Error Response Example

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