> ## 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 to Crypto)

> Accept local fiat payments from your users and automatically deliver crypto to their wallets using the VelaFi fiat-to-crypto on-ramp API.

The VelaFi fiat-to-crypto on-ramp lets you accept local currency payments — such as MXN, ARS, BRL, or COP — and settle the equivalent cryptocurrency directly to your user's wallet. The API handles exchange rate quoting, order creation, payment instruction delivery, and crypto release, so you can focus on building your product rather than managing payment rails.

### Confirm prerequisites

Before creating an on-ramp order, make sure you have completed the following setup steps:

* **Merchant account activated** — your merchant record must exist and its fiat account must be in an active state.
* **Payment method ID ready** — obtain the `paymentId` for the on-ramp payment method you want to use (e.g., SPEI for Mexico, PIX for Brazil). Refer to the [Payment Method ID guide](https://docs.velafi.com/docs/payment-methods.md) for how to look these up.
* **API credentials available** — all requests require the `X-BH-TOKEN` header containing a business token from `GET /v2/token/generate`.

### Get a quote (optional)

Request a real-time exchange rate before placing the order. The `price` is in units of fiat per 1 unit of crypto. With `createQuoteId=true`, the response also includes a `quoteId` you can pass when creating the order to guarantee that rate.

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

**Query parameters:**

**country** `string` *required*

Name of the country where the fiat payment originates (e.g., `"Mexico"`).

**from** `string` *required*

The fiat currency code to convert from (e.g., `"MXN"`).

**to** `string` *required*

The cryptocurrency to convert to (e.g., `"USDT"`).

**createQuoteId** `boolean`

Set to `true` to generate a `quoteId` that you can use to lock the quoted price when placing an order.

**Example response:**

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

> [!TIP]
>
> The `quoteId` is valid for **10 seconds** in production (300 seconds in the sandbox) and is single-use by default. Pass it in the `quoteId` field when you create the order to honour the quoted rate. If you omit it, the order uses the rate at the time of placement.

### Create the on-ramp order

Submit a `POST` request to `/v2/order/fiat_to_crypto` with the order details. The response returns an `orderId` you use to track the order.

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

#### Request parameters

**country** `string` *required*

Name of the country where the fiat payment originates (e.g., `"Mexico"`).

**crypto** `string` *required*

Cryptocurrency to deliver to the user (e.g., `"USDT"`).

**fiat** `string` *required*

Fiat currency the user pays in (e.g., `"MXN"`).

**paymentId** `number` *required*

ID of the payment method for the on-ramp deposit (e.g., SPEI, PIX). See [Payment Method IDs](https://docs.velafi.com/docs/payment-methods.md).

**fiatAmount** `decimal`

Amount of fiat currency the user will pay (e.g., `1000.00`). Provide either `fiatAmount` or `cryptoAmount`.

**cryptoAmount** `decimal`

Amount of crypto to deliver to the user (e.g., `50.00`). Provide either `cryptoAmount` or `fiatAmount`.

**clientId** `string`

Your own order reference ID, up to 40 characters, unique across all your `fiat_to_crypto` and `crypto_to_fiat` orders. A repeated `clientId` is rejected, so you can safely retry a create request with the same value. Returned as-is in subsequent order queries. See [Idempotency and retries](https://docs.velafi.com/api-reference/order/create-a-fiat-to-crypto-order.md#idempotency-and-retries).

**merchantId** `number` *required*

ID of the merchant the order belongs to. Requests without a valid `merchantId` are rejected.

**quoteId** `string`

Quote ID returned by `GET /v2/user/crypto-quote`. Pass this to lock the quoted exchange rate for this order.

**depositAlias** `string`

Alias of a virtual account to associate with this deposit, if your setup uses virtual account routing.

**inFieldJson** `object`

Additional structured fields required by certain payment methods.

**inFieldJson fields**

**inFieldJson.bank** `enum`

Bank code required when using Colombian payment methods (e.g., `paymentId=141`). See the [Colombian bank codes list](https://docs.velafi.com/api-reference/beneficiary/get-payment-templates.md#colombian-bank-codes-1).

**remark** `string`

Free-text note attached to the order for your reference.

#### Example request

```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"
  }'
```

#### Example response

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

Store the returned `orderId` — you will use it to retrieve payment instructions and monitor order status.

### Send payment to the designated account

After the order is created, retrieve the order details to get the payment instructions (e.g., CLABE account number for Mexico). VelaFi supports two payment flows:

* **Pending Fund balance payment** — if your merchant account holds a Pending Fund balance, VelaFi can deduct the fiat amount from it automatically without requiring a real-time bank transfer.
* **Bank transfer** — the user (or your system) sends a bank transfer to the payment account details returned in `paymentInfo`. On automatic payment methods, VelaFi's bank integration moves the order to `status: 50` (paid). On manual payment methods, call [`POST /v2/order/confirm`](https://docs.velafi.com/api-reference/order/confirm-a-specific-order) with `orderType` set to `fiat_to_crypto` after the transfer is sent, to mark the order as paid.

### Retrieve the order and monitor status

Poll `GET /v2/order/detail` with the `orderId` and `orderType=fiat_to_crypto` to check the current state of the order.

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

#### Example request

```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"
```

#### Example response

```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"
  }
}
```

#### Response fields

**orderId** `string`

Unique identifier for this order.

**clientId** `string`

Your own reference ID, echoed back from the create request.

**merchantId** `number`

ID of the merchant associated with this order.

**paymentId** `number`

ID of the payment method used for the fiat deposit.

**country** `string`

Country where the fiat payment originates.

**crypto** `string`

Cryptocurrency being delivered.

**fiat** `string`

Fiat currency paid by the user.

**orderType** `string`

Always `fiat_to_crypto` for on-ramp orders.

**orderPrice** `string`

Exchange rate captured at the time the order was created.

**cryptoAmount** `string`

Amount of crypto to be delivered to the user.

**fiatAmount** `string`

Amount of fiat currency paid by the user.

**fiatFee** `string`

Fee charged in fiat currency for this order.

**orderStatus** `number`

Current status code. See [Order Statuses](https://docs.velafi.com/docs/order-statuses.md).

**traceNumber** `string`

National central bank reference number for the transaction.

**paymentInfo** `object`

Payment instructions for the user (e.g., bank account details). Contents vary by country and payment method.

**failCode** `integer`

Error code recorded for a failed order. `0` when no failure code is recorded.

**failReason** `string`

Human-readable description of why the order failed.

**createTime** `string`

Order creation timestamp in milliseconds (Unix epoch).

**completedTime** `string`

Order completion timestamp in milliseconds (Unix epoch).

#### Order status codes

On-ramp orders use the ramp status codes. See [Order Statuses](https://docs.velafi.com/docs/order-statuses.md) for the full table, including which codes end an order.

### Order complete — crypto delivered

Once `orderStatus` reaches `60` (completed), the order is complete. You can also [subscribe to webhooks](https://docs.velafi.com/docs/guides/webhooks.md) to receive real-time push notifications on every status change instead of polling.

> [!NOTE]
>
> Make sure the `paymentId` and `merchantId` you supply correspond to active, configured records in your VelaFi account.


## Related topics

- [Get a Crypto/Fiat Quote](https://docs.velafi.com/api-reference/quote/get-user-quote-for-crypto-fiat.md)
- [Confirm an Order](https://docs.velafi.com/api-reference/order/confirm-a-specific-order.md)
- [Introduction](https://docs.velafi.com/docs/introduction.md)
- [Off-Ramp (Crypto to Fiat)](https://docs.velafi.com/docs/guides/off-ramp.md)
- [Order Statuses](https://docs.velafi.com/docs/order-statuses.md)


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