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

✓Préparez votre Merchant UID.

✓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.

Exemple de signature minimale Node.js

import crypto from 'node:crypto';

const merchantUid = '880001';
const apiKey = 'mch_xxxxxxxxxxxxxxxxxxxx';
const timestamp = String(Date.now());
const nonce = crypto.randomBytes(16).toString('hex');
const method = 'POST';
const path = '/openapi/payin/orders';
const canonicalQuery = '';
const canonicalBody = '{"amount":"100.00","chainCode":"TRON","merchantOrderNo":"M202604170001","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');

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.
Pour le paiement, modifiez le chemin vers /openapi/payout/orders et soumettez les paramètres de paiement.

Exemple de création de commande Node.js

import { UUGateClient } from 'uugate-openapi-sdk';

const client = new UUGateClient({
  baseUrl: 'https://api.uugate.com',
  merchantUid: '880001',
  apiKey: 'mch_xxxxxxxxxxxxxxxxxxxx',
});

const order = await client.createPayinOrder({
  chainCode: 'TRON',
  tokenSymbol: 'USDT',
  merchantOrderNo: 'M202604170001',
  amount: '100.00',
  notifyUrl: 'https://merchant.example.com/api/uugate/payin-notify',
});

console.log(order.orderNo, order.cashierUrl);

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.
Pour le paiement, concentrez-vous sur status=confirmed et status=failed.

Exemple de gestionnaire de rappel minimal

import express from 'express';
import { verifyCallbackSignature } from 'uugate-openapi-sdk';

const app = express();
app.use(express.json({
  verify: (req, _res, buffer) => {
    req.rawBody = buffer.toString('utf8');
  },
}));

app.post('/merchant/callback', (req, res) => {
  const valid = verifyCallbackSignature({
    apiKey: process.env.UUGATE_API_KEY,
    timestamp: req.header('x-callback-timestamp'),
    nonce: req.header('x-callback-nonce'),
    signature: req.header('x-callback-signature'),
    rawBody: req.rawBody || '',
  });

  if (!valid) {
    return res.status(401).json({ ok: false });
  }

  if (req.body.status === 'completed') {
    // Marquer la commande du marchand comme réussie
  }

  return res.status(200).json({ ok: true });
});

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.