> ## Documentation Index
> Fetch the complete documentation index at: https://docs.velafi.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Evento de orden

> Referencia del payload del evento ORDER_WEBHOOK que VelaFi envía a tu endpoint cuando cambia el estado de una orden de fiat a cripto o de cripto a fiat.

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

| Encabezado | 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](https://docs.velafi.com/es/api-reference/webhooks/webhook-setup.md). |
| `Content-Type` | `application/json` |

## Códigos de estado de la orden

| Código | Significado |
| - | - |
| `10` | En revisión: la orden está en revisión |
| `11` | Revisión de riesgo: la orden está en revisión de riesgo |
| `12` | Documento de RFI cargado: se cargó un documento solicitado durante la revisión de riesgo |
| `31` | Documentos de soporte pendientes |
| `32` | En espera de depósito de cripto |
| `40` | Pago pendiente: en espera del pago |
| `50` | Pagada: pago recibido |
| `60` | Completada: orden completada |
| `70` | Cancelada: cancelada, rechazada o con tiempo de espera agotado |
| `72` | Reembolsada: la orden fue reembolsada |

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

**webhookId** `string`

ID del endpoint de webhook que entregó este evento.

**eventType** `string`

Siempre es `ORDER_WEBHOOK` para este tipo de evento.

**orderId** `string`

Identificador único de la orden.

**clientId** `string`

El identificador de la orden que proporcionaste. Se omite si no proporcionaste uno.

**userId** `string`

ID de tu cuenta (usuario) de VelaFi.

**merchantId** `string`

ID del comercio al que pertenece esta orden.

**settingsId** `string`

ID de la configuración de cuenta del comercio (canal de pago) usada para la orden.

**orderType** `string`

Dirección de la operación: `BUY` (fiat → cripto) o `SELL` (cripto → fiat).

**fiat** `string`

Moneda fiat de la orden, por ejemplo `MXN`.

**fiatAmount** `string`

Monto en fiat de la orden.

**arriveFiatAmount** `string`

Monto en fiat efectivamente pagado o recibido.

**fiatFee** `string`

Comisión en fiat cobrada por la orden.

**crypto** `string`

Criptomoneda de la orden, por ejemplo `USDT`.

**cryptoAmount** `string`

Monto en cripto de la orden.

**orderPrice** `string`

Tipo de cambio al que se ejecutó la orden (fiat por unidad de cripto).

**orderStatus** `string`

Código del estado actual de la orden. Consulta la tabla de estados de arriba.

**failCode** `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.

**failReason** `string`

Descripción legible del fallo. Solo está presente cuando `failCode` está presente y hay una descripción registrada.

**createTime** `string`

Marca de tiempo Unix (milisegundos) en la que se creó la orden.

**updateTime** `string`

Marca de tiempo Unix (milisegundos) de la última actualización de la orden.

**timestamp** `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

```json Cuerpo del POST entrante theme={null}
{
  "webhookId": "ebab8a9663704e7cbbebe672c7c67912",
  "eventType": "ORDER_WEBHOOK",
  "orderId": "473130522693193728",
  "clientId": "W658784738723",
  "userId": "455472",
  "merchantId": "4",
  "settingsId": "12",
  "orderType": "SELL",
  "fiat": "MXN",
  "fiatAmount": "99",
  "arriveFiatAmount": "99",
  "fiatFee": "0",
  "crypto": "USDT",
  "cryptoAmount": "5",
  "orderPrice": "19.8158",
  "orderStatus": "60",
  "createTime": "1735279907000",
  "updateTime": "1735280582000",
  "fiatCurrency": "MXN",
  "orderAmount": "99",
  "arriveOrderAmount": "99",
  "mcSettingsId": "12",
  "cryptoCurrency": "USDT",
  "quantity": "5",
  "timestamp": "1735280582345"
}
```

## Respuesta requerida

Devuelve el siguiente cuerpo JSON con el estado HTTP `200` para confirmar la recepción:

```json Tu respuesta theme={null}
{
  "callbackStatus": "SUCCESS"
}
```

> [!NOTE]
>
> 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](https://docs.velafi.com/es/api-reference/webhooks/webhook-setup.md#delivery-and-retries).


## Related topics

- [Webhooks](https://docs.velafi.com/es/docs/guides/webhooks.md)
- [Evento de pago global](https://docs.velafi.com/es/api-reference/webhooks/fiat-fiat-order-message-push.md)
- [Evento de retiro de on-ramp](https://docs.velafi.com/es/api-reference/webhooks/on-ramp-withdraw-message-push.md)
- [Evento de pago con stablecoin](https://docs.velafi.com/es/api-reference/webhooks/stablecoin-payment-order-message-push.md)
- [Configuración de webhooks](https://docs.velafi.com/es/api-reference/webhooks/webhook-setup.md)


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.