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

# On-ramp (fiat a cripto)

> Acepta pagos en fiat local de tus usuarios y entrega cripto automáticamente a sus billeteras con la API de on-ramp fiat a cripto de VelaFi.

El on-ramp fiat a cripto de VelaFi te permite aceptar pagos en moneda local, como MXN, ARS, BRL o COP, y liquidar el equivalente en criptomoneda directamente en la billetera de tu usuario. La API se encarga de cotizar el tipo de cambio, crear la orden, entregar las instrucciones de pago y liberar la cripto, para que te concentres en construir tu producto en lugar de administrar canales de pago.

### Confirma los requisitos previos

Antes de crear una orden de on-ramp, asegúrate de haber completado los siguientes pasos de configuración:

* **Cuenta del comercio activada**: tu registro de comercio debe existir y su cuenta fiat debe estar activa.
* **ID del método de pago listo**: obtén el `paymentId` del método de pago de on-ramp que quieres usar (p. ej., SPEI para México, PIX para Brasil). Consulta la [guía de IDs de métodos de pago](https://docs.velafi.com/es/docs/payment-methods.md) para saber cómo obtenerlos.
* **Credenciales de API disponibles**: todas las solicitudes requieren el header `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 puedes enviar al crear la orden para garantizar ese tipo de cambio.

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

**Parámetros de consulta:**

**country** `string` *required*

Nombre del país donde se origina el pago fiat (p. ej., `"Mexico"`).

**from** `string` *required*

Código de la moneda fiat de origen (p. ej., `"MXN"`).

**to** `string` *required*

Criptomoneda de destino (p. ej., `"USDT"`).

**createQuoteId** `boolean`

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

**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, por defecto, es de un solo uso. Envíalo en el campo `quoteId` al crear la orden para respetar el tipo de cambio cotizado. Si lo omites, la orden usa el tipo de cambio vigente al momento de crearla.

### Crea la orden de on-ramp

Envía una solicitud `POST` a `/v2/order/fiat_to_crypto` con los datos de la orden. La respuesta devuelve un `orderId` que usas para dar seguimiento a la orden.

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

#### Parámetros de la solicitud

**country** `string` *required*

Nombre del país donde se origina el pago fiat (p. ej., `"Mexico"`).

**crypto** `string` *required*

Criptomoneda que se entregará al usuario (p. ej., `"USDT"`).

**fiat** `string` *required*

Moneda fiat con la que paga el usuario (p. ej., `"MXN"`).

**paymentId** `number` *required*

ID del método de pago para el depósito de on-ramp (p. ej., SPEI, PIX). Consulta [IDs de métodos de pago](https://docs.velafi.com/es/docs/payment-methods.md).

**fiatAmount** `decimal`

Monto en moneda fiat que pagará el usuario (p. ej., `1000.00`). Envía `fiatAmount` o `cryptoAmount`.

**cryptoAmount** `decimal`

Monto de cripto que se entregará al usuario (p. ej., `50.00`). Envía `cryptoAmount` o `fiatAmount`.

**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 de forma segura una solicitud de creación con el mismo valor. Se devuelve sin cambios 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. Las solicitudes sin un `merchantId` válido se rechazan.

**quoteId** `string`

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

**depositAlias** `string`

Alias de una cuenta virtual que se asociará con este depósito, si tu configuración usa enrutamiento por cuentas virtuales.

**inFieldJson** `object`

Campos estructurados adicionales que requieren ciertos métodos de pago.

**Campos de inFieldJson**

**inFieldJson.bank** `enum`

Código de banco obligatorio al usar métodos de pago de Colombia (p. ej., `paymentId=141`). Consulta la [lista de códigos de bancos de Colombia](https://docs.velafi.com/es/api-reference/beneficiary/get-payment-templates.md#colombian-bank-codes).

**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/fiat_to_crypto \
  -H "X-BH-TOKEN: YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "country": "Mexico",
    "clientId": "my-order-001",
    "merchantId": 3,
    "crypto": "USDT",
    "fiat": "MXN",
    "fiatAmount": 1000.00,
    "paymentId": 105,
    "quoteId": "e46836d68a4a4a6f8f2f609352cffb2f",
    "remark": "On-ramp for user #1234"
  }'
```

#### Ejemplo de respuesta

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

Guarda el `orderId` devuelto: lo usarás para obtener las instrucciones de pago y monitorear el estado de la orden.

### Envía el pago a la cuenta designada

Después de crear la orden, consulta los detalles de la orden para obtener las instrucciones de pago (p. ej., el número de cuenta CLABE en México). VelaFi admite dos flujos de pago:

* **Pago con saldo de Pending Fund**: si la cuenta de tu comercio tiene saldo en la cuenta Pending Fund (fondos pendientes), VelaFi puede descontar automáticamente el monto en fiat de ese saldo sin necesidad de una transferencia bancaria en tiempo real.
* **Transferencia bancaria**: el usuario (o tu sistema) envía una transferencia bancaria a los datos de la cuenta de pago devueltos en `paymentInfo`. En los métodos de pago automáticos, la integración bancaria de VelaFi mueve la orden a `status: 50` (pagada). En los métodos de pago manuales, llama a [`POST /v2/order/confirm`](https://docs.velafi.com/es/api-reference/order/confirm-a-specific-order) con `orderType` establecido en `fiat_to_crypto` después de enviar la transferencia, para marcar la orden como pagada.

### Consulta la orden y monitorea su estado

Consulta periódicamente `GET /v2/order/detail` con el `orderId` y `orderType=fiat_to_crypto` para revisar el estado actual de la orden.

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

#### Ejemplo de solicitud

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

#### Ejemplo de respuesta

```json theme={null}
{
  "code": 200,
  "msg": "SUCCESS",
  "data": {
    "orderId": "493829236956962816",
    "clientId": "my-order-001",
    "merchantId": 3,
    "paymentId": 105,
          "country": "Mexico",
    "crypto": "USDT",
    "fiat": "MXN",
    "orderType": "fiat_to_crypto",
    "orderPrice": "21.4104",
    "cryptoAmount": "5.1376",
    "fiatAmount": "110",
    "fiatFee": "0",
    "orderStatus": 60,
    "traceNumber": "20241223907069062e51744c4f0e57",
    "paymentInfo": {
      "Cuenta CLABE": "000000000000000001"
    },
    "failCode": 0,
    "failReason": "",
    "createTime": "1740214865000",
    "completedTime": "1740214866000"
  }
}
```

#### Campos de la respuesta

**orderId** `string`

Identificador único de esta orden.

**clientId** `string`

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

**merchantId** `number`

ID del comercio asociado a esta orden.

**paymentId** `number`

ID del método de pago usado para el depósito fiat.

**country** `string`

País donde se origina el pago fiat.

**crypto** `string`

Criptomoneda que se entrega.

**fiat** `string`

Moneda fiat pagada por el usuario.

**orderType** `string`

Siempre `fiat_to_crypto` para órdenes de on-ramp.

**orderPrice** `string`

Tipo de cambio registrado al momento de crear la orden.

**cryptoAmount** `string`

Monto de cripto que se entregará al usuario.

**fiatAmount** `string`

Monto en moneda fiat pagado por el usuario.

**fiatFee** `string`

Comisión cobrada en moneda fiat por esta orden.

**orderStatus** `number`

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

**traceNumber** `string`

Número de referencia del banco central nacional para la transacción.

**paymentInfo** `object`

Instrucciones de pago para el usuario (p. ej., datos de la cuenta bancaria). 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 código de falla 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 (Unix epoch).

**completedTime** `string`

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

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

Las órdenes de on-ramp usan los códigos de estado de ramp. Consulta [Estados de las órdenes](https://docs.velafi.com/es/docs/order-statuses.md) para ver la tabla completa, incluidos los códigos que finalizan una orden.

### Orden completada: cripto entregada

Cuando `orderStatus` llega a `60` (completada), la orden está completa. También puedes [suscribirte a webhooks](https://docs.velafi.com/es/docs/guides/webhooks.md) para recibir notificaciones push en tiempo real en cada cambio de estado en lugar de consultar periódicamente.

> [!NOTE]
>
> Asegúrate de que el `paymentId` y el `merchantId` que envías correspondan a registros activos y configurados en tu cuenta de VelaFi.


## Related topics

- [Listar métodos de pago fiat→cripto](https://docs.velafi.com/es/api-reference/basic-configuration/get-fiat-crypto-payment-methods.md)
- [Introducción](https://docs.velafi.com/es/docs/introduction.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)
- [Crear una orden de on-ramp](https://docs.velafi.com/es/api-reference/order/create-a-fiat-to-crypto-order.md)


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