> ## 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.

# 将您的客户注册为商户

> 通过 API 将您自己的客户注册为 VelaFi 商户，引导他们完成 KYC/KYB，并激活其本地货币账户。

如果您的平台代表您自己的客户（个人或公司）转移资金，请在您的 VelaFi 账户下将每位客户注册为一个**商户**。每个商户都需通过各自的 KYC（个人）或 KYB（企业）验证，并获得专属的**商户 ID (MID)**。商户获批且其币种账户激活后，您在为该客户发起的每一次支付调用中都需传入该 MID。

## 工作原理

```mermaid theme={null}
flowchart LR
  A["POST /v2/merchants"] --> B["客户在 kycLink<br/>完成验证"]
  B --> C["GET /v2/merchants<br/>直到 status = 2"]
  C --> D["POST /v2/merchant/accounts<br/>按币种逐个激活"]
  D --> E["GET /v2/merchant/accounts<br/>直到 status = 2"]
  E --> F["可选：虚拟账户"]
  F --> G["在支付调用中<br/>使用 merchantId"]
```

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

## 开始之前

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

## 分步操作

**1. 创建商户**

调用[创建商户](https://docs.velafi.com/cn/api-reference/merchant/create-merchant.md)（`POST /v2/merchants`），传入 `merchantName`、`email`、`merchantType`（`INDIVIDUAL` 或 `BUSINESS`）和 `callbackUrl`。同时传入 `industryType`（当其为 `other` 时还需传入 `industryTypeRemark`）。对于个人，`flow` 用于选择 KYC 流程（默认为 `PROFESSIONALS`，或 `CONSUMERS`），`languageCode` 用于设置托管页面的语言（`en`、`es`、`pt`、`zh`）。

```bash theme={null}
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"
  }'
```

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

请立即在您的系统中将 `merchantId` 与该客户关联保存。从此刻起商户即已存在，即使尚未完成验证。

常见拒绝原因：

| 错误码 | 原因 |
| - | - |
| `-5005` | 您的账户下已存在使用该 `merchantName` 的商户。 |
| `-2017` | 该 `email` 已被某个 VelaFi 商户使用。 |
| `-4010` | 某个字段无效，例如 `merchantType`、`flow` 或 `email`。`msg` 会指明该字段。 |
| `-5064` | 您的账户已达到商户数量上限。请联系 VelaFi。 |

> [!WARNING]
>
> 创建商户不是幂等操作。如果调用超时，不要使用不同的信息再次创建商户。请按您发送的 `email` 筛选商户列表（参见第 3 步），以确认商户是否已创建。

**2. 引导客户前往验证链接**

将客户的浏览器重定向到 `kycLink`，或在您的应用中通过 iframe 打开。个人完成 KYC；企业完成 KYB。两种展示方式参见[创建商户](https://docs.velafi.com/cn/docs/guides/creating-merchant.md)。

该链接有时效限制。如果客户未完成或链接已过期，请使用现有的 `merchantId`、创建时使用的相同 `merchantType` 以及 `callbackUrl` 再次调用 `POST /v2/merchants`，以获取新链接：

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

这不会创建第二个商户。当商户的验证正在审核中时，该调用会以 `-5062` 失败；验证获批后，则以 `-5063` 失败。

> [!NOTE]
>
> 用户到达您的 `callbackUrl` 仅表示客户离开了托管流程，并不表示已获批。请务必在下一步中检查状态。

**3. 检查商户状态**

调用[获取商户列表](https://docs.velafi.com/cn/api-reference/merchant/get-a-list-of-merchants.md)（`GET /v2/merchants`），读取 `status` 和 `rejectReason`。请传入 `status=-1`：不传时，列表只返回已获批的商户。使用 `email` 或 `merchantName` 筛选以查找单个商户。

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

| `status` | 含义 | 处理方式 |
| - | - | - |
| `4` | 未完成 | 客户尚未完成托管流程。向其发送新链接（第 2 步）。 |
| `1` | 认证中 | 审核中。继续轮询。 |
| `2` | 正常 | 已获批。继续第 4 步。 |
| `3` | 认证失败 | 已被拒绝。读取 `rejectReason`。您可以请求新链接以重新提交。 |

商户验证没有 Webhook。请以适中的间隔轮询，例如在客户入驻期间每隔几分钟轮询一次，之后降低频率。

**4. 激活币种账户**

针对客户需要的每种币种，调用 `POST /v2/merchant/accounts`，传入 `merchantId`、`fiat` 和 `trench`（渠道名称），以及该渠道的 `fieldList`。请求内容因商户类型而异：

* 个人：[激活个人商户账户](https://docs.velafi.com/cn/api-reference/merchant/activate-merchant-account-for-individual.md)
* 企业：[激活企业商户账户](https://docs.velafi.com/cn/api-reference/merchant/activate-merchant-account-for-business.md)

```bash theme={null}
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"
  }'
```

处理返回的 `status`：

| `status` | 含义 | 处理方式 |
| - | - | - |
| `0` 且带有 `verifyLink` | 企业商户：该渠道需要额外的企业验证。 | 引导企业前往 `verifyLink`。VelaFi 批准后，该渠道会自动开通，无需再次调用。 |
| `1` | 待处理。服务商正在开设账户。 | 轮询[获取商户账户列表](https://docs.velafi.com/cn/api-reference/merchant/get-a-list-of-merchant-accounts.md)。 |
| `2` | 已激活。 | 完成。 |
| `3` | 失败。 | 读取 `failReason`。 |
| `4` 且带有 `verifyLink` | 未完成。例如，通过 Lead Bank 开通 USD/EUR 需要签署协议。 | 引导商户前往 `verifyLink`。 |

然后轮询 `GET /v2/merchant/accounts?merchantId=100001`，直到该渠道显示 `status: 2`。每条记录还会返回该渠道的 `paymentId`，您在虚拟账户、出金和订单中都需要用到它。

部分渠道有额外要求。BRL Pix - Woovi 要求个人先完成活体检测（[获取 Woovi 活体检测 URL](https://docs.velafi.com/cn/api-reference/merchant/get-woovi-liveness-url.md)），要求企业提供完整的公司和 UBO 资料。文件必须通过[上传文件](https://docs.velafi.com/cn/api-reference/basic-configuration/upload-file.md)上传。各渠道的要求参见[激活商户账户](https://docs.velafi.com/cn/docs/guides/activating-merchant-account.md)。

常见拒绝原因：`-5073`（商户尚未通过 KYC）、`-5074`（已激活）、`-5062`（激活已在处理中）、`-5079`（无该渠道的激活权限）、`-4010`（缺少必填的 `fieldList` 字段或字段无效）。

**5. 可选：创建虚拟账户**

如果客户向大量付款人收款，请通过[创建虚拟账户](https://docs.velafi.com/cn/api-reference/merchant/create-multiple-virtual-account.md)（`POST /v2/merchant/virtual/accounts`）为每个付款人提供专属的充值信息。传入 `merchantId`、`fiat`、该渠道的 `paymentId` 以及由字母和数字组成的 `alias`。虚拟账户支持 MXN、ARS、BRL 和 COP，且币种账户必须已激活。

通过[获取虚拟账户列表](https://docs.velafi.com/cn/api-reference/merchant/get-multiple-virtual-account.md)读取充值信息。向虚拟账户的充值会以 `depositAlias` 的形式携带其别名。完整的收款流程参见[使用虚拟账户收取本地付款](https://docs.velafi.com/cn/docs/use-cases/collect-with-virtual-accounts.md)。

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

`merchantId` 决定一次调用使用谁的余额、限额和账户。在为该客户发起的每次调用中，请传入客户的 MID，而不是您自己的：

| 调用 | 字段 |
| - | - |
| 入金和出金订单（`POST /v2/order/fiat_to_crypto`、`POST /v2/order/crypto_to_fiat`） | `merchantId` |
| 全球支付订单（`POST /v2/order/fiat_to_fiat`） | `onRampMerchantId`、`offRampMerchantId` |
| 从法币余额出金（`POST /v2/merchant/claimfunds`） | `merchantId` |
| 商户之间划转（`POST /v2/merchant/transfer`） | `fromMerchantId`、`toMerchantId` |
| 收款人（`POST /v2/payments`） | 收款人所属币种账户对应商户的 `merchantId`。请务必传入：不传时，为自动支付方式添加收款人会失败。 |
| 加密货币提现和充值地址 | `merchantId` |
| 充值信息、资金记录、法币流水、余额 | `merchantId` 筛选条件 |

请在您的客户 ID 与 VelaFi MID 之间保持一一对应，并且绝不允许由客户提供的值来决定 MID。

## 需要处理的 Webhook

商户验证和渠道激活没有 Webhook。请按上文所述轮询 `GET /v2/merchants` 和 `GET /v2/merchant/accounts`。

Webhook 按 VelaFi 账户注册，而不是按商户注册：每种事件类型注册一次，即可接收您所有商户的事件。订单、资金记录、加密货币提现和稳定币支付事件都带有 `merchantId`，请据此路由。对于不带 `merchantId` 的事件，请通过其 ID 查询相应记录。参见 [Webhook 设置](https://docs.velafi.com/cn/api-reference/webhooks/webhook-setup.md)。

## 处理失败

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

## 对账

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

请运行定期任务，将您的客户记录与这两个列表进行比对，确保不会有客户停留在您系统不知道的状态。

## 在沙盒环境中测试

您的沙盒账户附带预先配置的测试商户，沙盒环境中不会进行真实的 KYC/KYB。请使用这些商户测试激活结果、虚拟账户以及后续的支付流程。请针对上表中的每个状态码编写状态处理逻辑，因为您无法让真实审核人员批准或拒绝沙盒商户。参见[沙盒环境](https://docs.velafi.com/cn/docs/sandbox.md)。

## 上线检查清单

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

然后完成通用的[上线检查清单](https://docs.velafi.com/cn/docs/use-cases/go-live-checklist.md)。


## Related topics

- [核心使用场景](https://docs.velafi.com/cn/docs/use-cases/overview.md)
- [商户](https://docs.velafi.com/cn/docs/merchants.md)
- [创建商户](https://docs.velafi.com/cn/docs/guides/creating-merchant.md)
- [Agent Skills](https://docs.velafi.com/cn/docs/developer-tools/agent-skills.md)
- [添加收款人](https://docs.velafi.com/cn/api-reference/beneficiary/add-beneficiary.md)


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.