Démarrage rapide

Si vous souhaitez simplement terminer la première intégration, cette page suffit : générez des en-têtes signés, créez un ordre de paiement, puis vérifiez le rappel et renvoyez une réponse 2xx.

Les exemples utilisent par défaut la création d’ordres de paiement. Les ordres de paiement utilisent la même signature, les mêmes en-têtes de demande et les mêmes en-têtes de rappel ; seuls le point de terminaison et la charge utile de l’entreprise changent.

API de productionhttps://api.uugate.com

Actifs pris en chargeTRC20-USDT · BEP20-USDT · BEP20-USDC · SPL-USDC

Configuration du callbackAPI Key + notifyUrl

✓Merchant UID est l'identité marchande unique attribuée par la plateforme. Il est utilisé dans les charges utiles x-merchant-uid et callback.

✓Préparez le API Key commençant par mch_ à partir des paramètres API du commerçant.

✓Préparez un notifyUrl accessible au public et appartenant au commerçant ; il est requis lors de la création de commandes.

Step 1

Générer des en-têtes signés

Les requêtes OpenAPI utilisent cinq en-têtes : x-api-key, x-merchant-uid, x-timestamp, x-nonce et x-signature.

Utilisez le même mch_ API Key comme clé x-api et comme secret de signature.
Le chemin de signature doit être uniquement le chemin API, par exemple /openapi/payin/orders, sans le domaine.
La charge utile de signature est Merchant UID, timestamp, nonce, méthode, chemin, canonique query et canonique body.

Node.js

import { createHmac, randomBytes } from 'node:crypto';

function required(name) {
  const value = process.env[name]?.trim();
  if (!value) throw new Error(name + ' is required');
  return value;
}
const uid = "880001", key = "mch_xxxxxxxxxxxxxxxxxxxx";
const timestamp = "1776193200000", nonce = "2f5c7b147c3748f0a8b3d9bb38aa91a4";
const method = 'POST', path = '/openapi/payin/orders';
const canonicalQuery = '', canonicalBody = "{\"amount\":\"100.00\",\"chainCode\":\"TRON\",\"merchantOrderNo\":\"M202604150001\",\"notifyUrl\":\"https://merchant.example.com/api/uugate/payin-notify\",\"tokenSymbol\":\"USDT\"}";
const payload = [uid, timestamp, nonce, method, path, canonicalQuery, canonicalBody].join('\n');
const signature = createHmac('sha256', key).update(payload, 'utf8').digest('hex');
console.log(signature);

Step 2

Créer une commande d’encaissement

Après avoir préparé les en-têtes signés, appelez l'ordre de paiement de création API. En cas de succès, utilisez orderNo, cashierUrl et paymentUri.

Point final : POST /openapi/payin/orders.
Utilisez le cashierUrl renvoyé lorsque l'interface du commerçant doit rediriger vers la caisse.
notifyUrl est obligatoire et est transmis avec la demande de commande. Aucune configuration de rappel backend distincte n’est nécessaire.

Node.js

import { createHmac, randomBytes } from 'node:crypto';

function required(name) {
  const value = process.env[name]?.trim();
  if (!value) throw new Error(name + ' is required');
  return value;
}
const uid = required("UUGATE_MERCHANT_UID"), key = required("UUGATE_API_KEY");
const timestamp = String(Date.now()), nonce = randomBytes(16).toString("hex");
const method = 'POST', path = '/openapi/payin/orders';
const canonicalQuery = '', canonicalBody = "{\"amount\":\"100.00\",\"chainCode\":\"TRON\",\"merchantOrderNo\":\"M202604150001\",\"notifyUrl\":\"https://merchant.example.com/api/uugate/payin-notify\",\"tokenSymbol\":\"USDT\"}";
const payload = [uid, timestamp, nonce, method, path, canonicalQuery, canonicalBody].join('\n');
const signature = createHmac('sha256', key).update(payload, 'utf8').digest('hex');
const base = (process.env.UUGATE_BASE_URL || 'https://api.uugate.com').replace(/\/+$/, '');
const response = await fetch(base + path, {
  method, redirect: 'error', signal: AbortSignal.timeout(30000),
  headers: { 'Content-Type': 'application/json', 'x-api-key': key, 'x-merchant-uid': uid,
    'x-timestamp': timestamp, 'x-nonce': nonce, 'x-signature': signature },
  ...(canonicalBody ? { body: canonicalBody } : {}),
});
const raw = await response.text();
if (!response.ok) throw new Error('HTTP ' + response.status + ': ' + (raw || 'empty response body'));
JSON.parse(raw);
console.log(raw);

Step 3

Recevoir et traiter le rappel

Lorsque la plateforme appelle votre notifyUrl, vérifiez-le d'abord avec apiKey, mettez à jour la commande commerciale après vérification, puis renvoyez 200 ou une autre réponse 2xx.

La vérification par rappel utilise apiKey, et non la signature x OpenAPI.
Pour le paiement, considérez status=completed comme l'état de réussite final.
Ce code vérifie uniquement les callbacks. Transmettez le corps brut à l’entrée standard et mappez les en-têtes vers UUGATE_CALLBACK_TIMESTAMP, UUGATE_CALLBACK_NONCE et UUGATE_CALLBACK_SIGNATURE. UUGATE_API_KEY doit être la clé utilisée pour créer la commande. Validez ensuite la commande et persistez-la de façon idempotente dans une transaction avant de renvoyer HTTP 2xx.

Node.js

import { createHmac, timingSafeEqual } from 'node:crypto';

function required(name) {
  const value = process.env[name]?.trim();
  if (!value) throw new Error(name + ' is required');
  return value;
}
const key = required('UUGATE_API_KEY');
const timestamp = required('UUGATE_CALLBACK_TIMESTAMP'), nonce = required('UUGATE_CALLBACK_NONCE');
const signature = required('UUGATE_CALLBACK_SIGNATURE');
const chunks = [];
for await (const chunk of process.stdin) chunks.push(chunk);
const rawBody = Buffer.concat(chunks);
const expected = createHmac('sha256', key).update(timestamp + '.' + nonce + '.', 'utf8').update(rawBody).digest();
const actual = Buffer.from(signature, 'hex');
if (!/^[a-fA-F0-9]{64}$/.test(signature) || actual.length !== expected.length || !timingSafeEqual(expected, actual))
  throw new Error('Invalid callback signature');
console.log('VERIFIED');

Le timestamp, le nonce et les identifiants fixes sont des valeurs de test de signature hors ligne. Pour une requête réelle, utilisez le timestamp actuel en millisecondes et un nouveau nonce aléatoire. Les chemins API n’ont pas de préfixe de version ; v1 désigne uniquement la signature des callbacks.

Exécution : enregistrez Java sous UUGateExample.java (UUGateCallback.java pour les callbacks), puis utilisez java nom du fichier ; PHP : php example.php ; Go : go run example.go ; Node.js : node example.mjs. Les vérificateurs de callback lisent le corps brut sur l’entrée standard.

Le paiement et le paiement partagent le même algorithme de signature et les mêmes en-têtes de rappel, vous n'avez donc pas besoin de deux flux d'authentification.

Une fois que cette page a du sens, continuez vers le bas pour les paramètres détaillés, les structures de réponse et les téléchargements SDK.