Saltar al contenido principal
Cuando una orden fiat/cripto creada mediante la API entra en uno de los estados que se indican abajo, VelaFi envía una solicitud HTTP POST firmada a tu endpoint ORDER_WEBHOOK registrado. Las órdenes que no se crearon mediante la API no activan este webhook. El payload contiene la instantánea completa de la orden, incluidos los montos, el precio y el código de estado actualizado. Tu endpoint debe verificar el encabezado signature y responder con {"callbackStatus": "SUCCESS"} para confirmar la recepción.

​
Encabezados de la solicitud

​
Códigos de estado de la orden

Las órdenes que se cancelan, se rechazan en la revisión de la API o de riesgo, o cuyo tiempo de espera se agota, se envían con orderStatus 70. Otros estados, como 20, 30, 71 y 73, no se envían.

​
Campos del payload

​
string
ID del endpoint de webhook que entregó este evento.
​
string
Siempre es ORDER_WEBHOOK para este tipo de evento.
​
string
Identificador único de la orden.
​
string
El identificador de la orden que proporcionaste. Se omite si no proporcionaste uno.
​
string
ID de tu cuenta (usuario) de VelaFi.
​
string
ID del comercio al que pertenece esta orden.
​
string
ID de la configuración de cuenta del comercio (canal de pago) usada para la orden.
​
string
Dirección de la operación: BUY (fiat → cripto) o SELL (cripto → fiat).
​
string
Moneda fiat de la orden, por ejemplo MXN.
​
string
Monto en fiat de la orden.
​
string
Monto en fiat efectivamente pagado o recibido.
​
string
Comisión en fiat cobrada por la orden.
​
string
Criptomoneda de la orden, por ejemplo USDT.
​
string
Monto en cripto de la orden.
​
string
Tipo de cambio al que se ejecutó la orden (fiat por unidad de cripto).
​
string
Código del estado actual de la orden. Consulta la tabla de estados de arriba.
​
string
Código de fallo legible por máquina. Solo está presente en órdenes canceladas (70) o reembolsadas (72) que tienen un código de fallo registrado; en otros casos se omite.
​
string
Descripción legible del fallo. Solo está presente cuando failCode está presente y hay una descripción registrada.
​
string
Marca de tiempo Unix (milisegundos) en la que se creó la orden.
​
string
Marca de tiempo Unix (milisegundos) de la última actualización de la orden.
​
string
Marca de tiempo Unix (milisegundos) en la que se firmó este intento de entrega.
Por compatibilidad con versiones anteriores, el payload también contiene fiatCurrency, orderAmount, arriveOrderAmount, mcSettingsId, cryptoCurrency y quantity, que repiten fiat, fiatAmount, arriveFiatAmount, settingsId, crypto y cryptoAmount. Algunas órdenes incluyen campos adicionales, como bankOrderId. Ignora los campos que no uses.

​
Ejemplo de payload

Cuerpo del POST entrante

​
Respuesta requerida

Devuelve el siguiente cuerpo JSON con el estado HTTP 200 para confirmar la recepción:
Tu respuesta
VelaFi reintenta la entrega si tu endpoint devuelve un estado distinto de 2xx, no responde a tiempo o devuelve cualquier otro cuerpo. El mismo evento puede llegar más de una vez, así que elimina duplicados usando orderId junto con orderStatus. Consulta Entrega y reintentos.