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

# Crear una orden de off-ramp

> Crea una orden de off-ramp de cripto a fiat. La cripto se debita del saldo en cripto del comercio y el fiat local se paga a un beneficiario registrado.

El off-ramp de cripto a fiat permite a tus usuarios convertir criptomonedas en fiat local, que luego se paga al beneficiario identificado por `userPaymentId`. Antes de llamar a este endpoint, asegúrate de que el beneficiario de destino se haya registrado mediante `POST /v2/payments` y tenga `status: 1` (válido). Indica el monto en cripto (`cryptoAmount`) o en fiat (`fiatAmount`); si envías ambos, `fiatAmount` tiene prioridad. Para fijar el tipo de cambio, envía un `quoteId`; sin él, la orden se cotiza al tipo de cambio vigente al momento de crearla. La cripto se toma del saldo en cripto del comercio (consulta [Fondeo de la orden](#funding-the-order)).

## Endpoint

```text theme={null}
POST https://api.velafi.com/v2/order/crypto_to_fiat
```

> [!NOTE]
>
> Usa `https://api-test.velafi.com/v2/order/crypto_to_fiat` para pruebas en sandbox.

## Encabezados de la solicitud

| Encabezado | Valor |
| - | - |
| `X-BH-TOKEN` | Tu token de `GET /v2/token/generate` |
| `Content-Type` | `application/json` |

## Parámetros del cuerpo de la solicitud

**country** `string` *required*

Nombre completo del país del off-ramp (p. ej., `"Mexico"`, `"Argentina"`). Debe coincidir con el país asociado al `userPaymentId` elegido.

**crypto** `string` *required*

Símbolo de la criptomoneda que quieres convertir (p. ej., `"USDT"`, `"USDC"`).

**fiat** `string` *required*

Código ISO 4217 de la moneda fiat que recibirá el beneficiario (p. ej., `"MXN"`, `"ARS"`, `"BRL"`).

**userPaymentId** `integer` *required*

ID numérico del beneficiario (método de pago del usuario) que recibirá el pago en fiat. Obtenlo de `GET /v2/payments`.

**clientId** `string`

Tu propio ID de referencia de la orden, de hasta 40 caracteres. Debe ser único entre todas las órdenes `fiat_to_crypto` y `crypto_to_fiat` de tu cuenta; una segunda solicitud de creación con el mismo `clientId` se rechaza. Se devuelve en las respuestas de Consultar orden y puede usarse en lugar de `orderId` para buscar 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** `integer` *required*

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

**cryptoAmount** `decimal`

Monto de criptomoneda que quieres convertir (p. ej., `1000.00`). Se ignora cuando también se envía un `fiatAmount` positivo.

**fiatAmount** `decimal`

Monto en moneda fiat que debe recibir el beneficiario (p. ej., `21000.00`). Envía `fiatAmount` o `cryptoAmount`; si envías ambos, `fiatAmount` tiene prioridad.

**remark** `string`

Nota opcional de texto libre adjunta a la orden.

**quoteId** `string`

ID de cotización de la API de cotizaciones para fijar un tipo de cambio específico. Omítelo para usar el tipo de cambio spot en vivo.

## Campos de la respuesta

**code** `integer`

Código de estado de la respuesta. `200` indica éxito.

**msg** `string`

Mensaje de respuesta legible.

**data** `object`

Objeto con el resultado de la orden.

**campos de data**

**data.orderId** `integer`

ID numérico único de la orden creada. Úsalo para consultar el estado y los detalles de la orden.

## Ejemplo

```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-2024-001",
    "merchantId": 3,
    "crypto": "USDT",
    "fiat": "MXN",
    "cryptoAmount": 1000.00,
    "userPaymentId": 91,
    "remark": "Payout to supplier",
    "quoteId": "e46836d68a4a4a6f8f2f609352cffb2f"
  }'
```

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

## Fondeo de la orden

La cripto de una orden de off-ramp proviene del saldo en cripto del comercio para el `crypto` y el `merchantId` de la solicitud. Consulta el saldo con [Saldo en 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.

* **El saldo cubre la orden:** VelaFi debita la cripto del saldo al crear la orden.
* **El saldo es insuficiente:** la solicitud se rechaza con un error de saldo insuficiente, a menos que tu cuenta tenga habilitado el off-ramp con fondeo posterior (la habilitación puede variar según la moneda fiat).

> [!NOTE]
>
> Con el off-ramp con fondeo posterior habilitado, una orden sin fondos suficientes espera en `status: 32` (en espera del depósito de cripto). Si la orden primero necesita revisión de cumplimiento (`status: 10` u `11`), pasa a `32` una vez aprobada. Mientras está en `32`, el detalle de la orden devuelve `orderExpireTimestamp`, la fecha límite de fondeo como marca de tiempo Unix en segundos. VelaFi revisa el saldo del comercio cada minuto; cuando varias órdenes esperan sobre el mismo comercio y la misma cripto, el saldo se aplica a ellas de la más antigua a la más reciente. Cuando el saldo cubre una orden, VelaFi debita la cripto y la orden pasa a `status: 40`, o a `31` si se requieren documentos de soporte. Si la fecha límite vence antes, la orden se cancela (`status: 70`).

Para una orden `crypto_to_fiat` en `status: 50` (pagada), [`POST /v2/order/confirm`](https://docs.velafi.com/es/api-reference/order/confirm-a-specific-order) completa la orden (`status: 60`).

## Idempotencia y reintentos

Usa `clientId` para que la creación de órdenes se pueda reintentar de forma segura.

* `clientId` es opcional. Si lo envías, debe tener como máximo 40 caracteres y ser único en tu cuenta entre todas las órdenes `fiat_to_crypto` y `crypto_to_fiat`, para todos tus comercios.
* Una solicitud de creación que reutiliza un `clientId` existente se rechaza con un error de envío repetido, y no se crea una nueva orden. La respuesta no devuelve la orden original; búscala por separado.
* Un `clientId` queda asociado a su orden de forma permanente, incluso después de que la orden se cancela. Usa un `clientId` nuevo para cada orden nueva.
* Busca una orden por `clientId` con `GET /v2/order/detail?orderType=crypto_to_fiat&clientId={clientId}`.

Si una solicitud de creación agota el tiempo de espera o no devuelve respuesta:

1. Llama a `GET /v2/order/detail` con el mismo `orderType` y `clientId`.
2. Si encuentras la orden, la solicitud original fue exitosa. No la vuelvas a crear.
3. Si no la encuentras, reintenta con el mismo `clientId`. Si la primera solicitud sí creó la orden mientras tanto, el reintento se rechaza como duplicado en lugar de crear una segunda orden.

> [!NOTE]
>
> Un `quoteId` puede consumirse en una solicitud de creación que luego se rechaza. Solicita una nueva cotización antes de reintentar.


## Related topics

- [Listar beneficiarios](https://docs.velafi.com/es/api-reference/beneficiary/get-beneficiary.md)
- [Crear una orden de pago global](https://docs.velafi.com/es/api-reference/order/create-a-fiat-to-fiat-order.md)
- [Crear una orden de on-ramp](https://docs.velafi.com/es/api-reference/order/create-a-fiat-to-crypto-order.md)
- [Off-ramp (cripto a fiat)](https://docs.velafi.com/es/docs/guides/off-ramp.md)
- [Confirmar una orden](https://docs.velafi.com/es/api-reference/order/confirm-a-specific-order.md)


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