以稳定币注资支付本地货币

​

工作原理

​

开始之前

• API 访问权限。 一个 API 密钥、已加入白名单的服务器 IP，以及用于 X-BH-TOKEN 请求头的业务令牌。参见认证。
• 一个已验证的商户，拥有出金币种和渠道的已激活账户。收款人必须使用该账户的支付方式（paymentId）。参见激活商户账户。
• 已注册 ORDER_WEBHOOK。 您的端点必须返回 HTTP 2xx 和响应体 {"callbackStatus":"SUCCESS"}，否则推送视为失败。参见 Webhook 和推送与重试。

​

构建流程

curl -G https://api.velafi.com/v2/assets/depositAddress \
  -H "X-BH-TOKEN: YOUR_TOKEN" \
  --data-urlencode "tokenId=USDT" \
  --data-urlencode "chainType=TRC20" \
  --data-urlencode "merchantId=100001"

{ "code": 200, "msg": "SUCCESS", "data": { "id": 456, "status": 1, "failReason": "", "sameAccountNumberId": 456 } }

curl "https://api.velafi.com/v2/user/crypto-quote?country=Mexico&from=USDT&to=MXN&createQuoteId=true" \
  -H "X-BH-TOKEN: YOUR_TOKEN"

curl -X POST https://api.velafi.com/v2/order/crypto_to_fiat \
  -H "X-BH-TOKEN: YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "merchantId": 100001,
    "clientId": "payout-0001",
    "country": "Mexico",
    "fiat": "MXN",
    "crypto": "USDT",
    "fiatAmount": 1000,
    "userPaymentId": 456,
    "quoteId": "YOUR_QUOTE_ID"
  }'

{ "code": 200, "msg": "SUCCESS", "data": { "orderId": 1123123123 } }

​

通过 Circle Payment Network 进行 USD 和 EUR 出金

1. 为商户和币种激活 CPN 账户，并将 trench 设为 Circle Payment Network。参见激活企业商户账户。
2. 在 CPN 支付方式上登记收款人，例如 USD 使用 120 Wire (CPN) 或 127 FEDWIRE (CPN)，EUR 使用 124 SEPA (CPN)。CPN 模板要求提供收款人地址、useCase 和 reasonForPayment 代码。参见获取支付方式模板中的 CPN 模板。
3. 将 fiat 设为 USD 或 EUR，并使用 CPN 收款人的 userPaymentId 创建 crypto_to_fiat 订单，方法与上文完全相同。

​

需要处理的 Webhook

​

处理失败

​

对账

• 每笔出金： 通过 orderId 或 clientId 调用获取订单是唯一可信来源：orderStatus、cryptoAmount（从钱包扣除）、fiatAmount（支付给收款人）、fiatFee、orderPrice、orderFeeDetail、traceNumber、failCode 和 failReason。
• 每日总额： 使用 orderType=crypto_to_fiat 和时间范围调用获取订单列表。该接口也会列出非通过 API 创建的订单。
• 钱包： 通过获取加密货币充值记录查看充值，通过获取加密资产余额查看 free 和 locked。

​

在沙盒环境中测试

• 使用 https://api-test.velafi.com。沙盒环境中不会发送 Webhook，因此请轮询 GET /v2/order/detail。
• 使用加密货币充值模拟器向商户钱包添加测试 USDT 或 USDC。参见沙盒环境测试工具。
• 部分支付方式 ID 在沙盒环境中有所不同，例如 CBU/CVU (Momentum) 为 18 而不是 63。参见支付方式。
• 模拟器只能生成成功的充值。您无法模拟被退回的出金，因此请使用录制的负载测试 70 和 72 的处理逻辑。

​

上线检查清单

• 在创建订单前已为钱包注资，或已开通后付款出金，且您的系统会在 orderExpireTimestamp 之前为处于 32 的订单注资。
• 收款人只登记一次，按 userPaymentId 保存，且仅在 status 为 1 时使用。
• 每个创建请求都传入唯一的 clientId，超时时先通过 clientId 查询再决定是否重试。
• ORDER_WEBHOOK 端点会验证签名，返回 HTTP 2xx 和 {"callbackStatus":"SUCCESS"}，并基于 orderId + orderStatus 去重。
• 70 和 72（包括 60 之后的 72）会在您这边释放或冲正该笔出金，且只有在原订单达到最终状态后才创建替代出金。
• 停留在 40 或 50 的订单会被标记，并携带 orderId 升级处理。
• 对于 USD 和 EUR，CPN 账户已激活，且 CPN 收款人包含所需的合规字段。