Callback de recebimento

The merchant server is called only after a pay-in completes successfully; the callback status is always completed.

Only final payment results are sent. Any HTTP 2xx response stops delivery immediately. After the first failure, the platform retries in 1 minute; after another failure, it makes a final retry in 5 minutes, for up to 3 attempts total. Callback business times use Beijing time in YYYY/MM/DD HH:mm:ss format.

POSTnotifyUrl da solicitação de criação de ordem de pagamento body

Cabeçalhos

Campo	Tipo	Obrigatório	Descrição
content-type	application/json	Sim	Sempre aplicação/json.
x-callback-timestamp	string	Sim	Retorno de chamada timestamp em milissegundos.
x-callback-nonce	string	Sim	Retorno de chamada nonce.
x-callback-signature	string	Sim	HMAC-SHA256(apiKey, timestamp + "." + nonce + "." + rawBody)。
x-callback-signature-algorithm	string	Sim	Sempre HMAC-SHA256.
x-callback-signature-version	string	Sim	Sempre v1.

Parâmetros

Campo	Tipo	Obrigatório	Descrição
merchantUid	string	Sim	Merchant UID.
orderNo	string	Sim	Número de pedido da plataforma.
merchantOrderNo	string \| null	Sim	Número do pedido do comerciante.
bindKey	string \| null	Sim	Chave vinculativa para recarga de associado. Geralmente vazio para ordens de pagamento compartilhadas.
expectedAmount	string	Sim	Valor do pedido.
paidAmount	string	Sim	Valor real pago.
chainCode	string	Sim	Código da cadeia.
tokenSymbol	string	Sim	Símbolo simbólico.
txHash	string	Sim	Hash de transação na cadeia.
fromAddress	string \| null	Sim	Endereço do remetente.
status	string	Sim	Final successful pay-in status; always completed.

Exemplo de requisição

{
  "merchantUid": "880001",
  "orderNo": "PI1776193200123ABCD1234",
  "merchantOrderNo": "M202604150001",
  "bindKey": "USER_90001",
  "expectedAmount": "100.000000",
  "paidAmount": "100.000000",
  "chainCode": "TRON",
  "tokenSymbol": "USDT",
  "txHash": "f7f17891f52c35d0c93170f0d12bb347ac16ab34853b4bc8dcf7fd0a8c9aa321",
  "fromAddress": "TS7b7iD8G2PaPqK1TqSmLJ9nrrYH4oKX1S",
  "status": "completed"
}

Campos da resposta

Campo	Tipo	Obrigatório	Descrição
HTTP Status	200-299	Sim	Qualquer resposta 2xx é tratada como sucesso.
Response Body	string \| json	Não	A resposta body pode ser customizada.

Exemplo de resposta

HTTP/1.1 200 OK
Content-Type: application/json

{
  "ok": true
}

Exemplos de código

Node.js Exemplo de verificação de retorno de chamada

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

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

Notas

A verificação de retorno de chamada usa apiKey, não o cabeçalho de solicitação de assinatura x OpenAPI.
Após verificar, confira comerciante, pedido, ativo, rede e valor. Salve pagamento e resultado em transação idempotente por pedido da plataforma antes de responder 2xx; duplicatas não podem repetir créditos ou entregas.
Para recarga de membro, use bindKey diretamente como identificador de membro para que você não precise de uma tabela extra de mapeamento de orderNo para membro.