> ## 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.

# Off-ramp (cripto a fiat)

> Acepta cripto de tus usuarios y entrega moneda fiat local directamente en sus cuentas bancarias con la API de off-ramp de cripto a fiat de VelaFi.

El off-ramp de cripto a fiat de VelaFi convierte cripto del saldo cripto de tu comercio en moneda fiat local —como MXN, ARS, BRL o COP— que se deposita directamente en las cuentas bancarias de tus usuarios. La API se encarga de la cotización del tipo de cambio, el cargo de la cripto a tu saldo del comercio, la conversión y el inicio de la transferencia bancaria, para que puedas ofrecer flujos de retiro de efectivo sin fricciones sin tener que administrar tú mismo infraestructura de pagos local.

### Confirma los requisitos previos

Antes de crear una orden off-ramp, asegúrate de tener lista la siguiente configuración:

* **Cuenta del comercio activada**: el registro de tu comercio debe existir y su cuenta fiat debe estar activa para la dirección off-ramp.
* **Beneficiario agregado**: la cuenta bancaria del usuario debe estar registrada como beneficiario en tu cuenta de VelaFi. El `userPaymentId` del registro del beneficiario es obligatorio para crear una orden off-ramp. Consulta [Crear un beneficiario](https://docs.velafi.com/es/docs/guides/managing-beneficiaries.md) para ver los pasos de registro.
* **Saldo cripto fondeado**: la cripto de la orden se carga al saldo cripto del comercio. Revísalo con [Saldo cripto](https://docs.velafi.com/es/api-reference/merchant/get-crypto-assets-balance.md) y recárgalo mediante la [dirección de depósito](https://docs.velafi.com/es/api-reference/merchant/get-crypto-deposit-address.md) del comercio.
* **Credenciales de API disponibles**: todas las solicitudes requieren el encabezado `X-BH-TOKEN` con un token de negocio obtenido de `GET /v2/token/generate`.

### Obtén una cotización (opcional)

Solicita un tipo de cambio en tiempo real antes de crear la orden. El `price` está expresado en unidades de fiat por 1 unidad de cripto. Con `createQuoteId=true`, la respuesta también incluye un `quoteId` que fija el tipo de cambio.

**Endpoint:** `GET /v2/user/crypto-quote`

**Parámetros de consulta:**

**country** `string` *required*

Nombre del país donde se entregará el pago en fiat (por ejemplo, `"Mexico"`).

**from** `string` *required*

La criptomoneda que se vende (por ejemplo, `"USDT"`).

**to** `string` *required*

La moneda fiat que se recibirá (por ejemplo, `"MXN"`).

**createQuoteId** `boolean`

Establécelo en `true` para generar un `quoteId` que puedes enviar al crear la orden para fijar el precio cotizado.

**Ejemplo de respuesta:**

```json theme={null}
{
  "code": 200,
  "msg": "SUCCESS",
  "data": {
    "price": "21.4104",
    "quoteId": "e46836d68a4a4a6f8f2f609352cffb2f"
  }
}
```

> [!TIP]
>
> El `quoteId` es válido durante **10 segundos** en producción (300 segundos en el sandbox) y, de forma predeterminada, es de un solo uso. Envíalo en la solicitud de creación de la orden para garantizar el tipo de cambio cotizado. Si lo omites, la orden usa el tipo de cambio vigente al momento de crearla.

### Crea la orden off-ramp

Envía una solicitud `POST` a `/v2/order/crypto_to_fiat`. VelaFi carga la cripto al saldo cripto del comercio, la convierte al tipo de cambio acordado y paga el monto en fiat a la cuenta del beneficiario. La respuesta devuelve un `orderId` para darle seguimiento.

**Endpoint:** `POST /v2/order/crypto_to_fiat`

#### Parámetros de la solicitud

**country** `string` *required*

Nombre del país al que se enviará el pago en fiat (por ejemplo, `"Mexico"`).

**crypto** `string` *required*

Criptomoneda que vende el usuario (por ejemplo, `"USDT"`).

**fiat** `string` *required*

Moneda fiat que recibirá el usuario (por ejemplo, `"MXN"`).

**userPaymentId** `number` *required*

ID de la cuenta bancaria registrada del beneficiario (se devuelve al agregar un beneficiario). Consulta [Obtener beneficiarios](https://docs.velafi.com/es/api-reference/beneficiary/get-beneficiary.md).

**cryptoAmount** `decimal`

Monto de criptomoneda que se venderá (por ejemplo, `1000.00`). Envía `cryptoAmount` o `fiatAmount`.

**fiatAmount** `decimal`

Monto objetivo en fiat que debe recibir el usuario (por ejemplo, `21410.40`). Envía `fiatAmount` o `cryptoAmount`.

**quoteId** `string`

ID de cotización de `GET /v2/user/crypto-quote`. Envíalo para fijar el tipo de cambio cotizado para esta orden.

**clientId** `string`

Tu propio ID de referencia de la orden, de hasta 40 caracteres, único entre todas tus órdenes `fiat_to_crypto` y `crypto_to_fiat`. Un `clientId` repetido se rechaza, así que puedes reintentar con seguridad una solicitud de creación con el mismo valor. Se devuelve tal cual en las consultas posteriores de la orden. Consulta [Idempotencia y reintentos](https://docs.velafi.com/es/api-reference/order/create-a-fiat-to-crypto-order.md#idempotency-and-retries).

**merchantId** `number` *required*

ID del comercio al que pertenece la orden. La cripto se carga al saldo de este comercio. Las solicitudes sin un `merchantId` válido se rechazan.

**remark** `string`

Nota de texto libre adjunta a la orden para tu referencia.

#### Ejemplo de solicitud

```bash theme={null}
curl -X POST https://api.velafi.com/v2/order/crypto_to_fiat \
  -H "X-BH-TOKEN: YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "country": "Mexico",
    "clientId": "my-offramp-001",
    "merchantId": 3,
    "crypto": "USDT",
    "fiat": "MXN",
    "cryptoAmount": 1000.00,
    "userPaymentId": 91,
    "quoteId": "e46836d68a4a4a6f8f2f609352cffb2f",
    "remark": "Off-ramp for user #5678"
  }'
```

#### Ejemplo de respuesta

```json theme={null}
{
  "code": 200,
  "msg": "SUCCESS",
  "data": {
    "orderId": 1123123123
  }
}
```

Guarda el `orderId` devuelto: lo usarás para monitorear la orden mientras avanza por la validación, la conversión y el pago.

### El sistema procesa la conversión y la transferencia bancaria

Una vez aceptada la orden, VelaFi automáticamente:

1. **Carga la cripto**: toma el monto de cripto del saldo cripto del comercio al crear la orden. Si el saldo es insuficiente, la creación de la orden falla con un error de saldo insuficiente, a menos que el off-ramp con fondeo posterior esté habilitado para tu cuenta; en ese caso, la orden espera en `status: 32` (después de la revisión de cumplimiento, si la orden la requiere) hasta que el saldo la cubra o pase `orderExpireTimestamp`. Consulta [Fondeo de la orden](https://docs.velafi.com/es/api-reference/order/create-a-crypto-to-fiat-order.md#funding-the-order).
2. **Convierte a fiat**: cambia la cripto al tipo de cambio fijado o al tipo de cambio de mercado vigente.
3. **Inicia la transferencia bancaria**: envía el monto en fiat a la cuenta bancaria registrada del beneficiario mediante el canal de pago local (por ejemplo, SPEI para México, PIX para Brasil).

> [!NOTE]
>
> Para una orden en estado `50` (Pagada), [`POST /v2/order/confirm`](https://docs.velafi.com/es/api-reference/order/confirm-a-specific-order) con `orderType` establecido en `crypto_to_fiat` completa la orden (estado `60`).

### Monitorea el estado de la orden

Consulta periódicamente `GET /v2/order/detail` con el `orderId` y `orderType=crypto_to_fiat`, o configura un [webhook](https://docs.velafi.com/es/docs/guides/webhooks.md) para recibir notificaciones push en tiempo real en cada cambio de estado.

**Endpoint:** `GET /v2/order/detail?orderId={orderId}&orderType=crypto_to_fiat`

#### Ejemplo de solicitud

```bash theme={null}
curl -X GET "https://api.velafi.com/v2/order/detail?orderId=1123123123&orderType=crypto_to_fiat" \
  -H "X-BH-TOKEN: YOUR_TOKEN"
```

#### Ejemplo de respuesta

```json theme={null}
{
  "code": 200,
  "msg": "SUCCESS",
  "data": {
    "orderId": "1123123123",
    "clientId": "my-offramp-001",
    "merchantId": 3,
    "userPaymentId": 91,
    "country": "Mexico",
    "crypto": "USDT",
    "fiat": "MXN",
    "orderType": "crypto_to_fiat",
    "orderPrice": "21.4104",
    "cryptoAmount": "1000.0000",
    "fiatAmount": "21410.40",
    "fiatFee": "0",
    "orderStatus": 60,
    "traceNumber": "20241223907069062e51744c4f0e57",
    "paymentInfo": {
      "Cuenta CLABE": "000000000000000001"
    },
    "failCode": 0,
    "failReason": "",
    "createTime": "1740214865000",
    "completedTime": "1740215740000"
  }
}
```

#### Campos de la respuesta

**orderId** `string`

Identificador único de esta orden.

**clientId** `string`

Tu propio ID de referencia, devuelto tal como se envió en la solicitud de creación.

**merchantId** `number`

ID del comercio asociado a esta orden.

**userPaymentId** `number`

ID de la cuenta bancaria registrada del beneficiario que se usó para el pago en fiat.

**country** `string`

País donde se entrega el pago en fiat.

**crypto** `string`

Criptomoneda vendida por el usuario.

**fiat** `string`

Moneda fiat recibida por el usuario.

**orderType** `string`

Siempre es `crypto_to_fiat` para órdenes off-ramp.

**orderPrice** `string`

Tipo de cambio registrado al crear la orden.

**cryptoAmount** `string`

Monto de criptomoneda vendido.

**fiatAmount** `string`

Monto de moneda fiat entregado al beneficiario.

**fiatFee** `string`

Comisión cobrada en moneda fiat por esta orden.

**orderStatus** `number`

Código del estado actual. Consulta [Estados de la orden](https://docs.velafi.com/es/docs/order-statuses.md).

**traceNumber** `string`

Número de referencia del banco central nacional para el pago.

**paymentInfo** `object`

Datos de la cuenta bancaria usados para el pago. El contenido varía según el país y el método de pago.

**failCode** `integer`

Código de error registrado para una orden fallida. `0` cuando no hay un código de fallo registrado.

**failReason** `string`

Descripción legible del motivo por el que falló la orden.

**createTime** `string`

Marca de tiempo de creación de la orden en milisegundos (época Unix).

**completedTime** `string`

Marca de tiempo de finalización de la orden en milisegundos (época Unix).

#### Códigos de estado de la orden

| Estado | Etiqueta | Descripción |
| - | - | - |
| `10` | En revisión | La orden está en revisión de cumplimiento. |
| `11` | Solicitud de información | Se activó una RFI: se requieren documentos de soporte. |
| `12` | RFI cargada | Documentos cargados y en espera de aprobación de cumplimiento. |
| `30` | Aprobada | Orden en espera de la aceptación del usuario. |
| `31` | Documentos de soporte pendientes | Se deben enviar los documentos requeridos antes del procesamiento. |
| `32` | En espera de depósito de cripto | Orden con fondeo posterior en espera de que el saldo cripto del comercio la cubra. |
| `40` | Pago pendiente | Cripto cargada al saldo del comercio. |
| `50` | Pagada | Pago en fiat en curso. |
| `60` | Liberada | Orden completada: fiat entregado al beneficiario. |
| `70` | Cancelada | Orden cancelada (por ejemplo, por rechazo en la revisión o por tiempo de espera agotado). |
| `72` | Reembolsada | Cripto reembolsada al usuario. |
| `73` | En reembolso | Reembolso de cripto en curso. |

> [!WARNING]
>
> El `userPaymentId` debe hacer referencia a un beneficiario que ya esté registrado en tu cuenta de VelaFi. Intentar crear una orden con un `userPaymentId` desconocido producirá un error.


## Related topics

- [Introducción](https://docs.velafi.com/es/docs/introduction.md)
- [Documentación de la API de VelaFi](https://docs.velafi.com/es/index.md)
- [Inicio rápido](https://docs.velafi.com/es/docs/quickstart.md)
- [On-ramp (fiat a cripto)](https://docs.velafi.com/es/docs/guides/on-ramp.md)
- [Crear una orden de off-ramp](https://docs.velafi.com/es/api-reference/order/create-a-crypto-to-fiat-order.md)


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