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

# 创建出金订单

> 创建加密货币到法币的出金订单。加密货币从商户的加密资产余额中扣除，本地法币将支付给已登记的收款人。

加密货币到法币的出金 (Off-Ramp) 功能让你的用户可以将加密货币兑换为本地法币，然后支付给由 `userPaymentId` 标识的收款人。调用此接口前，请确保目标收款人已通过 `POST /v2/payments` 登记，且 `status: 1`（有效）。金额可以用加密货币（`cryptoAmount`）或法币（`fiatAmount`）指定；如果同时发送，则以 `fiatAmount` 为准。如需锁定汇率，请传入 `quoteId`；否则订单将按创建时的当前汇率定价。加密货币从商户的加密资产余额中扣除（参见[为订单注资](#funding-the-order)）。

## 接口地址

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

> [!NOTE]
>
> 在沙盒环境中测试时，请使用 `https://api-test.velafi.com/v2/order/crypto_to_fiat`。

## 请求头

| 请求头 | 值 |
| - | - |
| `X-BH-TOKEN` | 通过 `GET /v2/token/generate` 获取的令牌 |
| `Content-Type` | `application/json` |

## 请求体参数

**country** `string` *required*

出金国家的完整名称（例如 `"Mexico"`、`"Argentina"`）。必须与所选 `userPaymentId` 关联的国家一致。

**crypto** `string` *required*

要兑换的加密货币代码（例如 `"USDT"`、`"USDC"`）。

**fiat** `string` *required*

收款人将收到的法币的 ISO 4217 代码（例如 `"MXN"`、`"ARS"`、`"BRL"`）。

**userPaymentId** `integer` *required*

接收法币付款的收款人（用户支付方式）的数字 ID。可通过 `GET /v2/payments` 获取。

**clientId** `string`

你自己的订单参考 ID，最长 40 个字符。它在你账户下的所有 `fiat_to_crypto` 和 `crypto_to_fiat` 订单中必须唯一；使用相同 `clientId` 的第二次创建请求将被拒绝。该值会在查询订单响应中返回，并可代替 `orderId` 用于查询订单。参见[幂等性与重试](https://docs.velafi.com/cn/api-reference/order/create-a-fiat-to-crypto-order.md#idempotency-and-retries)。

**merchantId** `integer` *required*

订单所属商户的数字 ID。加密货币从该商户的余额中扣除。未提供有效 `merchantId` 的请求将被拒绝。

**cryptoAmount** `decimal`

要兑换的加密货币数量（例如 `1000.00`）。如果同时发送了正数的 `fiatAmount`，则忽略此值。

**fiatAmount** `decimal`

收款人应收到的法币金额（例如 `21000.00`）。请提供 `fiatAmount` 或 `cryptoAmount`；如果同时发送，则以 `fiatAmount` 为准。

**remark** `string`

附加到订单的可选自由文本备注。

**quoteId** `string`

来自报价 API 的报价 ID，用于锁定特定汇率。省略则使用实时现货汇率。

## 响应字段

**code** `integer`

响应状态码。`200` 表示成功。

**msg** `string`

可读的响应信息。

**data** `object`

订单结果对象。

**data 字段**

**data.orderId** `integer`

所创建订单的唯一数字 ID。用于查询订单状态和详情。

## 示例

```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-2024-001",
    "merchantId": 3,
    "crypto": "USDT",
    "fiat": "MXN",
    "cryptoAmount": 1000.00,
    "userPaymentId": 91,
    "remark": "Payout to supplier",
    "quoteId": "e46836d68a4a4a6f8f2f609352cffb2f"
  }'
```

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

## 为订单注资

出金订单所需的加密货币来自请求中 `crypto` 和 `merchantId` 对应的商户加密资产余额。可通过[加密资产余额](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)进行充值。

* **余额足以覆盖订单：** VelaFi 在创建订单时从余额中扣除加密货币。
* **余额不足：** 请求将被拒绝并返回余额不足错误，除非你的账户已开通后注资出金（开通情况可能因法币币种而异）。

> [!NOTE]
>
> 开通后注资出金后，资金不足的订单会停留在 `status: 32`（等待加密货币充值）。如果订单需要先进行合规审核（`status: 10` 或 `11`），审核通过后会进入 `32`。订单处于 `32` 状态期间，订单详情会返回 `orderExpireTimestamp`，即以秒为单位的 Unix 时间戳形式的注资截止时间。VelaFi 每分钟检查一次商户余额；当同一商户和加密货币下有多个订单在等待时，余额会按从早到晚的顺序分配给这些订单。一旦余额足以覆盖某个订单，VelaFi 会扣除加密货币，订单进入 `status: 40`，如需补充证明文件则进入 `31`。如果先到达截止时间，订单将被取消（`status: 70`）。

对于处于 `status: 50`（已支付）的 `crypto_to_fiat` 订单，调用 [`POST /v2/order/confirm`](https://docs.velafi.com/cn/api-reference/order/confirm-a-specific-order) 可完成订单（`status: 60`）。

## 幂等性与重试

使用 `clientId` 可以让订单创建请求安全地重试。

* `clientId` 为可选参数。发送时，其长度不得超过 40 个字符，且必须在你账户下所有商户的全部 `fiat_to_crypto` 和 `crypto_to_fiat` 订单中唯一。
* 重复使用已有 `clientId` 的创建请求将被拒绝并返回重复提交错误，不会创建新订单。响应不会返回原订单；请改为查询该订单。
* `clientId` 会永久绑定到其订单，即使订单被取消也是如此。新订单请使用新的 `clientId`。
* 通过 `GET /v2/order/detail?orderType=crypto_to_fiat&clientId={clientId}` 按 `clientId` 查询订单。

如果创建请求超时或没有返回响应：

1. 使用相同的 `orderType` 和 `clientId` 调用 `GET /v2/order/detail`。
2. 如果找到订单，说明原请求已成功。不要再次创建。
3. 如果未找到，使用相同的 `clientId` 重试。如果第一次请求在此期间确实已创建订单，重试将作为重复请求被拒绝，而不会创建第二个订单。

> [!NOTE]
>
> `quoteId` 可能会被一个随后被拒绝的创建请求消耗。重试前请重新申请报价。


## Related topics

- [出金（加密货币兑法币）](https://docs.velafi.com/cn/docs/guides/off-ramp.md)
- [获取收款人列表](https://docs.velafi.com/cn/api-reference/beneficiary/get-beneficiary.md)
- [创建入金订单](https://docs.velafi.com/cn/api-reference/order/create-a-fiat-to-crypto-order.md)
- [Webhook](https://docs.velafi.com/cn/docs/guides/webhooks.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.