> ## 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) 会为您的用户将本地法币兑换为加密货币。请指定源法币、目标加密货币，并通过 `paymentId` 指定支付方式。订单金额可以用法币（`fiatAmount`）或加密货币（`cryptoAmount`）确定；如果同时传入两者，则以 `fiatAmount` 为准。如需锁定汇率，请传入通过报价 API 获取的 `quoteId`；若未传入，订单将按创建时的当前汇率定价。响应会返回一个 `orderId`，您可以通过获取订单和订单列表端点，使用它在订单整个生命周期内进行跟踪。

## 端点

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

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

## 请求头

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

## 请求体参数

**country** `string` *required*

入金所在国家的完整名称（例如 `"Mexico"`、`"Brazil"`）。必须与所选 `paymentId` 支持的国家一致。

**crypto** `string` *required*

目标加密货币的代码（例如 `"USDT"`、`"USDC"`、`"BTC"`）。

**fiat** `string` *required*

用户付款所用法币的 ISO 4217 代码（例如 `"MXN"`、`"BRL"`、`"COP"`）。

**paymentId** `integer` *required*

法币充值所用支付方式的数字 ID。请参阅支付模板参考中的支付方式 ID 表。

**clientId** `string`

您自己的订单参考 ID，最多 40 个字符。它在您账户下所有 `fiat_to_crypto` 和 `crypto_to_fiat` 订单中必须唯一；使用相同 `clientId` 的第二次创建请求将被拒绝。该字段会在获取订单的响应中返回，并可代替 `orderId` 用于查询订单。请参阅[幂等性与重试](#idempotency-and-retries)。

**merchantId** `integer` *required*

订单所属商户的数字 ID。未提供有效 `merchantId` 的请求将被拒绝。

**fiatAmount** `decimal`

用户支付的法币金额（例如 `1000.00`）。请提供 `fiatAmount` 或 `cryptoAmount`；如果同时传入两者，则以 `fiatAmount` 为准。

**cryptoAmount** `decimal`

用户收到的加密货币数量（例如 `46.73`）。如果同时传入了正数的 `fiatAmount`，则忽略此字段。

**remark** `string`

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

**depositAlias** `string`

用于法币充值的虚拟账户别名。基于虚拟账户的支付方式必须提供。

**quoteId** `string`

通过报价 API 获取的报价 ID，用于锁定特定汇率。省略则使用实时现货汇率。

**inFieldJson** `object`

某些支付方式所需的额外支付专用字段。

**inFieldJson 字段**

**inFieldJson.bank** `string`

付款人银行代码，当 `paymentId` 为 `141`（PSE）时必填。PSE 使用其独立的银行列表，与收款人所用的[哥伦比亚银行代码](https://docs.velafi.com/cn/api-reference/beneficiary/get-payment-templates.md#哥伦比亚银行代码)表不同。

**PSE 银行代码**

| 代码 | 银行 |
| - | - |
| 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 |

## 响应字段

**code** `integer`

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

**msg** `string`

可读的响应消息。

**data** `object`

订单结果对象。

**data 字段**

**data.orderId** `integer`

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

## 示例

```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]
>
> 创建订单后，轮询 `GET /v2/order/detail?orderId={orderId}&orderType=fiat_to_crypto` 以监控其状态。新订单的初始状态为 `status: 40`（待付款）；如果需要合规审核或补充材料，则为 `10`、`11` 或 `31`。使用自动支付方式的订单会通过 VelaFi 的银行集成进入 `status: 50`（已付款）。对于手动支付方式，请在转账发出后调用 [`POST /v2/order/confirm`](https://docs.velafi.com/cn/api-reference/order/confirm-a-specific-order) 将订单标记为已付款。

## 幂等性与重试

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

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

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

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

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


## Related topics

- [入金（法币兑加密货币）](https://docs.velafi.com/cn/docs/guides/on-ramp.md)
- [创建出金订单](https://docs.velafi.com/cn/api-reference/order/create-a-crypto-to-fiat-order.md)
- [订单状态](https://docs.velafi.com/cn/docs/order-statuses.md)
- [Webhook](https://docs.velafi.com/cn/docs/guides/webhooks.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.