> ## 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 on-ramp

> Crea una orden on-ramp de fiat a cripto. Un usuario paga en moneda fiat local y recibe criptomoneda en su billetera al tipo de cambio vigente.

El on-ramp de fiat a cripto convierte moneda fiat local en criptomoneda para tu usuario. Especifica la moneda fiat de origen, la cripto de destino y el método de pago mediante `paymentId`. Fija el monto de la orden en fiat (`fiatAmount`) o en cripto (`cryptoAmount`); si envías ambos, `fiatAmount` tiene prioridad. Para fijar el tipo de cambio, envía un `quoteId` de la API de cotizaciones; sin él, la orden se valúa al tipo de cambio vigente al momento de crearla. La respuesta devuelve un `orderId` que puedes usar para dar seguimiento a la orden durante todo su ciclo de vida mediante los endpoints Obtener orden y Listar órdenes.

## Endpoint

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

> [!NOTE]
>
> Usa `https://api-test.velafi.com/v2/order/fiat_to_crypto` para hacer pruebas en el 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 on-ramp (por ejemplo, `"Mexico"`, `"Brazil"`). Debe coincidir con el país admitido por el `paymentId` elegido.

**crypto** `string` *required*

Símbolo (ticker) de la criptomoneda de destino (por ejemplo, `"USDT"`, `"USDC"`, `"BTC"`).

**fiat** `string` *required*

Código ISO 4217 de la moneda fiat con la que paga el usuario (por ejemplo, `"MXN"`, `"BRL"`, `"COP"`).

**paymentId** `integer` *required*

ID numérico del método de pago usado para el depósito en fiat. Consulta la tabla de IDs de métodos de pago en la referencia de plantillas de pago.

**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 Obtener orden y se puede usar en lugar de `orderId` para buscar la orden. Consulta [Idempotencia y reintentos](#idempotency-and-retries).

**merchantId** `integer` *required*

ID numérico del comercio al que pertenece la orden. Las solicitudes sin un `merchantId` válido se rechazan.

**fiatAmount** `decimal`

Monto de moneda fiat que paga el usuario (por ejemplo, `1000.00`). Envía `fiatAmount` o `cryptoAmount`; si envías ambos, `fiatAmount` tiene prioridad.

**cryptoAmount** `decimal`

Monto de criptomoneda que recibe el usuario (por ejemplo, `46.73`). Se ignora cuando también se envía un `fiatAmount` positivo.

**remark** `string`

Nota opcional de texto libre adjunta a la orden.

**depositAlias** `string`

Alias de la cuenta virtual que se usará para el depósito en fiat. Obligatorio para los métodos de pago basados en cuentas virtuales.

**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 tiempo real.

**inFieldJson** `object`

Campos adicionales específicos del pago, requeridos por ciertos métodos de pago.

**Campos de inFieldJson**

**inFieldJson.bank** `string`

Código del banco del pagador, obligatorio cuando `paymentId` es `141` (PSE). PSE usa su propia lista de bancos, que no es la misma que la tabla de [Códigos de bancos de Colombia](https://docs.velafi.com/es/api-reference/beneficiary/get-payment-templates.md#colombian-bank-codes) que se usa para los beneficiarios.

**Códigos de bancos de PSE**

| Código | Banco |
| - | - |
| 1001 | BANCO DE BOGOTA |
| 1002 | BANCO POPULAR |
| 1006 | ITAU |
| 1007 | BANCOLOMBIA |
| 1009 | CITIBANK |
| 1012 | BANCO GNB SUDAMERIS |
| 1013 | BBVA COLOMBIA |
| 1019 | DAVIBANK |
| 1023 | BANCO DE OCCIDENTE |
| 1032 | BANCO CAJA SOCIAL BCSC SA |
| 1040 | BANCO AGRARIO |
| 1047 | BANCO MUNDO MUJER |
| 1051 | BANCO DAVIVIENDA SA |
| 1052 | BANCO AV VILLAS |
| 1059 | BANCO DE LAS MICROFINANZAS - BANCAMIA S.A. |
| 1060 | BANCO PICHINCHA |
| 1061 | BANCOOMEVA |
| 1062 | BANCO FALABELLA S.A. |
| 1063 | BANCO FINANDINA S.A. |
| 1065 | BANCO SANTANDER DE NEGOCIOS COLOMBIA S.A |
| 1066 | BANCO COOPERATIVO COOPCENTRAL |
| 1069 | BANCO SERFINANZA S.A |
| 1070 | LULO BANK S.A. |
| 1071 | BANCO J.P. MORGAN COLOMBIA S.A. |
| 1097 | Dale |
| 1121 | FINANCIERA JURISCOOP S.A. COMPAÑIA DE FINANCIAMIENTO |
| 1283 | COOPERATIVA FINANCIERA DE ANTIOQUIA |
| 1286 | JFK COOPERATIVA FINANCIERA |
| 1289 | COOTRAFA COOPERATIVA FINANCIERA |
| 1292 | CONFIAR COOPERATIVA FINANCIERA |
| 1303 | BANCO UNION S.A |
| 1370 | COLTEFINANCIERA S.A |
| 1507 | NEQUI |
| 1551 | DAVIPLATA |
| 1558 | BAN100 S.A |
| 1637 | IRIS |
| 1801 | MOVII |
| 1802 | DING TECNIPAGOS SA |
| 1804 | UALA |
| 1808 | BOLD CF |
| 1809 | NU COLOMBIA |
| 1811 | RAPPIPAY |
| 1812 | COINK |
| 1814 | GLOBAL66 |
| 1815 | Alianza fiduciaria |
| 1816 | Crezcamos |

## 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 obtener el estado y los detalles de la orden.

## Ejemplo

```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": "Colombia",
    "clientId": "my-order-2024-001",
    "merchantId": 3,
    "crypto": "USDT",
    "fiat": "COP",
    "fiatAmount": 100000.00,
    "paymentId": 141,
    "remark": "On-ramp for user #42",
    "quoteId": "e46836d68a4a4a6f8f2f609352cffb2f",
    "inFieldJson": {
      "bank": "1001"
    }
  }'
```

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

> [!TIP]
>
> Después de crear la orden, consulta periódicamente `GET /v2/order/detail?orderId={orderId}&orderType=fiat_to_crypto` para monitorear su estado. Una orden nueva inicia en `status: 40` (pago pendiente), o en `10`, `11` o `31` cuando se requiere revisión de cumplimiento o documentos de soporte. Las órdenes con métodos de pago automáticos pasan a `status: 50` (pagada) mediante la integración bancaria de VelaFi. Para los métodos de pago manuales, llama a [`POST /v2/order/confirm`](https://docs.velafi.com/es/api-reference/order/confirm-a-specific-order) después de enviar la transferencia para marcar la orden como pagada.

## Idempotencia y reintentos

Usa `clientId` para que la creación de órdenes se pueda reintentar con seguridad.

* `clientId` es opcional. Cuando 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 ninguna orden nueva. La respuesta no devuelve la orden original; búscala por separado.
* Un `clientId` queda vinculado a su orden de forma permanente, incluso después de que la orden se cancela. Usa un `clientId` nuevo para una orden nueva.
* Busca una orden por `clientId` con `GET /v2/order/detail?orderType=fiat_to_crypto&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` se puede consumir en una solicitud de creación que luego se rechaza. Solicita una cotización nueva antes de reintentar.


## Related topics

- [On-ramp (fiat a cripto)](https://docs.velafi.com/es/docs/guides/on-ramp.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 off-ramp](https://docs.velafi.com/es/api-reference/order/create-a-crypto-to-fiat-order.md)
- [Confirmar una orden](https://docs.velafi.com/es/api-reference/order/confirm-a-specific-order.md)
- [Evento de retiro de on-ramp](https://docs.velafi.com/es/api-reference/webhooks/on-ramp-withdraw-message-push.md)


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