Criar pedido de cobrança

Cria uma ordem de pagamento compartilhada de valor fixo. A resposta inclui número do pedido, endereço de recebimento, checkout URL e pagamento status.

notifyUrl é obrigatório. Os retornos de chamada posteriores para este pedido são entregues diretamente a este URL.

POST/openapi/payin/orders

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 de token, por exemplo USDT.
merchantOrderNostringSimNúmero do pedido do comerciante. Máximo de 128 caracteres.
amountstringSimValor do pagamento, até 6 casas decimais.
notifyUrlstringSimRetorno de chamada específico do pedido URL. Recomenda-se um HTTPS URL público de propriedade do comerciante. Máximo de 500 caracteres; destinos privados, loopback ou inseguros são proibidos.

Exemplo de requisição

{
  "chainCode": "TRON",
  "tokenSymbol": "USDT",
  "merchantOrderNo": "M202604150001",
  "amount": "100.00",
  "notifyUrl": "https://merchant.example.com/api/uugate/payin-notify"
}

Campos da resposta

CampoTipoObrigatórioDescrição
orderNostringSimNúmero de pedido da plataforma.
merchantOrderNostring | nullSimNúmero do pedido do comerciante.
bindKeystring | nullSimBinding key for exclusive-wallet orders; empty for shared pay-in orders.
chainCodestring | nullSimRede do pedido.
tokenSymbolstring | nullSimMoeda do pedido.
txHashstring | nullSimHash da transação correspondente; null antes da detecção.
amountstring | nullSimValor do pedido.
paidAmountstring | nullSimValor pago. Vazio antes do pagamento.
addressstring | nullSimEndereço de recebimento real.
cashierUrlstring | nullSimURL completa do checkout com token aleatório. Preserve todo o fragmento #ct=.
paymentUristring | nullSimPagamento de carteira URI.
expireAtstring | nullSimPrazo de validade do pedido.
createdAtstring | nullSimTempo criado.
detectedAtstring | nullSimPayment detection time; empty before detection.
confirmedAtstring | nullSimOn-chain confirmation time; empty before confirmation.
completedAtstring | nullSimOrder completion time; empty before completion.
statusstringSimPedido status.

Exemplo de resposta

{
  "orderNo": "PI1776193200123ABCD1234",
  "merchantOrderNo": "M202604150001",
  "bindKey": null,
  "amount": "100.000000",
  "paidAmount": null,
  "address": "TXYZ3x9nJ5J4xP2gh6mQW7rT31jB8Y2pA9",
  "cashierUrl": "https://open.uugate.com/SK/PI1776193200123ABCD1234#ct=aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
  "paymentUri": "TRON:TXYZ3x9nJ5J4xP2gh6mQW7rT31jB8Y2pA9?token=USDT&amount=100.000000",
  "expireAt": "2026-04-18T06:30:00.000Z",
  "createdAt": "2026-04-18T06:00:00.000Z",
  "detectedAt": null,
  "confirmedAt": null,
  "completedAt": null,
  "status": "waiting_payment",
  "chainCode": "TRON",
  "tokenSymbol": "USDT",
  "txHash": null
}

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/orders';
const canonicalQuery = '', canonicalBody = "{\"amount\":\"100.00\",\"chainCode\":\"TRON\",\"merchantOrderNo\":\"M202604150001\",\"notifyUrl\":\"https://merchant.example.com/api/uugate/payin-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

  • Um pedido de pagamento compartilhado pode ser acionado 40105 quando o mesmo comerciante, rede, token e valor ainda estão reservados por outro pedido válido.
  • 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.