Evento de retiro cripto

Cuando un retiro cripto desde una de las billeteras de tu comercio llega a un estado final, VelaFi envía una solicitud HTTP POST firmada a tu endpoint de CRYPTO_WITHDRAW_WEBHOOK. Verifica el header signature y responde con {"callbackStatus": "SUCCESS"} para confirmar la recepción. El evento cubre:

Retiros a direcciones externas creados con Crear retiro cripto o en el panel de VelaFi.
Elementos de pagos masivos enviados a direcciones externas.
Retiros automáticos de órdenes de on-ramp a la dirección de destino de la orden. Estos también disparan ON_RAMP_WITHDRAW_WEBHOOK cuando son exitosos, así que si te suscribes a ambos tipos de evento recibirás dos notificaciones por la misma transferencia.

No se envía para:

Retiros a una dirección de billetera de VelaFi creados con Crear retiro cripto o en el panel. Estos se registran como transferencias internas y aparecen en Historial de transferencias cripto.
Reembolsos de pagos con stablecoin, aunque aparezcan en Obtener historial de retiros cripto.
Retiros que siguen en curso, esperando aprobación o en revisión. Solo se envían los estados finales.

Registra este tipo de evento con Crear webhook usando "eventType": "CRYPTO_WITHDRAW_WEBHOOK". Como con todos los tipos de evento, un webhook recibe el evento para todos los comercios de tu cuenta, y los webhooks no se disparan en el sandbox.

Headers de la solicitud

Header	Descripción
`signature`	Firma RSA-SHA256 del cuerpo sin procesar de la solicitud, codificada en hexadecimal. Usa la `publicKey` de tu webhook para verificarla. Consulta Configuración de webhooks.
`Content-Type`	`application/json`

Campos del payload

Todos los valores se envían como cadenas JSON.

string

El ID del webhook para el que se encoló el evento.

string

Siempre CRYPTO_WITHDRAW_WEBHOOK para este tipo de evento.

string

ID del registro de retiro. Coincide con el orderId que devuelven Crear retiro cripto y Obtener historial de retiros cripto.

string

El clientId del retiro: el valor que proporcionaste en Crear retiro cripto, o el orderId de on-ramp en el caso de un retiro automático de on-ramp. Todos los elementos de un pago masivo comparten el mismo valor, con el formato masspayout:<id>. Vacío si el retiro no tiene uno.

string

El ID de tu cuenta (usuario) de VelaFi.

string

Comercio cuya billetera se debitó.

string

Símbolo del token, por ejemplo USDT.

string

Red del retiro, por ejemplo TRC20. Es el mismo valor que chainType en Obtener cuota de retiro.

string

Dirección de destino.

string

Monto del retiro (el mismo valor que cryptoAmount en Obtener historial de retiros cripto).

string

Comisión de red, en el mismo token que crypto. Siempre 0 en los retiros automáticos de on-ramp.

string

amount menos fee (el mismo valor que arriveCryptoAmount en Obtener historial de retiros cripto).

string

Resultado final del retiro:

SUCCESS — el retiro se completó on-chain.
FAILED — el retiro falló o VelaFi lo rechazó, y el monto se devolvió al saldo de la billetera.
REFUNDED — los fondos ya habían salido de la billetera de VelaFi, regresaron y se devolvieron al saldo de la billetera. Manéjalo igual que FAILED.
CANCELLED — el retiro se canceló en el panel de VelaFi antes de enviarse, y el monto se devolvió al saldo de la billetera. La Open API no tiene un endpoint de cancelación.

string

El código de status correspondiente de Obtener historial de retiros cripto: 6 para SUCCESS, 7 para FAILED y REFUNDED, y 9 para CANCELLED.

string

Hash de la transacción on-chain. Solo se incluye cuando status es SUCCESS.

string

Momento en que se creó el retiro (marca de tiempo Unix en milisegundos).

string

Momento en que el retiro llegó a su estado final (marca de tiempo Unix en milisegundos).

string

Marca de tiempo Unix (milisegundos) en la que se firmó este intento de entrega.

Ejemplos de payloads

SUCCESS
FAILED

Incoming POST body

{
  "webhookId": "ebab8a9663704e7cbbebe672c7c67912",
  "eventType": "CRYPTO_WITHDRAW_WEBHOOK",
  "withdrawId": "512345678901234567",
  "clientId": "withdraw-0001",
  "userId": "455472",
  "merchantId": "100001",
  "crypto": "USDT",
  "network": "TRC20",
  "address": "YOUR_DESTINATION_ADDRESS",
  "amount": "100",
  "fee": "1",
  "netAmount": "99",
  "status": "SUCCESS",
  "statusCode": "6",
  "txHash": "4a7f0c3e2b1d9f8e7a6b5c4d3e2f1a0b9c8d7e6f5a4b3c2d1e0f9a8b7c6d5e4f",
  "createTime": "1735279907000",
  "completeTime": "1735280100000",
  "timestamp": "1735280101000"
}

Incoming POST body

{
  "webhookId": "ebab8a9663704e7cbbebe672c7c67912",
  "eventType": "CRYPTO_WITHDRAW_WEBHOOK",
  "withdrawId": "512345678901234568",
  "clientId": "withdraw-0002",
  "userId": "455472",
  "merchantId": "100001",
  "crypto": "USDT",
  "network": "TRC20",
  "address": "YOUR_DESTINATION_ADDRESS",
  "amount": "100",
  "fee": "1",
  "netAmount": "99",
  "status": "FAILED",
  "statusCode": "7",
  "createTime": "1735279907000",
  "completeTime": "1735283507000",
  "timestamp": "1735283508000"
}

Respuesta requerida

Devuelve un estado HTTP 2xx (por ejemplo 200) con el siguiente cuerpo JSON para confirmar la recepción:

Your response

{
  "callbackStatus": "SUCCESS"
}

Notas de manejo

Un evento final por retiro. VelaFi envía el evento una vez que un retiro llega a un estado final. Los estados intermedios, como aprobación o revisión, no se envían. Para consultar un retiro antes de que sea final, usa Obtener historial de retiros cripto.
Duplicados. El mismo evento puede llegar más de una vez, así que deduplica por withdrawId y status. Consulta Entrega y reintentos.
Concilia los eventos perdidos. Si tu endpoint pierde todos los intentos de entrega, el evento no se vuelve a entregar. Concilia los retiros pendientes con Obtener historial de retiros cripto, haciendo coincidir por clientId o, para los elementos de pagos masivos, por withdrawId (orderId en el historial). No mantengas bloqueado indefinidamente el saldo de un usuario de tu lado.
Reemplazar un webhook. A diferencia de otros tipos de evento, las entregas pendientes solo van al webhook para el que se encolaron. Si creas un nuevo webhook de CRYPTO_WITHDRAW_WEBHOOK después de eliminar o desactivar el anterior, los eventos que siguen encolados para el webhook anterior no se entregan. Para cambiar a dónde van los eventos, actualiza la URL del webhook existente con Actualizar webhook. Los eventos pendientes de un webhook desactivado se entregan si vuelves a activar ese mismo webhook sin crear otro.

Descripción general

Cuenta

Configuración

Comercios

Billetera cripto

Beneficiarios

Cotizaciones

Órdenes

Webhooks

Evento de retiro cripto

Headers de la solicitud

Campos del payload

Ejemplos de payloads

Respuesta requerida

Notas de manejo

​Headers de la solicitud

​Campos del payload

​Ejemplos de payloads

​Respuesta requerida

​Notas de manejo

Headers de la solicitud

Campos del payload

Ejemplos de payloads

Respuesta requerida

Notas de manejo