Inicio rápido

Si solo desea completar la primera integración, esta página es suficiente: genere encabezados firmados, cree una orden de pago, luego verifique la devolución de llamada y devuelva una respuesta 2xx.

Los ejemplos utilizan la creación de órdenes de pago de forma predeterminada. Las órdenes de pago utilizan la misma firma, encabezados de solicitud y encabezados de devolución de llamada; solo cambian el punto final y la carga útil empresarial.

API de producciónhttps://api.uugate.com

Activos compatiblesTRC20-USDT · BEP20-USDT · BEP20-USDC · SPL-USDC

Configuración de callbackAPI Key + notifyUrl

✓Prepare su Merchant UID.

✓Prepare el API Key comenzando con mch_ de la configuración del comerciante API.

✓Prepare un notifyUrl accesible públicamente propiedad del comerciante; es necesario al crear pedidos.

Step 1

Generar encabezados firmados

Las solicitudes OpenAPI utilizan cinco encabezados: x-api-key, x-merchant-uid, x-timestamp, x-nonce y x-signature.

Utilice el mismo mch_ API Key como x-api-key y como secreto de firma.
La ruta de la firma debe ser únicamente la ruta API, por ejemplo /openapi/payin/orders, sin el dominio.
La carga útil de la firma es Merchant UID, timestamp, nonce, método, ruta, canónico query y canónico body.

Ejemplo de firma mínima 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

Crear pedido de cobro

Después de preparar los encabezados firmados, llame a la orden de pago de creación API. En caso de éxito, utilice orderNo, cashierUrl y paymentUri.

Punto final: POST /openapi/payin/orders.
Utilice el cashierUrl devuelto cuando la interfaz del comerciante necesite redirigir al pago.
notifyUrl es obligatorio y se pasa con la solicitud de pedido. No se necesita una configuración de devolución de llamada de backend por separado.
Para el pago, cambie la ruta a /openapi/payout/orders y envíe los parámetros de pago.

Ejemplo de creación de orden en 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

Recibir y procesar devolución de llamada

Cuando la plataforma llame a su notifyUrl, verifíquelo primero con apiKey, actualice la orden comercial después de la verificación y luego devuelva 200 u otra respuesta 2xx.

La verificación de devolución de llamada utiliza apiKey, no la firma x OpenAPI.
Para el pago, trate status=completed como el estado de éxito final.
Para el pago, concéntrese en status=confirmed y status=failed.

Ejemplo de controlador de devolución de llamada mínimo

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') {
    // Marcar el pedido del comerciante como exitoso
  }

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

El pago y el pago comparten el mismo algoritmo de firma y encabezados de devolución de llamada, por lo que no necesita dos flujos de autenticación.

Una vez que esta página tenga sentido, continúe hacia abajo para obtener parámetros detallados, estructuras de respuesta y descargas SDK.