> ## 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 加密货币到法币出金 (Off-Ramp) 功能会将你商户加密资产余额中的加密货币兑换为本地法币——例如 MXN、ARS、BRL 或 COP——并直接存入用户的银行账户。API 负责汇率报价、从商户余额中扣除加密货币、兑换以及发起银行转账，让你无需自行管理本地支付基础设施即可提供顺畅的提现流程。

### 确认前提条件

创建出金订单前，请确保已完成以下设置：

* **商户账户已激活** — 你的商户记录必须存在，且其法币账户必须已针对出金方向激活。
* **已添加收款人** — 用户的银行账户必须已在你的 VelaFi 账户中登记为收款人。创建出金订单需要收款人记录的 `userPaymentId`。有关登记步骤，请参见[创建收款人](https://docs.velafi.com/cn/docs/guides/managing-beneficiaries.md)。
* **加密资产余额已注资** — 订单所需的加密货币从商户的加密资产余额中扣除。可通过[加密资产余额](https://docs.velafi.com/cn/api-reference/merchant/get-crypto-assets-balance.md)查询余额，并通过商户的[充值地址](https://docs.velafi.com/cn/api-reference/merchant/get-crypto-deposit-address.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*

卖出的加密货币（例如 `"USDT"`）。

**to** `string` *required*

接收的法币（例如 `"MXN"`）。

**createQuoteId** `boolean`

设置为 `true` 可生成 `quoteId`，在创建订单时传入即可锁定报价价格。

**响应示例：**

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

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

### 创建出金订单

向 `/v2/order/crypto_to_fiat` 提交 `POST` 请求。VelaFi 从商户的加密资产余额中扣除加密货币，按约定汇率兑换，并将法币支付到收款人账户。响应会返回用于跟踪的 `orderId`。

**接口：** `POST /v2/order/crypto_to_fiat`

#### 请求参数

**country** `string` *required*

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

**crypto** `string` *required*

用户卖出的加密货币（例如 `"USDT"`）。

**fiat** `string` *required*

用户将收到的法币（例如 `"MXN"`）。

**userPaymentId** `number` *required*

收款人已登记银行账户的 ID（在添加收款人时返回）。参见[获取收款人](https://docs.velafi.com/cn/api-reference/beneficiary/get-beneficiary.md)。

**cryptoAmount** `decimal`

要卖出的加密货币数量（例如 `1000.00`）。请提供 `cryptoAmount` 或 `fiatAmount` 其中之一。

**fiatAmount** `decimal`

用户应收到的目标法币金额（例如 `21410.40`）。请提供 `fiatAmount` 或 `cryptoAmount` 其中之一。

**quoteId** `string`

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

**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` 的请求将被拒绝。

**remark** `string`

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

#### 请求示例

```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-001",
    "merchantId": 3,
    "crypto": "USDT",
    "fiat": "MXN",
    "cryptoAmount": 1000.00,
    "userPaymentId": 91,
    "quoteId": "e46836d68a4a4a6f8f2f609352cffb2f",
    "remark": "Off-ramp for user #5678"
  }'
```

#### 响应示例

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

请保存返回的 `orderId`——在订单经历校验、兑换和付款的过程中，你将使用它来监控订单。

### 系统处理兑换和银行转账

订单被接受后，VelaFi 会自动：

1. **扣除加密货币** — 在创建订单时从商户的加密资产余额中扣除相应数量的加密货币。如果余额不足，订单创建将失败并返回余额不足错误，除非你的账户已开通后注资出金；此时订单会停留在 `status: 32`（如需合规审核，则在审核之后），直到余额足以覆盖订单或超过 `orderExpireTimestamp`。参见[为订单注资](https://docs.velafi.com/cn/api-reference/order/create-a-crypto-to-fiat-order.md#funding-the-order)。
2. **兑换为法币** — 按锁定汇率或当前市场汇率兑换加密货币。
3. **发起银行转账** — 通过本地支付通道（例如墨西哥的 SPEI、巴西的 PIX）将法币金额发送到收款人已登记的银行账户。

> [!NOTE]
>
> 对于状态为 `50`（已支付）的订单，调用 [`POST /v2/order/confirm`](https://docs.velafi.com/cn/api-reference/order/confirm-a-specific-order) 并将 `orderType` 设置为 `crypto_to_fiat`，即可完成订单（状态 `60`）。

### 监控订单状态

使用 `orderId` 和 `orderType=crypto_to_fiat` 轮询 `GET /v2/order/detail`，或配置 [Webhook](https://docs.velafi.com/cn/docs/guides/webhooks.md) 以在每次状态变更时接收实时推送通知。

**接口：** `GET /v2/order/detail?orderId={orderId}&orderType=crypto_to_fiat`

#### 请求示例

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

#### 响应示例

```json theme={null}
{
  "code": 200,
  "msg": "SUCCESS",
  "data": {
    "orderId": "1123123123",
    "clientId": "my-offramp-001",
    "merchantId": 3,
    "userPaymentId": 91,
    "country": "Mexico",
    "crypto": "USDT",
    "fiat": "MXN",
    "orderType": "crypto_to_fiat",
    "orderPrice": "21.4104",
    "cryptoAmount": "1000.0000",
    "fiatAmount": "21410.40",
    "fiatFee": "0",
    "orderStatus": 60,
    "traceNumber": "20241223907069062e51744c4f0e57",
    "paymentInfo": {
      "Cuenta CLABE": "000000000000000001"
    },
    "failCode": 0,
    "failReason": "",
    "createTime": "1740214865000",
    "completedTime": "1740215740000"
  }
}
```

#### 响应字段

**orderId** `string`

该订单的唯一标识符。

**clientId** `string`

你自己的参考 ID，从创建请求中原样返回。

**merchantId** `number`

与该订单关联的商户 ID。

**userPaymentId** `number`

用于法币付款的收款人已登记银行账户的 ID。

**country** `string`

法币付款到账的国家。

**crypto** `string`

用户卖出的加密货币。

**fiat** `string`

用户收到的法币。

**orderType** `string`

出金订单始终为 `crypto_to_fiat`。

**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 纪元）。

#### 订单状态码

| 状态 | 标签 | 说明 |
| - | - | - |
| `10` | 审核中 | 订单正在进行合规审核。 |
| `11` | 需要补充信息 | 触发 RFI——需要提供证明文件。 |
| `12` | RFI 已上传 | 文件已上传，等待合规审批。 |
| `30` | 已批准 | 订单等待用户接受。 |
| `31` | 待提交证明文件 | 必须提交所需文件后才能处理。 |
| `32` | 等待加密货币充值 | 后注资订单正在等待商户的加密资产余额足以覆盖。 |
| `40` | 待付款 | 已从商户余额中扣除加密货币。 |
| `50` | 已支付 | 法币付款处理中。 |
| `60` | 已放款 | 订单完成——法币已支付给收款人。 |
| `70` | 已取消 | 订单已取消（例如审核被拒或超时）。 |
| `72` | 已退款 | 加密货币已退还给用户。 |
| `73` | 退款中 | 加密货币退款处理中。 |

> [!WARNING]
>
> `userPaymentId` 必须指向已在你的 VelaFi 账户中登记的收款人。使用未知的 `userPaymentId` 创建订单将导致错误。


## Related topics

- [获取加密货币→法币交易对](https://docs.velafi.com/cn/api-reference/basic-configuration/get-crypto-fiat-pairs.md)
- [获取加密货币→法币支付方式](https://docs.velafi.com/cn/api-reference/basic-configuration/get-crypto-fiat-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/on-ramp.md)


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