Exemplo de solicitação e verificação de assinatura

Método da requisição: as APIs usam principalmente `GET` / `POST`; requisições JSON usam `application/json`.

Autenticação: as solicitações OpenAPI são verificadas com cabeçalhos e assinaturas HMAC-SHA256.

Cabeçalhos

Campo	Tipo	Obrigatório	Descrição
x-api-key	string	Sim	Comerciante API Key. Use o valor que começa com mch_ na página de configurações do comerciante API.
x-merchant-uid	string	Sim	Merchant UID.
x-timestamp	string	Sim	Milissegundos de 13 dígitos timestamp. O desvio padrão permitido do relógio é de 5 minutos.
x-nonce	string	Sim	String aleatória exclusiva para cada solicitação, com até 128 caracteres. A reutilização é rejeitada.
x-signature	string	Sim	Assinatura hexadecimal gerada com HMAC-SHA256. A carga útil contém Merchant UID, timestamp, nonce, método, caminho, query canônico e body canônico.

Regras de assinatura

As solicitações usam application/json. Para GET APIs sem body, a parte body na assinatura é uma string vazia.
O caminho da assinatura deve ser o caminho API bruto, por exemplo /openapi/payin/orders, sem o domínio.
Os parâmetros de consulta são classificados por chave; As chaves JSON body são classificadas antes da serialização.
Falhas comuns de assinatura incluem timestamps expirados, valores nonce repetidos, ordem de campo inconsistente ou espaços extras.

Exemplo do payload de assinatura

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

Exemplo completo

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

Exemplos de assinatura

Node.js Exemplo de assinatura

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);

Campos de erro

Campo	Tipo	Obrigatório	Descrição
code	number	Sim	Código de erro comercial.
message	string	Sim	Mensagem de erro.
data	object \| null	Sim	Dados de erro adicionais.
requestId	string \| null	Sim	ID de rastreamento de solicitação do servidor.

Exemplo de erro

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