Solicitar ejemplo y verificación de firma

Método de solicitud: las API usan principalmente `GET` / `POST`; las solicitudes JSON usan `application/json`.

Autenticación: las solicitudes OpenAPI se verifican con encabezados y firmas HMAC-SHA256.

Encabezados

Campo	Tipo	Obligatorio	Descripción
x-api-key	string	Sí	Comerciante API Key. Utilice el valor que comienza con mch_ de la página de configuración del comerciante API.
x-merchant-uid	string	Sí	Merchant UID.
x-timestamp	string	Sí	Milisegundo de 13 dígitos timestamp. La desviación del reloj permitida por defecto es de 5 minutos.
x-nonce	string	Sí	Cadena aleatoria única para cada solicitud, hasta 128 caracteres. Se rechaza la reutilización.
x-signature	string	Sí	Firma hexadecimal generada con HMAC-SHA256. La carga útil contiene Merchant UID, timestamp, nonce, método, ruta, query canónico y body canónico.

Reglas de firma

Las solicitudes utilizan application/json. Para GET APIs sin body, la parte body en la firma es una cadena vacía.
La ruta de la firma debe ser la ruta sin formato API, por ejemplo /openapi/payin/orders, sin el dominio.
Los parámetros de consulta están ordenados por clave; Las claves JSON body se ordenan antes de la serialización.
Los errores de firma comunes incluyen timestamp caducados, valores nonce repetidos, orden de campos inconsistente o espacios adicionales.

Ejemplo de payload de firma

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

Ejemplo completo

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

Ejemplos de firma

Node.js Ejemplo de firma

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

Campos de error

Campo	Tipo	Obligatorio	Descripción
code	number	Sí	Código de error empresarial.
message	string	Sí	Mensaje de error.
data	object \| null	Sí	Datos de error adicionales.
requestId	string \| null	Sí	ID de seguimiento de solicitud del servidor.

Ejemplo de error

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