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

# 入金（法币兑加密货币）

> 使用 VelaFi 法币兑加密货币入金 API，接收用户的本地法币付款，并自动将加密货币发送到其钱包。

VelaFi 法币兑加密货币入金 (On-Ramp) 让您可以接收本地货币付款——例如 MXN、ARS、BRL 或 COP——并将等值的加密货币直接结算到用户的钱包。API 负责处理汇率报价、订单创建、付款指引下发和加密货币释放，让您可以专注于构建产品，而无需管理支付通道。

### 确认前提条件

在创建入金订单之前，请确保您已完成以下设置步骤：

* **商户账户已激活** — 您的商户记录必须存在，且其法币账户必须处于激活状态。
* **已准备好支付方式 ID** — 获取您要使用的入金支付方式的 `paymentId`（例如墨西哥的 SPEI、巴西的 PIX）。有关如何查询，请参阅[支付方式 ID 指南](https://docs.velafi.com/cn/docs/payment-methods.md)。
* **已获取 API 凭证** — 所有请求都需要携带 `X-BH-TOKEN` 请求头，其中包含通过 `GET /v2/token/generate` 获取的业务令牌。

### 获取报价（可选）

在下单之前请求实时汇率。`price` 表示每 1 单位加密货币对应的法币数量。设置 `createQuoteId=true` 时，响应中还会包含一个 `quoteId`，您可以在创建订单时传入以锁定该汇率。

**端点：** `GET /v2/user/crypto-quote`

**查询参数：**

**country** `string` *required*

法币付款来源国家的名称（例如 `"Mexico"`）。

**from** `string` *required*

兑换来源的法币代码（例如 `"MXN"`）。

**to** `string` *required*

兑换目标的加密货币（例如 `"USDT"`）。

**createQuoteId** `boolean`

设置为 `true` 可生成一个 `quoteId`，用于在下单时锁定报价。

**响应示例：**

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

> [!TIP]
>
> `quoteId` 在生产环境中的有效期为 **10 秒**（沙盒环境中为 300 秒），且默认只能使用一次。创建订单时请在 `quoteId` 字段中传入该值，以使用报价汇率。如果省略，订单将使用下单时的汇率。

### 创建入金订单

向 `/v2/order/fiat_to_crypto` 提交包含订单详情的 `POST` 请求。响应会返回一个 `orderId`，用于追踪订单。

**端点：** `POST /v2/order/fiat_to_crypto`

#### 请求参数

**country** `string` *required*

法币付款来源国家的名称（例如 `"Mexico"`）。

**crypto** `string` *required*

发送给用户的加密货币（例如 `"USDT"`）。

**fiat** `string` *required*

用户支付所用的法币（例如 `"MXN"`）。

**paymentId** `number` *required*

入金存款所用支付方式的 ID（例如 SPEI、PIX）。参见[支付方式 ID](https://docs.velafi.com/cn/docs/payment-methods.md)。

**fiatAmount** `decimal`

用户将支付的法币金额（例如 `1000.00`）。请提供 `fiatAmount` 或 `cryptoAmount` 其中之一。

**cryptoAmount** `decimal`

发送给用户的加密货币金额（例如 `50.00`）。请提供 `cryptoAmount` 或 `fiatAmount` 其中之一。

**clientId** `string`

您自定义的订单参考 ID，最多 40 个字符，在您所有的 `fiat_to_crypto` 和 `crypto_to_fiat` 订单中必须唯一。重复的 `clientId` 会被拒绝，因此您可以使用相同的值安全地重试创建请求。该值会在后续订单查询中原样返回。参见[幂等性与重试](https://docs.velafi.com/cn/api-reference/order/create-a-fiat-to-crypto-order.md#idempotency-and-retries)。

**merchantId** `number` *required*

订单所属商户的 ID。没有有效 `merchantId` 的请求将被拒绝。

**quoteId** `string`

由 `GET /v2/user/crypto-quote` 返回的报价 ID。传入此值可为该订单锁定报价汇率。

**depositAlias** `string`

如果您的设置使用虚拟账户路由，可指定要与此存款关联的虚拟账户别名。

**inFieldJson** `object`

某些支付方式所需的其他结构化字段。

**inFieldJson 字段**

**inFieldJson.bank** `enum`

使用哥伦比亚支付方式（例如 `paymentId=141`）时必填的银行代码。参见[哥伦比亚银行代码列表](https://docs.velafi.com/cn/api-reference/beneficiary/get-payment-templates.md#哥伦比亚银行代码)。

**remark** `string`

附加到订单的自由文本备注，供您参考。

#### 请求示例

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

#### 响应示例

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

请保存返回的 `orderId`——您将使用它获取付款指引并监控订单状态。

### 向指定账户付款

订单创建后，获取订单详情以取得付款指引（例如墨西哥的 CLABE 账号）。VelaFi 支持两种付款流程：

* **待处理资金余额付款** — 如果您的商户账户持有待处理资金 (Pending Fund) 余额，VelaFi 可以自动从中扣除法币金额，无需实时银行转账。
* **银行转账** — 用户（或您的系统）向 `paymentInfo` 中返回的收款账户信息发起银行转账。对于自动支付方式，VelaFi 的银行集成会将订单变更为 `status: 50`（已付款）。对于人工支付方式，请在转账发出后调用 [`POST /v2/order/confirm`](https://docs.velafi.com/cn/api-reference/order/confirm-a-specific-order)，并将 `orderType` 设置为 `fiat_to_crypto`，以将订单标记为已付款。

### 获取订单并监控状态

使用 `orderId` 和 `orderType=fiat_to_crypto` 轮询 `GET /v2/order/detail`，以查看订单的当前状态。

**端点：** `GET /v2/order/detail?orderId={orderId}&orderType=fiat_to_crypto`

#### 请求示例

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

#### 响应示例

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

#### 响应字段

**orderId** `string`

此订单的唯一标识符。

**clientId** `string`

您自定义的参考 ID，从创建请求中原样返回。

**merchantId** `number`

与此订单关联的商户 ID。

**paymentId** `number`

法币存款所用支付方式的 ID。

**country** `string`

法币付款的来源国家。

**crypto** `string`

发送的加密货币。

**fiat** `string`

用户支付的法币。

**orderType** `string`

入金订单始终为 `fiat_to_crypto`。

**orderPrice** `string`

订单创建时锁定的汇率。

**cryptoAmount** `string`

将发送给用户的加密货币金额。

**fiatAmount** `string`

用户支付的法币金额。

**fiatFee** `string`

此订单以法币收取的手续费。

**orderStatus** `number`

当前状态码。参见[订单状态](https://docs.velafi.com/cn/docs/order-statuses.md)。

**traceNumber** `string`

该交易的国家中央银行参考编号。

**paymentInfo** `object`

给用户的付款指引（例如银行账户信息）。内容因国家和支付方式而异。

**failCode** `integer`

失败订单记录的错误码。未记录失败代码时为 `0`。

**failReason** `string`

订单失败原因的人类可读描述。

**createTime** `string`

订单创建时间戳，以毫秒为单位（Unix 纪元）。

**completedTime** `string`

订单完成时间戳，以毫秒为单位（Unix 纪元）。

#### 订单状态码

入金订单使用出入金 (ramp) 状态码。完整表格（包括哪些状态码表示订单终结）请参见[订单状态](https://docs.velafi.com/cn/docs/order-statuses.md)。

### 订单完成——加密货币已发送

当 `orderStatus` 变为 `60`（已完成）时，订单即完成。您也可以[订阅 Webhook](https://docs.velafi.com/cn/docs/guides/webhooks.md)，在每次状态变更时接收实时推送通知，而无需轮询。

> [!NOTE]
>
> 请确保您提供的 `paymentId` 和 `merchantId` 对应于您 VelaFi 账户中已激活且已配置的记录。


## Related topics

- [获取法币→加密货币交易对](https://docs.velafi.com/cn/api-reference/basic-configuration/get-fiat-crypto-pairs.md)
- [获取法币→加密货币支付方式](https://docs.velafi.com/cn/api-reference/basic-configuration/get-fiat-crypto-payment-methods.md)
- [获取加密货币/法币报价](https://docs.velafi.com/cn/api-reference/quote/get-user-quote-for-crypto-fiat.md)
- [获取订单](https://docs.velafi.com/cn/api-reference/order/retrieve-a-specific-order.md)
- [出金（加密货币兑法币）](https://docs.velafi.com/cn/docs/guides/off-ramp.md)


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