7.4.3 获取用户链上地址

#简要描述：获取用户链上地址(如果不存在则创建)。

请求方式: POST
请求接口: https://网关域名/wallet-trade-merchant/merchant/user/get-address
请求媒体类型( JSON 数据格式 )Content-Type: application/json

查询参数

参数名称	类型	必填	参数含义	参数说明
merchantId	int64	是	商户 ID
userId	string	是	用户 ID	商户本地用户唯一 ID
network	string	是	主网	支持 TRON、BSC、POLYGON、ETHEREUM（可通过文档7.4.2获取）
key	string	是	商户 key	平台分配商户 key
sign	string	是	签名参照（如何签名）	详见如何签名规则

请求 json 样例

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

响应 json 示例

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

响应data 参数说明

参数名称	类型	参数含义	备注
merchantId	int64	商户 ID
userId	string	用户 ID	商户本地用户唯一 ID
address	string	链地址	用户的链地址
network	object	链主网信息
└ name	string	主网名称
└ queryBaseUrl	string	链上查询网址
└ collectionNetworkConfirm	int64	充值网络确认次数
└withdrawalNetworkConfirm	int64	出款网络确认次数
└ coinTotal	int64	币数量
└ masterCoin	string	主链币种
└ networkType	string	主网类型(客户端要保存地址类型时，请使用这个字段)
└ masterCoin	string	主链币种
└ avgBlockSecond	num	平均出块时间(秒)
└ estimatedMinute	num	预计充值到账时间(分钟)
└ displayName	string	主网显示名称
└ logo	string	logo地址

回调通知

当该用户地址收到款项且订单处理完成后，系统会向商户配置的默认回调地址发送通知消息。

回调地址配置

该接口不支持通过请求参数指定 notifyUrl，系统将回调商户后台配置的默认回调地址。默认回调地址由商户创建时提供，并可在运营管理后台进行维护。

回调请求方式

HTTP Method

POST

Content-Type

application/json

回调数据示例

根据款项来源不同，回调数据分为以下三种情况。

情况一：通过链上（其它钱包）转账至该地址

链上转账场景会返回 blockchain 链上交易信息。

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

情况二：通过内部钱包转账至该地址

内部钱包支付场景会返回付款方的 walletUserId。

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

情况三：通过商户OpenAPI 提款至该地址

通过商户OpenAPI 创建提款订单并提款至该地址时，会返回来源提款订单信息 fromWithdraw。

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

为满足业务发展需要，回调参数未来可能新增字段。新增字段默认参与签名计算（除签名规则中特别说明的字段外），因此商户系统应具备向前兼容能力，避免因字段扩展导致验签失败。

回调参数说明

参数名称	类型	参与签名	参数含义	参数说明
amount	decimal	是	订单金额
bizType	enum	是	业务类型	固定为 `PAYMENT_TRANSFER`
blockchain	object	是	链上交易信息	仅链上转账充值场景返回
└ network	String	是	主网
└ receiverAddress	String	是	接收地址
└ senderAddress	String	是	发送地址
└ txId	String	是	交易 ID	区块链交易哈希
└ txIndex	int	是	交易索引
currency	String	是	订单币种
fromWithdraw	object	是	来源提款订单信息	仅通过 OpenAPI 提款至该地址的场景返回
└ localOrderId	String	是	来源商户订单号
└ merchantId	int64	是	来源提款订单商户 ID
└ orderId	int64	是	来源平台订单号
merchantActualAmount	decimal	是	商户实际收款金额
merchantCurrency	String	是	商户结算币种
merchantId	int64	是	商户 ID
merchantPaidAmount	decimal	是	商户应收金额
merchantUserId	String	是	商户用户 ID	对应获取地址接口的 `userId`
notifyTime	long	是	回调时间	回调通知时间
orderCreateTime	long	是	订单创建时间
orderId	String	是	订单号	平台订单号（唯一）
status	String	是	支付状态	`SUCCESS`、`FAIL`
type	String	是	订单类型	固定为 `PAYMENT`
userAmount	decimal	是	用户实付金额
userCurrency	String	是	用户币种
userReceivableAmount	decimal	是	用户应收金额
walletUserId	int64	是	钱包内部用户 ID	内部钱包支付或通过 OpenAPI 提款至该地址时返回
sign	String	否	签名值	MD5 签名（详情参见签名算法）

status 状态说明

状态值	说明
SUCCESS	已完成
FAIL	已失败

回调响应要求

商户成功处理回调后，必须返回以下内容：

success

系统收到字符串 success 后，视为回调处理成功，不再重复发送。

回调重试机制

如果出现以下情况：

未收到响应
返回内容不是 success
HTTP 请求异常
服务超时

系统将自动重试发送回调通知。

最大重试次数

14次

重试间隔

建议商户系统按照 orderId 实现幂等处理，避免因重复回调导致业务数据重复处理。

签名校验

收到回调通知后，商户必须先进行签名验证，验证通过后再执行业务逻辑。签名算法与下单请求签名规则完全一致，请参考《2. 如何签名》。

验签流程

获取回调参数中的 sign
从参数中移除 sign
将商户 key 放入参数
使用商户 secret 按签名规则重新计算签名
比较计算结果与回调中的 sign 是否一致

只有验签成功后，才应处理订单业务。

Java 验签示例

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("签名验证失败");
    }
    // 业务处理逻辑
}

查询参数​

请求 json 样例​

响应data 参数说明​

回调通知

回调地址配置​

回调请求方式​

回调数据示例​

情况一：通过链上（其它钱包）转账至该地址​

情况二：通过内部钱包转账至该地址​

情况三：通过 商户OpenAPI 提款至该地址​

回调参数说明​

status 状态说明​

回调响应要求​

回调重试机制​

最大重试次数​

重试间隔​