Exemple de demande et vérification de signature

Méthode de requête : les API utilisent principalement `GET` / `POST`; les requêtes JSON utilisent `application/json`.

Authentification : les requêtes OpenAPI sont vérifiées avec des en-têtes et des signatures HMAC-SHA256.

En-têtes

Champ	Type	Obligatoire	Description
x-api-key	string	Oui	Marchand API Key. Utilisez la valeur commençant par mch_ de la page des paramètres API du marchand.
x-merchant-uid	string	Oui	Merchant UID.
x-timestamp	string	Oui	Milliseconde à 13 chiffres timestamp. La dérive d'horloge autorisée par défaut est de 5 minutes.
x-nonce	string	Oui	Chaîne aléatoire unique pour chaque requête, jusqu'à 128 caractères. La réutilisation est rejetée.
x-signature	string	Oui	Signature hexadécimale générée avec HMAC-SHA256. La charge utile contient Merchant UID, timestamp, nonce, la méthode, le chemin, le query canonique et le body canonique.

Règles de signature

Les requêtes utilisent application/json. Pour les GET API sans body, la partie body dans la signature est une chaîne vide.
Le chemin de signature doit être le chemin brut API, par exemple /openapi/payin/orders, sans le domaine.
Les paramètres de requête sont triés par clé ; Les clés JSON body sont triées avant la sérialisation.
Les échecs de signature courants incluent des timestamp expirés, des valeurs nonce répétées, un ordre de champ incohérent ou des espaces supplémentaires.

Exemple de payload de signature

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

Exemple complet

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

Exemples de signature

Exemple de signature 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);

Champs d’erreur

Champ	Type	Obligatoire	Description
code	number	Oui	Code d'erreur métier.
message	string	Oui	Message d'erreur.
data	object \| null	Oui	Données d'erreur supplémentaires.
requestId	string \| null	Oui	ID de trace de demande du serveur.

Exemple d’erreur

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