Pay-in Callback

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 from the create pay-in order request body

Request Headers

Field	Type	Required	Description
content-type	application/json	Yes	Always application/json.
x-callback-timestamp	string	Yes	Callback timestamp in milliseconds.
x-callback-nonce	string	Yes	Callback nonce.
x-callback-signature	string	Yes	HMAC-SHA256(apiKey, timestamp + "." + nonce + "." + rawBody)。
x-callback-signature-algorithm	string	Yes	Always HMAC-SHA256.
x-callback-signature-version	string	Yes	Always v1.

Request Parameters

Field	Type	Required	Description
merchantUid	string	Yes	Merchant UID.
orderNo	string	Yes	Platform order number.
merchantOrderNo	string \| null	Yes	Merchant order number.
bindKey	string \| null	Yes	Binding key for member recharge. Usually empty for shared pay-in orders.
expectedAmount	string	Yes	Order amount.
paidAmount	string	Yes	Actual paid amount.
chainCode	string	Yes	Chain code.
tokenSymbol	string	Yes	Token symbol.
txHash	string	Yes	On-chain transaction hash.
fromAddress	string \| null	Yes	Sender address.
status	string	Yes	Final successful pay-in status; always completed.

Request Example

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

Response Fields

Field	Type	Required	Description
HTTP Status	200-299	Yes	Any 2xx response is treated as success.
Response Body	string \| json	No	The response body can be customized.

Response Example

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

{
  "ok": true
}

Code Examples

Node.js Callback Verification Example

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

Notes

Callback verification uses apiKey, not the OpenAPI x-signature request header.
After verification, match the merchant, order, asset, network and amount. Persist payment and business results transactionally and idempotently by platform order number before returning 2xx; repeated notifications must not duplicate credits or fulfillment.
For member recharge, use bindKey directly as the member identifier so you do not need an extra orderNo-to-member mapping table.