Início rápido

Se você deseja apenas concluir a primeira integração, esta página é suficiente: gere cabeçalhos assinados, crie uma ordem de pagamento, verifique o retorno de chamada e retorne uma resposta 2xx.

Os exemplos usam a criação de ordem de pagamento por padrão. Os pedidos de pagamento usam a mesma assinatura, cabeçalhos de solicitação e cabeçalhos de retorno de chamada; apenas o endpoint e a carga útil do negócio mudam.

API de produçãohttps://api.uugate.com

Ativos compatíveisTRC20-USDT · BEP20-USDT · BEP20-USDC · SPL-USDC

Configuração de callbackAPI Key + notifyUrl

✓Prepare seu Merchant UID.

✓Prepare o API Key começando com mch_ nas configurações do comerciante API.

✓Prepare um notifyUrl publicamente acessível de propriedade do comerciante; é necessário ao criar pedidos.

Step 1

Gerar cabeçalhos assinados

As solicitações OpenAPI usam cinco cabeçalhos: x-api-key, x-merchant-uid, x-timestamp, x-nonce e x-signature.

Use o mesmo mch_ API Key como x-api-key e o segredo de assinatura.
O caminho da assinatura deve ser apenas o caminho API, por exemplo /openapi/payin/orders, sem o domínio.
A carga útil da assinatura é Merchant UID, timestamp, nonce, método, caminho, query canônico e body canônico.

Exemplo mínimo de assinatura 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

Criar pedido de cobrança

Depois de preparar os cabeçalhos assinados, chame a criação da ordem de pagamento API. Em caso de sucesso, use orderNo, cashierUrl e paymentUri.

Ponto final: POST /openapi/payin/orders.
Use o cashierUrl retornado quando o front-end do comerciante precisar redirecionar para a finalização da compra.
notifyUrl é obrigatório e passado com a solicitação de pedido. Nenhuma configuração separada de retorno de chamada de back-end é necessária.
Para pagamento, altere o caminho para /openapi/payout/orders e envie os parâmetros de pagamento.

Exemplo de criação de pedido em 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

Receber e processar retorno de chamada

Quando a plataforma chamar seu notifyUrl, verifique-o primeiro com apiKey, atualize a ordem comercial após a verificação e, em seguida, retorne 200 ou outra resposta 2xx.

A verificação de retorno de chamada usa apiKey, não a assinatura x OpenAPI.
Para pagamento, trate status=completed como o estado final de sucesso.
Para pagamento, concentre-se em status=confirmed e status=failed.

Exemplo de manipulador de retorno de chamada 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') {
    //Marca o pedido do comerciante como bem-sucedido
  }

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

O pagamento e o pagamento compartilham o mesmo algoritmo de assinatura e cabeçalhos de retorno de chamada, portanto, você não precisa de dois fluxos de autenticação.

Quando esta página fizer sentido, continue para parâmetros detalhados, estruturas de resposta e downloads de SDK.