Criar carteira exclusiva

Cria um endereço de recebimento exclusivo para um bindKey. Os depósitos futuros neste endereço pertencem permanentemente a esse bindKey.

Se notifyUrl for fornecido, futuros pedidos de recarga criados automaticamente para este endereço exclusivo retornarão a chamada para esse URL primeiro. Isso é útil quando cada site ou aplicativo recebe suas próprias notificações de recarga de membros.

POST/openapi/payin/exclusive-bindings

Cabeçalhos

CampoTipoObrigatórioDescrição
x-api-keystringSimComerciante API Key. Use o valor que começa com mch_ na página de configurações do comerciante API.
x-merchant-uidstringSimMerchant UID.
x-timestampstringSimMilissegundos de 13 dígitos timestamp. O desvio padrão permitido do relógio é de 5 minutos.
x-noncestringSimString aleatória exclusiva para cada solicitação, com até 128 caracteres. A reutilização é rejeitada.
x-signaturestringSimAssinatura hexadecimal gerada com HMAC-SHA256. A carga útil contém Merchant UID, timestamp, nonce, método, caminho, query canônico e body canônico.

Parâmetros

CampoTipoObrigatórioDescrição
chainCodestringSimCódigo da cadeia. Valores suportados: TRON / BSC / SOL.
tokenSymbolstringSimSímbolo simbólico.
bindKeystringSimChave de ligação exclusiva do lado do comerciante. Máximo de 128 caracteres.
labelstringNãoObservação vinculativa. Máximo de 100 caracteres.
notifyUrlstringNãoRetorno de chamada independente URL para este endereço exclusivo. Pedidos criados automaticamente a partir de depósitos futuros retornarão aqui primeiro. Máximo de 500 caracteres; destinos privados, loopback ou inseguros são proibidos.

Exemplo de requisição

{
  "chainCode": "TRON",
  "tokenSymbol": "USDT",
  "bindKey": "USER_90001",
  "label": "VIP User 90001",
  "notifyUrl": "https://merchant.example.com/api/uugate/member-topup-notify"
}

Campos da resposta

CampoTipoObrigatórioDescrição
bindingIdnumberSimID do registro de associação.
chainCodestringSimCódigo da cadeia.
tokenSymbolstringSimSímbolo simbólico.
bindKeystringSimChave de ligação.
addressIdnumberSimID do endereço.
addressstringSimEndereço de recebimento exclusivo.
addressTypestringSimSempre exclusivo.
notifyUrlstring | nullSimRetorno de chamada exclusivo URL usado por esta ligação.
statusstringSimVinculação status.

Exemplo de resposta

{
  "bindingId": 70031,
  "chainCode": "TRON",
  "tokenSymbol": "USDT",
  "bindKey": "USER_90001",
  "addressId": 31088,
  "address": "TQ3sCY8k9h7G9UsApY3JPt5VDpNKr2kJ1E",
  "addressType": "exclusive",
  "notifyUrl": "https://merchant.example.com/api/uugate/member-topup-notify",
  "status": "active"
}

Exemplos de código

Execução: salve Java como UUGateExample.java (UUGateCallback.java para callbacks) e use java nome do arquivo; PHP: php example.php; Go: go run example.go; Node.js: node example.mjs. A verificação de callbacks lê o corpo original da entrada padrão.

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/exclusive-bindings';
const canonicalQuery = '', canonicalBody = "{\"bindKey\":\"USER_90001\",\"chainCode\":\"TRON\",\"label\":\"VIP User 90001\",\"notifyUrl\":\"https://merchant.example.com/api/uugate/member-topup-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);

Notas

  • Se o mesmo bindKey for criado novamente, a plataforma retornará idempotentemente a ligação e o endereço existentes, o que funciona bem para um fluxo get-or-create.
  • Para recarga de associado, passe notifyUrl no momento da vinculação para depósitos de qualquer valor no endereço exclusivo de retorno diretamente para o site ou aplicativo correspondente.
  • As quatro linguagens usam as mesmas rotas, parâmetros e respostas. As credenciais vêm de UUGATE_MERCHANT_UID e UUGATE_API_KEY; UUGATE_BASE_URL usa https://api.uugate.com por padrão.
  • canonicalBody é JSON compacto com campos ordenados. Ao alterar parâmetros, ordene objetos recursivamente, preserve arrays e use UTF-8 sem escapes adicionais de barras ou Unicode. Valores monetários são strings; booleanos são true / false.
  • O sucesso retorna o objeto de negócio diretamente, sem envelope code / data. Verifique primeiro o status HTTP. Erros retornam code, message, data e requestId; recusas de segurança podem retornar apenas HTTP 401 / 403 com corpo vazio.
  • Após timeout ou HTTP 5xx, consulte o pedido antes de repetir a criação ou envio. Gere timestamp, nonce e assinatura novos em cada solicitação.