fiat_to_crypto 订单将本地货币（例如 MXN、ARS、COP 或 BRL）兑换为稳定币。您可以选择每笔订单的付款方式：使用商户待处理资金 (Pending Fund) 余额中已持有的法币支付，或由付款人针对该笔订单发起银行转账支付。订单完成后，加密货币会入账到商户的 VelaFi 钱包。之后您可以继续持有、提现，或让其自动发送到外部地址。
完整的字段说明请参阅入金指南和创建入金订单。
选择注资模式
工作原理
开始之前
- API 访问权限。 一个 API 密钥、已加入白名单的服务器 IP，以及用于
X-BH-TOKEN请求头的业务令牌。参见认证。 - 一个已验证的商户。 订单的
merchantId必须是您账户下已通过验证的商户。参见商户。 - 一个已激活的币种账户。 商户需要拥有该法币的已激活账户。参见激活商户账户。
- 已注册 Webhook。 注册
ORDER_WEBHOOK；如果预先注资，还需注册FUNDING_WEBHOOK；如果需要提现，还需注册CRYPTO_WITHDRAW_WEBHOOK。参见 Webhook。您的端点必须返回 HTTP2xx和响应体{"callbackStatus":"SUCCESS"}，否则推送视为失败。参见推送与重试。
构建流程
1
仅限预先注资：为待处理资金余额注资
通过获取待入账资金账户（
GET /v2/merchant/addfunds）获取商户币种账户的充值信息，并将法币汇至该账户。每笔入账的充值都会触发一条 type 为 DEPOSIT、status 为 2 的 FUNDING_WEBHOOK 事件。在创建大额订单前，请通过获取商户账户列表（balance）检查当前余额。如果您已经将付款收取到商户的币种账户，这些充值就构成了该余额。参见使用虚拟账户收取本地付款。2
可选：通过报价锁定汇率
调用获取加密货币/法币报价，将
from 设为法币、to 设为加密货币，并设置 createQuoteId=true。price 表示每 1 单位加密货币对应的法币数量。quoteId 在生产环境中的有效期为 10 秒（沙盒环境中为 300 秒），只能使用一次，并且与签发时的 country、法币和加密货币绑定。请在创建订单前一刻再请求报价。如果不传 quoteId，订单将按创建时的价格定价。3
创建订单
调用 如果请求超时，请在重试前先通过
POST /v2/order/fiat_to_crypto。务必传入唯一的 clientId（最多 40 个字符），以便安全重试并在之后查找订单。- 预先注资
- 按单付款
将 VelaFi 在创建订单时会检查商户该币种的余额。如果余额不足以覆盖订单金额，请求将因余额不足错误被拒绝，且不会创建订单。如果余额足够，订单创建后会立即从余额中支付并进入
paymentId 设为 70（VelaFi Pending Fund）。60（已完成），除非它需要先经过审核或提交材料（10、11 或 31）。该笔扣款会以 BUY_CRYPTO 记录的形式出现在资金记录中。Response
clientId 查询订单。参见幂等性与重试。4
仅限按单付款：展示付款指引
使用
orderType=fiat_to_crypto 调用获取订单，向付款人展示 paymentInfo 的内容（例如 SPEI 的 CLABE）以及准确的 fiatAmount。付款人的转账入账后，VelaFi 会将其用于同一币种账户上的未完成订单。金额与某笔订单金额完全相等的充值会优先用于该订单。否则，充值会用于最早的未完成订单。带有 depositAlias 的订单只能由该虚拟账户收到的充值支付。没有 depositAlias 的订单可以由该币种账户上的任何充值支付，包括已在待处理资金余额中的法币。5
6
可选：将加密货币从钱包转出
您有两种方式：
- 按订单自动提现。 如果 VelaFi 已为您的账户开通入金自动提现，请在创建请求中添加
network和address。订单完成后，VelaFi 会将cryptoAmount提现到该地址，并在提现成功时发送ON_RAMP_WITHDRAW_WEBHOOK。在生产环境中，network必须为POL或SPL20。这两个字段需同时传入或同时省略。未开通该功能的账户会被拒绝，并返回 “You are currently not a user of the onRamp automatic withdrawal service.”。参见入金提现事件。 - 自行提现。 将目标地址添加到您的提现白名单，然后使用您自己的唯一
clientId调用创建加密货币提现（POST /v2/assets/withdraw）。通过获取提现额度查询有效的chainType值和最低金额。
CRYPTO_WITHDRAW_WEBHOOK。对于自动提现，其 clientId 为入金订单的 orderId。需要处理的 Webhook
事件可能重复到达、乱序到达，且中间状态可能被跳过。请进行去重，并在事件与您持有的状态不符时通过
GET /v2/order/detail 读取订单。参见推送与重试。
处理失败
付款时限
按单付款订单只会在40 状态等待有限的时间。VelaFi 为您的账户设定该时限。订单详情中不会返回该时限，因此请向您的 VelaFi 联系人询问具体数值，并根据 createTime 向付款人展示截止时间。时限结束仍未收到全额付款时，订单将被取消，并在订单详情和 ORDER_WEBHOOK 中报告为 orderStatus 70。已取消的订单无法重新打开。
如果付款人在订单取消后付款，该转账仍会入账到商户的待处理资金余额（您会收到一条 FUNDING_WEBHOOK DEPOSIT），但不会用于已取消的订单。您可以为该金额创建新订单（随后由余额支付），或通过提取待处理资金将资金支付出去。
对账
- 订单： 通过
orderId或clientId调用获取订单，是每笔订单的唯一可信来源：orderStatus、fiatAmount、fiatFee、cryptoAmount、orderPrice、failCode和failReason。使用带时间范围的获取订单列表统计每日总额。该接口也会列出非通过 API 创建的订单。 - 法币余额： 获取资金记录显示每笔
DEPOSIT和BUY_CRYPTO，两种注资模式均适用。获取法币流水提供带变动后余额的逐笔账目。 - 加密货币转出： 通过
clientId查询获取加密货币提现记录，直到status为6（成功）、7（失败）或9（已取消）。
在沙盒环境中测试
- 使用
https://api-test.velafi.com。沙盒环境中不会发送 Webhook，因此请轮询GET /v2/order/detail。 - 使用法币充值模拟器为测试商户的余额注资，或支付按单付款订单（
depositAlias可指定虚拟账户）。参见沙盒环境测试工具。 - 在沙盒环境中，
quoteId的有效期为 300 秒，自动提现的network可接受POL或TSPL20。 - 模拟器只能生成成功的充值，无法模拟被退回的付款。如需测试过期路径，请创建一笔按单付款订单且不付款。
上线检查清单
- 每个创建请求都传入唯一的
clientId，超时时先通过clientId查询再决定是否重试。 - 预先注资流程会检查余额，并在遇到余额不足拒绝时不会循环重试同一请求。
- 按单付款流程会展示
paymentInfo、准确金额和截止时间，并在70后创建新订单。 - 如果您在同一币种账户上为多个付款人运行按单付款，每个付款人都有一个虚拟账户（
depositAlias）。 -
ORDER_WEBHOOK端点会验证签名，返回 HTTP2xx和{"callbackStatus":"SUCCESS"}，并基于orderId+orderStatus去重。 - 有定时任务根据 API 对未完成订单、资金记录和提现进行对账。
- 提现目标地址已加入白名单，或已开通自动提现并使用
network和address完成测试。