3- 3. Devolución de llamada

Cuando se procese el pedido, el sistema enviará un mensaje de notificación a la dirección de devolución de llamada configurada por el comerciante.

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

Al realizar un pedido, puede especificar la dirección de devolución de llamada exclusiva para este pedido a través del parámetro notifyUrl. Esta dirección anulará la dirección de devolución de llamada predeterminada configurada en el backend del comerciante.

param.put("notifyUrl", "http://{domain}/callback/notifyUrl");

Si no se ingresa notifyUrl al realizar un pedido, el sistema devolverá la llamada a la dirección de devolución de llamada predeterminada configurada en 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

{
  "amount": "100",
  "bizType": "WITHDRAW_ANY_DIGITAL_WALLET",
  "blockchain": {
    "network": "TRON",
    "receiverAddress": "THcJ2FeNBkuzd4PZBpRans6tx9QGg9KHRt",
    "senderAddress": "TE35TrUfHjbGEBsVS6zVXdHS8HxXCWwC2y",
    "txIndex": "2",
    "txId": "d848e4b62ec6925b8b3ff49dbc4d839f3f88508497c3af525f0c8293cb303ab3"
  },
  "currency": "CNY",
  "localOrderId": "TestOTM0625ROB016",
  "merchantActualAmount": "138.12",
  "merchantCurrency": "CNY",
  "merchantId": 302992856974,
  "merchantPaidAmount": "100",
  "notifyTime": 1772173006425,
  "orderCreateTime": 1772172958082,
  "orderId": "472515854147845",
  "status": "SUCCESS",
  "type": "WITHDRAW",
  "userAmount": "14.971722",
  "userCurrency": "USDT",
  "userMinerFee": "0",
  "isReissue": false,
  "userReceivableAmount": "14.971722",
  "rate": "6.71080951",
  "rateExpression": "1USDT≈6.7108CNY",
  "sign": "2c27c7e8184cc709a64ad502ee42eab7",
  "key": "9yUreYgTRtit39Dy"
}

**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 pedido	La descripción del tipo de pedido es la siguiente
blockchain	object	Sí	Información de transacciones en cadena	Información de transacciones en cadena, devuelta solo cuando isBlockchain=true
└red	String	Sí	Red principal
└dirección del receptor	String	Sí	Dirección del destinatario
└Dirección del remitente	decimal	Sí	Dirección de envío
└txId	String	Sí	ID de transacción	Hash de transacciones de blockchain
└txÍndice	String	Sí	Índice de transacciones	Índice de transacciones (escenario de transferencia por lotes)
currency	String	Sí	Moneda	Moneda del pedido
key	String	Sí	Clave de comerciante
localOrderId	String	Sí	Número de pedido del comerciante
merchantActualAmount	decimal	Sí	Monto de pago real del comerciante
merchantCurrency	String	Sí	Moneda de liquidación mercantil
merchantId	String	Sí	Identificación del comerciante
merchantPaidAmount	decimal	Sí	Importe a cobrar o a pagar por el comerciante
merchantUserId	String	Sí	ID de usuario del comerciante
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	ÉXITO, FRACASO (descripción a continuación)
type	String	Sí	Tipo de pedido	PAGO, RETIRO (descripción a continuación)
userAmount	decimal	Sí	El importe realmente recibido o pagado por el usuario
userCurrency	String	Sí	Moneda del usuario
userMinerFee	String	Sí	Tarifa minera
userReceivableAmount	String	Sí	Importe a pagar o a cobrar por el usuario
isReissue	Boolean	Sí	Ya sea para reeditar	Ya sea para volver a emitir la devolución de llamada
rate	string	Sí	Tipo de cambio
rateExpression	string	Sí	Expresión del tipo de cambio
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

tipo tipo descripción

Tipo Valor	Descripción
PAYMENT	Pago
WITHDRAW	Retiro

bizType descripción del tipo de negocio

tipo de negocio	Descripción
PAYMENT_WALLET_SCAN	Código de escaneo de billetera VPAY para pagar
PAYMENT_TRANSFER	Depósito directo de dirección vinculante de moneda digital
PAYMENT_ANY_DIGITAL_SCAN	Escanea el código QR para pagar cualquier cantidad de moneda digital
PAYMENT_FIXED_DIGITAL_SCAN	Pago de código de escaneo de cantidad fija en moneda digital
WITHDRAW_WALLET	Retirar a la billetera VPAY
WITHDRAW_ANY_DIGITAL_WALLET	Retirar a cualquier billetera digital
BATCH_PAY	Pago por lotes

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

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

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

1. Obtenga sign en el parámetro de devolución de llamada.
2. Eliminar sign de los parámetros
3. Ponga el comerciante key en los parámetros.
4. Utilice el comerciante secret para recalcular la firma de acuerdo con las reglas de firma.
5. 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("签名验证失败");
    }
    // 业务处理逻辑
}