7.4.3 Obtain the user’s on-chain address

#Brief description: Get the user's on-chain address (create it if it does not exist).

• Request method: POST
• Request interface: https://gateway-domain/wallet-trade-merchant/merchant/user/get-address
• Request media type (JSON data format)Content-Type: application/json

Query parameters

Parameter name	Type	Required	Parameter meaning	Parameter description
merchantId	int64	Yes	Merchant ID
userId	string	Yes	User ID	Merchant local user unique ID
network	string	Yes	Mainnet	Supports TRON, BSC, POLYGON, ETHEREUM (available through document 7.4.2)
key	string	Yes	Merchant key	Platform assigned merchant key
sign	string	Yes	Signature reference (how to sign)	See how to sign rules for details

Request json sample

{
  "merchantId": "302992856974",
  "userId": "77",
  "network": "TRON",
  "key": "9yUreYgTRtit39Dy",
  "sign": "3876e3b40ce4938c3123f07cd5aecb8c"
}

Response json example

{
  "code": 0,
  "data": {
    "address": "TMWFqTEZMDRxNzyfudFBw4rn7QFvMt4kSN",
    "merchantId": 308116064181,
    "network": {
      "avgBlockSecond": 3,
      "coinTotal": 2,
      "collectionNetworkConfirm": 3,
      "displayName": "Tron",
      "estimatedMinute": 1,
      "isDefault": null,
      "level": null,
      "logo": "https://dx-public-download.s3.ap-southeast-1.amazonaws.com/blockchain-logo/tron.png",
      "masterCoin": "TRX",
      "name": "TRON",
      "networkType": "TRON",
      "queryBaseUrl": "https://nile.tronscan.org/",
      "withdrawalNetworkConfirm": 3
    },
    "userId": "33"
  },
  "success": true,
  "message": null
}

Response data parameter description

Parameter name	Type	Parameter meaning	Remarks
merchantId	int64	Merchant ID
userId	string	User ID	Merchant’s local user unique ID
address	string	Chain address	User's chain address
network	object	Chain main network information
└ name	string	Mainnet name
└ queryBaseUrl	string	On-chain query URL
└ collectionNetworkConfirm	int64	Number of recharge network confirmations
└withdrawalNetworkConfirm	int64	Number of withdrawal network confirmations
└ coinTotal	int64	Number of coins
└ masterCoin	string	Main chain currency
└ networkType	string	Main network type (please use this field when the client wants to save the address type)
└ masterCoin	string	Main chain currency
└ avgBlockSecond	num	Average block time (seconds)
└ estimatedMinute	num	Estimated deposit arrival time (minutes)
└ displayName	string	Mainnet display name
└ logo	string	logo address

Callback Notification

When the user address receives the payment and the order is processed, the system will send a notification message to the default callback address configured by the merchant.

Callback address configuration

This interface does not support specifying notifyUrl through request parameters. The system will call back the default callback address configured by the merchant's backend. The default callback address is provided by the merchant when it is created and can be maintained in the operation management background.

Callback request method

HTTP Method

POST

Content-Type

application/json

Callback data example

Depending on the source of funds, the callback data is divided into the following three situations.

Scenario 1: Transfer to this address through the chain (other wallets)

The on-chain transfer scenario will return blockchain on-chain transaction information.

{
  "amount": "6",
  "bizType": "PAYMENT_TRANSFER",
  "blockchain": {
    "network": "TRON",
    "receiverAddress": "TMWFqTEZMDRxNzyfudFBw4rn7QFvMt4kSN",
    "senderAddress": "TPutFhYUQnrRxHSmKVwjp55vgk9QY6r5nS",
    "txId": "8265e6b65d8aad4727b55f79880941c1e22df54278a1f78b28d760eb7328a0d2",
    "txIndex": 0
  },
  "currency": "USDT",
  "merchantActualAmount": "38.86",
  "merchantCurrency": "CNY",
  "merchantId": 308116064181,
  "merchantPaidAmount": "38.86",
  "merchantUserId": "33",
  "notifyTime": 1783671086642,
  "orderCreateTime": 1783671075931,
  "orderId": "566708436246981",
  "status": "SUCCESS",
  "type": "PAYMENT",
  "userAmount": "6",
  "userCurrency": "USDT",
  "userReceivableAmount": "6",
  "sign": "b0d2d52d8dc41af9373431fc8b2b2d6a"
}

Scenario 2: Transfer to this address through internal wallet

The internal wallet payment scenario will return walletUserId of the payer.

{
  "amount": "7",
  "bizType": "PAYMENT_TRANSFER",
  "currency": "USDT",
  "merchantActualAmount": "45.33",
  "merchantCurrency": "CNY",
  "merchantId": 308116064181,
  "merchantPaidAmount": "45.33",
  "merchantUserId": "33",
  "notifyTime": 1783671928955,
  "orderCreateTime": 1783671928956,
  "orderId": "566715422826565",
  "status": "SUCCESS",
  "type": "PAYMENT",
  "userAmount": "7",
  "userCurrency": "USDT",
  "userReceivableAmount": "7",
  "walletUserId": 3,
  "sign": "08c9b45f19709f9d4e8ffbd5bc852eb9"
}

Scenario 3: Withdraw money to this address through Merchant OpenAPI

When a withdrawal order is created through Merchant OpenAPI and withdrawn to this address, the source withdrawal order information fromWithdraw will be returned.

{
  "amount": "8",
  "bizType": "PAYMENT_TRANSFER",
  "currency": "USDT",
  "fromWithdraw": {
    "localOrderId": "17751376202610003",
    "merchantId": 308116064181,
    "orderId": 566716344475973
  },
  "merchantActualAmount": "51.81",
  "merchantCurrency": "CNY",
  "merchantId": 308116064181,
  "merchantPaidAmount": "51.81",
  "merchantUserId": "33",
  "notifyTime": 1783672041921,
  "orderCreateTime": 1783672041922,
  "orderId": "566716348211653",
  "status": "SUCCESS",
  "type": "PAYMENT",
  "userAmount": "8",
  "userCurrency": "USDT",
  "userReceivableAmount": "8",
  "walletUserId": 2,
  "sign": "fc648e11787ccd94accd139453a3c69b"
}

**To meet business development needs, callback parameters may add new fields in the future. The newly added fields participate in signature calculation by default (except for the fields specifically stated in the signature rules). Therefore, the merchant system should have forward compatibility to avoid signature verification failure due to field expansion. **

Callback parameter description

Parameter name	Type	Participating signature	Parameter meaning	Parameter description
amount	decimal	Yes	Order Amount
bizType	enum	Yes	Business type	Fixed to PAYMENT_TRANSFER
blockchain	object	Yes	On-chain transaction information	Only on-chain transfer and recharge scenarios are returned
└ network	String	Yes	Mainnet
└ receiverAddress	String	Yes	Receiver Address
└ senderAddress	String	Yes	Sending address
└ txId	String	Yes	Transaction ID	Blockchain transaction hash
└ txIndex	int	Yes	Transaction Index
currency	String	Yes	Order currency
fromWithdraw	object	Yes	Source withdrawal order information	Only the scenario of withdrawing money to this address through OpenAPI is returned
└ localOrderId	String	Yes	Source merchant order number
└ merchantId	int64	Yes	Source withdrawal order merchant ID
└ orderId	int64	Yes	Source platform order number
merchantActualAmount	decimal	Yes	Merchant’s actual payment amount
merchantCurrency	String	Yes	Merchant settlement currency
merchantId	int64	Yes	Merchant ID
merchantPaidAmount	decimal	Yes	Merchant receivable amount
merchantUserId	String	Yes	Merchant user ID	userId corresponding to the address acquisition interface
notifyTime	long	Yes	Callback time	Callback notification time
orderCreateTime	long	Yes	Order Creation Time
orderId	String	Yes	Order number	Platform order number (unique)
status	String	Yes	Payment Status	SUCCESS, FAIL
type	String	Yes	Order type	Fixed to PAYMENT
userAmount	decimal	Yes	Amount actually paid by the user
userCurrency	String	Yes	User currency
userReceivableAmount	decimal	Yes	User receivable amount
walletUserId	int64	Yes	Wallet internal user ID	Returned when making internal wallet payments or withdrawals to this address via OpenAPI
sign	String	No	Signature value	MD5 signature (see signature algorithm for details)

status status description

Status Value	Description
SUCCESS	Completed
FAIL	Failed

Callback response requirements

After the merchant successfully handles the callback, the following content must be returned:

success

After the system receives the string success, it is deemed that the callback processing is successful and will not be sent again.

Callback retry mechanism

If:

• No response received
• The returned content is not success
• HTTP request exception
• Service timeout

The system will automatically retry sending the callback notification.

Maximum number of retries

14次

Retry interval

15s
15s
30s
180s
600s
1200s
1800s
1800s
1800s
3600s
10800s
10800s
21600s
21600s

It is recommended that the merchant system implements idempotent processing according to orderId to avoid repeated processing of business data due to repeated callbacks.

Signature Verification

After receiving the callback notification, the merchant must first perform signature verification, and then execute the business logic after passing the verification. The signature algorithm is completely consistent with the order request signature rules. Please refer to "2. How to Sign".

Signature Verification Process

1. Get sign in the callback parameter
2. Remove sign from parameters
3. Put the merchant key into the parameters
4. Use merchant secret to recalculate signature according to signature rules
5. Compare whether the calculation result is consistent with sign in the callback

Only after the signature verification is successful, the order business should be processed.

Java signature verification example

public void notify(JSONObject data) {

    log.info("收到回调通知：{}", data.toJSONString());

    String key = "your_key";
    String secret = "your_secret";

    String sign = data.getString("sign");

    data.put("key", key);
    data.remove("sign");

    String calculatedSign = SignUtils.getSign(data, secret);

    if (!calculatedSign.equals(sign)) {
        throw new DxBizException("签名验证失败");
    }
    // 业务处理逻辑
}