将您的客户注册为商户

​

工作原理

1. 创建商户。VelaFi 返回一个 merchantId 和一个托管的 kycLink。
2. 引导您的客户前往 kycLink 完成 KYC 或 KYB。
3. 轮询商户状态，直到其变为 2（正常）。
4. 为客户需要的每种币种激活一个币种账户（渠道）。
5. 可选：创建虚拟账户，让客户的每个付款人都拥有专属的充值信息。
6. 在该客户的每笔订单、出金、划转和查询中使用该 merchantId。

​

开始之前

• API 访问权限、带 IP 白名单的 API 密钥以及令牌。 参见认证。本页的所有调用都从您的服务器发起，并携带 X-BH-TOKEN 请求头。
• 您自己的账户已获批。 您创建的商户隶属于您的 VelaFi 账户。多商户模式参见商户。
• 客户资料已准备好。 确定每位客户是 INDIVIDUAL 还是 BUSINESS，并为每位客户收集商户名称和电子邮箱地址。
• 一个用于返回用户的页面。 您将其作为 callbackUrl 传入。对于个人验证，用户完成托管流程后，VelaFi 会将用户的浏览器重定向到该 URL。

​

分步操作

curl -X POST https://api.velafi.com/v2/merchants \
  -H "X-BH-TOKEN: YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "merchantName": "Example Customer 0001",
    "email": "customer0001@example.com",
    "merchantType": "BUSINESS",
    "industryType": "e-commerce",
    "callbackUrl": "https://your-app.example.com/onboarding/done",
    "languageCode": "en"
  }'

{
  "code": 200,
  "msg": "SUCCESS",
  "data": {
    "merchantId": 100001,
    "kycLink": "https://www.velafi.com/verify?velafi_token=abc123"
  }
}

{
  "merchantId": 100001,
  "merchantType": "BUSINESS",
  "callbackUrl": "https://your-app.example.com/onboarding/done",
  "languageCode": "en"
}

curl -G https://api.velafi.com/v2/merchants \
  -H "X-BH-TOKEN: YOUR_TOKEN" \
  --data-urlencode "status=-1" \
  --data-urlencode "email=customer0001@example.com"

curl -X POST https://api.velafi.com/v2/merchant/accounts \
  -H "X-BH-TOKEN: YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "merchantId": "100001",
    "fiat": "MXN",
    "trench": "CLABE - FINCO PAY"
  }'

​

在所有其他调用中使用商户 ID

​

需要处理的 Webhook

​

处理失败

• 验证被拒绝（status: 3）。 向客户展示 rejectReason，然后使用相同的 merchantId 和 merchantType 请求新链接。
• 客户中途放弃（status: 4）。 发送附带新链接的提醒。不要创建新商户；名称和邮箱已被第一个商户占用。
• 激活失败（status: 3）。 在激活响应或获取商户账户列表中读取 failReason。修正 fieldList 数据或联系 VelaFi。
• 激活长时间处于待处理状态。 待处理渠道取决于服务商。请继续轮询；如果渠道迟迟未激活，请联系 VelaFi。
• 超时和结果未知的错误（-1001、-1006、-1007）。商户或渠道可能已被创建。再次调用前，请通过获取商户列表或获取商户账户列表进行检查。参见错误码。

​

对账

• 带 status=-1 的 GET /v2/merchants 是验证状态以及每个商户每日和每月限额使用情况的唯一可信来源。
• GET /v2/merchant/accounts 是哪些渠道已激活及其 paymentId、余额和每月买入/卖出限额的唯一可信来源。

​

在沙盒环境中测试

​

上线检查清单

• POST /v2/merchants 返回后立即保存 merchantId，并将其与您的客户一一对应。
• 处理每种商户状态（1、2、3、4）和每种激活状态（0 到 4），包括 verifyLink 重定向。
• 使用 status=-1 轮询，以免尚未获批的商户从结果中遗漏。
• 使用现有的 merchantId 和 merchantType 重新请求过期链接，而不是创建重复的商户。
• 等待渠道显示 status: 2 后，再为该币种创建虚拟账户或发起支付。
• 在每个下游调用中传入客户的 MID，并按 merchantId 路由 Webhook 事件。