7.4.3 Obtener la dirección en cadena del usuario

#Breve descripción: Obtenga la dirección en cadena del usuario (créela si no existe).

Método de solicitud: POST
Interfaz de solicitud: https://gateway-domain/wallet-trade-merchant/merchant/user/get-address
Solicitar tipo de medio (formato de datos JSON) Tipo de contenido: aplicación/json

Parámetros de consulta

Nombre del parámetro	Tipo	Obligatorio	Significado del parámetro	Descripción del parámetro
`merchantId`	`int64`	Sí	Identificación del comerciante
`userId`	`string`	Sí	ID de usuario	ID único del usuario local del comerciante
`network`	`string`	Sí	Red principal	Soporta TRON, BSC, POLYGON, ETHEREUM (disponible a través del documento 7.4.2)
`key`	`string`	Sí	Clave de comerciante	Clave de comerciante asignada por la plataforma
`sign`	`string`	Sí	Referencia de firma (cómo firmar)	Vea cómo firmar reglas para más detalles

Solicitar muestra json

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

Ejemplo de respuesta 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
}

Descripción del parámetro de datos de respuesta

Nombre del parámetro	Tipo	Significado del parámetro	Observaciones
`merchantId`	`int64`	Identificación del comerciante
`userId`	`string`	ID de usuario	ID única del usuario local del comerciante
`address`	`string`	Dirección de cadena	Dirección de cadena del usuario
`network`	`object`	Cadena de información de la red principal
└ nombre	`string`	Nombre de la red principal
└ consultaBaseUrl	`string`	URL de consulta en cadena
└ colecciónRedConfirmar	`int64`	Número de confirmaciones de red de recarga
└confirmación de red de retiro	`int64`	Número de confirmaciones de la red de retiros
└ monedaTotal	`int64`	Número de monedas
└ masterCoin	`string`	Moneda de la cadena principal
└ tipo de red	`string`	Tipo de red principal (utilice este campo cuando el cliente desee guardar el tipo de dirección)
└ masterCoin	`string`	Moneda de la cadena principal
└ avgBlockSecond	`num`	Tiempo medio de bloqueo (segundos)
└ Minuto estimado	`num`	Tiempo estimado de llegada del depósito (minutos)
└ nombre para mostrar	`string`	Nombre para mostrar de la red principal
└ logotipo	`string`	dirección del logotipo

Notificación de devolución de llamada

Cuando la dirección del usuario recibe el pago y se procesa el pedido, el sistema enviará un mensaje de notificación a la dirección de devolución de llamada predeterminada configurada por el comerciante.

Configuración de la dirección de devolución de llamada

Esta interfaz no admite la especificación de notifyUrl a través de parámetros de solicitud. El sistema devolverá la llamada a la dirección de devolución de llamada predeterminada configurada por el backend del comerciante. La dirección de devolución de llamada predeterminada la proporciona el comerciante cuando se crea y se puede mantener en segundo plano de la gestión de operaciones.

Método de solicitud de devolución de llamada

Método HTTP

POST

Tipo de contenido

application/json

Ejemplo de datos de devolución de llamada

Dependiendo de la fuente de fondos, los datos de devolución de llamada se dividen en las tres situaciones siguientes.

Escenario 1: Transferencia a esta dirección a través de la cadena (otras billeteras)

El escenario de transferencia en cadena devolverá blockchain información de la transacción en cadena.

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

Escenario 2: Transferencia a esta dirección a través de una billetera interna

El escenario de pago de billetera interna devolverá walletUserId del pagador.

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

Escenario 3: retirar dinero a esta dirección a través de Merchant OpenAPI

Cuando se crea una orden de retiro a través de Merchant OpenAPI y se retira a esta dirección, se devolverá la información de la orden de retiro de origen 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"
}

**Para satisfacer las necesidades de desarrollo empresarial, los parámetros de devolución de llamada pueden agregar nuevos campos en el futuro. Los campos recién agregados participan en el cálculo de la firma de forma predeterminada (excepto los campos específicamente establecidos en las reglas de firma). Por lo tanto, el sistema comercial debe tener compatibilidad hacia adelante para evitar fallas en la verificación de firmas debido a la expansión del campo. **

Descripción del parámetro de devolución de llamada

Nombre del parámetro	Tipo	Firma participante	Significado del parámetro	Descripción del parámetro
`amount`	`decimal`	Sí	Monto del pedido
`bizType`	`enum`	Sí	Tipo de negocio	Fijado en `PAYMENT_TRANSFER`
`blockchain`	`object`	Sí	Información de transacciones en cadena	Solo se devuelven escenarios de recarga y transferencia en cadena
└ red	`String`	Sí	Red principal
└ dirección del receptor	`String`	Sí	Dirección del destinatario
└ dirección del remitente	`String`	Sí	Dirección de envío
└ ID de tx	`String`	Sí	ID de transacción	Hash de transacciones de blockchain
└ txIndex	`int`	Sí	Índice de transacciones
`currency`	`String`	Sí	Moneda del pedido
`fromWithdraw`	`object`	Sí	Información de la orden de retiro de origen	Solo se devuelve el escenario de retirar dinero a esta dirección a través de OpenAPI
└ ID de pedido local	`String`	Sí	Número de pedido del comerciante de origen
└ ID de comerciante	`int64`	Sí	ID de comerciante de orden de retiro de origen
└ ID de pedido	`int64`	Sí	Número de pedido de la plataforma fuente
`merchantActualAmount`	`decimal`	Sí	Monto de pago real del comerciante
`merchantCurrency`	`String`	Sí	Moneda de liquidación mercantil
`merchantId`	`int64`	Sí	Identificación del comerciante
`merchantPaidAmount`	`decimal`	Sí	Importe por cobrar del comerciante
`merchantUserId`	`String`	Sí	ID de usuario del comerciante	`userId` correspondiente a la interfaz de adquisición de direcciones
`notifyTime`	`long`	Sí	Tiempo de devolución de llamada	Hora de notificación de devolución de llamada
`orderCreateTime`	`long`	Sí	Hora de creación del pedido
`orderId`	`String`	Sí	Número de pedido	Número de pedido de plataforma (único)
`status`	`String`	Sí	Estado de pago	`SUCCESS`, `FAIL`
`type`	`String`	Sí	Tipo de pedido	Fijado en `PAYMENT`
`userAmount`	`decimal`	Sí	Importe realmente pagado por el usuario
`userCurrency`	`String`	Sí	Moneda del usuario
`userReceivableAmount`	`decimal`	Sí	Importe por cobrar del usuario
`walletUserId`	`int64`	Sí	ID de usuario interno de billetera	Devuelto al realizar pagos o retiros de billetera interna a esta dirección a través de OpenAPI
`sign`	`String`	No	Valor de firma	Firma MD5 (consulte el algoritmo de firma para obtener más detalles)

estado descripción del estado

Valor de estado	Descripción
`SUCCESS`	Completado
`FAIL`	Fallido

Requisitos de respuesta de devolución de llamada

Después de que el comerciante maneje con éxito la devolución de llamada, se debe devolver el siguiente contenido:

success

Después de que el sistema recibe la cadena success, se considera que el procesamiento de la devolución de llamada fue exitoso y no se volverá a enviar.

Mecanismo de reintento de devolución de llamada

Si:

No se recibió respuesta
El contenido devuelto no es success
Excepción de solicitud HTTP
Tiempo de espera del servicio

El sistema volverá a intentar enviar automáticamente la notificación de devolución de llamada.

Número máximo de reintentos

14次

Intervalo de reintento

Se recomienda que el sistema comercial implemente el procesamiento idempotente de acuerdo con orderId para evitar el procesamiento repetido de datos comerciales debido a devoluciones de llamadas repetidas.

Verificación de firma

Después de recibir la notificación de devolución de llamada, el comerciante primero debe realizar una verificación de firma y luego ejecutar la lógica comercial después de pasar la verificación. El algoritmo de firma es completamente consistente con las reglas de firma de solicitud de pedido. Consulte "2. Cómo firmar".

Proceso de verificación de firma

Obtenga sign en el parámetro de devolución de llamada.
Eliminar sign de los parámetros
Ponga el comerciante key en los parámetros.
Utilice el comerciante secret para recalcular la firma de acuerdo con las reglas de firma.
Compare si el resultado del cálculo es consistente con sign en la devolución de llamada

Solo después de que la verificación de la firma sea exitosa, se debe procesar el pedido comercial.

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

Parámetros de consulta​

Solicitar muestra json​

Descripción del parámetro de datos de respuesta​

Notificación de devolución de llamada

Configuración de la dirección de devolución de llamada​

Método de solicitud de devolución de llamada​

Ejemplo de datos de devolución de llamada​

Escenario 1: Transferencia a esta dirección a través de la cadena (otras billeteras)​

Escenario 2: Transferencia a esta dirección a través de una billetera interna​

Escenario 3: retirar dinero a esta dirección a través de Merchant OpenAPI​

Descripción del parámetro de devolución de llamada​

estado descripción del estado​

Requisitos de respuesta de devolución de llamada​

Mecanismo de reintento de devolución de llamada​

Número máximo de reintentos​

Intervalo de reintento​