沙盒环境

VelaFi 沙盒环境是一个隔离的测试环境，使用完全模拟的数据复现生产 API 的结构和行为。您可以创建订单、查询账户并完整演练请求/响应流程，而无需转移真实资金、验证真实身份或影响任何正式商户账户。它是任何新集成的推荐起点，也是在部署到生产环境之前验证变更的安全场所。

沙盒环境 Base URL

将您的 HTTP 客户端指向以下 Base URL 即可访问沙盒环境：

https://api-test.velafi.com

所有生产端点均以相同的路径结构在此 Base URL 下提供。例如，在沙盒环境中获取法币交易对：

curl --request GET \
  --url https://api-test.velafi.com/v2/base/fiat/symbols

此端点为公开端点，无需令牌。操作您账户的端点则需要令牌：请参阅认证。

获取沙盒环境凭证

沙盒环境 API 密钥与生产密钥分开开通，不通过控制台生成。如需获取沙盒环境的 API key 和 API secret，请直接联系 VelaFi 团队：

邮箱：contact@velafi.com

访问沙盒环境无需完成 KYC/KYB，也无需创建商户账户。VelaFi 团队会为您开通一个预配置的测试账户，其中包含可直接使用的模拟用户和商户数据。

收到凭证后，使用它们通过 GET /v2/token/generate 获取令牌，并在每个请求的 X-BH-TOKEN 请求头中携带该令牌，方式与生产环境完全相同：

X-BH-TOKEN: YOUR_SANDBOX_TOKEN

沙盒环境与生产环境对比

下表总结了两个环境之间的主要行为差异。在决定某项操作适合在哪个环境中进行时，可将其作为检查清单。

功能	沙盒环境	生产环境
是否需要 KYC / KYB	否——提供预配置的测试账户	是——需要完成完整的身份验证
API 密钥创建	无需创建——凭证由 VelaFi 提供	需要创建——通过控制台并使用双重验证（2FA）生成
用户和账户数据	虚拟模拟数据，不关联真实个人	与已验证商户和用户关联的真实数据
资金转账	不转移真实资金，所有交易均为模拟	通过实际支付通道转移真实资金
Webhook 回调	不触发——不会发送任何回调事件	订单状态变化时触发
Base URL	`https://api-test.velafi.com`	`https://api.velafi.com`

切勿将生产 API 密钥用于沙盒环境 Base URL，也切勿将沙盒环境凭证用于生产 Base URL。请在环境配置中严格区分这两套凭证。

示例：获取法币交易对

以下请求演示了一次完整的沙盒环境 API 调用。它使用的是公开端点，因此可以确认您能够访问沙盒环境，但不会测试您的凭证。

curl --request GET \
  --url https://api-test.velafi.com/v2/base/fiat/symbols

import requests

response = requests.get(
    "https://api-test.velafi.com/v2/base/fiat/symbols",
)
print(response.json())

const response = await fetch(
  "https://api-test.velafi.com/v2/base/fiat/symbols",
  {
    method: "GET",
  }
);
const data = await response.json();
console.log(data);

成功的响应会返回测试环境中支持的法币交易对列表：

{
  "code": 200,
  "msg": "SUCCESS",
  "data": [
    {
      "symbol": "ARS_USDT",
      "base_currency": "ARS",
      "quote_currency": "USDT",
      "status": "active"
    },
    {
      "symbol": "MXN_USDT",
      "base_currency": "MXN",
      "quote_currency": "USDT",
      "status": "active"
    }
  ]
}

在切换到生产环境之前，请在沙盒环境中完整演练入金、出金和全球支付订单流程。由于沙盒环境不会触发 Webhook 回调，测试期间请手动轮询订单状态端点以验证状态流转。

沙盒环境测试工具

沙盒环境提供两个模拟入账充值的端点，您无需转移真实资金即可为测试商户注资。它们仅存在于 https://api-test.velafi.com；在 https://api.velafi.com 上会返回 404。两者均支持 GET 或 POST，参数以查询参数形式发送。

模拟法币充值

https://api-test.velafi.com/v2/platform/test/deposit 模拟一笔向商户已激活法币账户的入账银行充值。

number

必填

要入账的商户 ID。

string

必填

法币代码，例如 MXN。

number

必填

充值金额。必须大于 0。

number

必填

该商户在此币种下已激活法币账户的支付方式 ID。

string

同一 merchantId、fiat 和 paymentId 下某个虚拟账户的别名。设置后，充值将进入该虚拟账户。

常见失败消息：

The merchant has not activated the corresponding fiat currency account. — 该商户没有此 fiat 和 paymentId 对应的已激活账户。
The depositAlias invalid. — 没有与 depositAlias 匹配的虚拟账户。
This method of currency recharge is not currently supported. — 此支付方式没有充值模拟器。

cURL

curl -G https://api-test.velafi.com/v2/platform/test/deposit \
  --data-urlencode "merchantId=151209" \
  --data-urlencode "fiat=MXN" \
  --data-urlencode "fiatAmount=1000" \
  --data-urlencode "paymentId=105"

模拟加密货币充值

https://api-test.velafi.com/v2/platform/test/crypto/deposit 向商户钱包添加测试加密货币资金。

number

必填

已获批准的商户 ID。

string

必填

USDT、USDC、BTC、MMXN、COPM 或 MXNB 之一。其他值将返回 {"code":500, "msg":"crypto is invalid"}。

number

必填

要添加的数量。必须大于 0。

成功时，响应的 code 为 200。

cURL

curl -G https://api-test.velafi.com/v2/platform/test/crypto/deposit \
  --data-urlencode "merchantId=151209" \
  --data-urlencode "crypto=USDT" \
  --data-urlencode "amount=500"

模拟器仅支持成功的充值，无法生成失败或被退回的充值。

后续步骤

快速入门

设置您的生产账户并生成正式 API 密钥。

API 参考

浏览所有可用端点、参数和响应结构。

快速入门

核心概念

指南

参考

沙盒环境 Base URL

获取沙盒环境凭证

沙盒环境与生产环境对比

示例：获取法币交易对

推荐的测试流程

沙盒环境测试工具

模拟法币充值

模拟加密货币充值

后续步骤

快速入门

API 参考

​沙盒环境 Base URL

​获取沙盒环境凭证

​沙盒环境与生产环境对比

​示例：获取法币交易对

​推荐的测试流程

​沙盒环境测试工具

​模拟法币充值

​模拟加密货币充值

​后续步骤

快速入门

API 参考

沙盒环境 Base URL

获取沙盒环境凭证

沙盒环境与生产环境对比

示例：获取法币交易对

推荐的测试流程

沙盒环境测试工具

模拟法币充值

模拟加密货币充值

后续步骤