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

# 获取商户列表

> 分页获取商户列表，包括其 KYC 验证状态、每日和每月交易限额以及当前使用量。

使用此接口查询在你的账户下注册的商户。你可以按名称、邮箱或验证状态进行筛选，并对结果进行分页。响应包含每个商户的 KYC 状态、每日和每月交易限额以及当前使用量 —— 便于监控合规额度余量。

> [!NOTE]
>
> 所有请求都必须在 `X-BH-TOKEN` 请求头中携带通过 `GET /v2/token/generate` 获取的业务 token。

## 接口地址

`GET https://api.velafi.com/v2/merchants`

## 查询参数

**merchantName** `string`

按商户名称筛选结果（支持部分匹配）。

**email** `string`

按商户邮箱地址筛选结果。

**status** `integer`

按 KYC/KYB 验证状态筛选：

* `-1` — 所有状态
* `1` — 认证中
* `2` — 正常（默认）
* `3` — 认证失败
* `4` — 未完成

**currentPage** `integer`

要获取的页码（从 1 开始）。默认为 `1`。

**pageSize** `integer`

每页记录数。默认为 `10`，最大为 `1000`。

## 响应字段

**code** `number`

HTTP 风格的响应码。`200` 表示成功。

**msg** `string`

可读的状态信息，例如 `SUCCESS`。

**data** `object`

**data 字段**

**currentPage** `number`

返回的当前页码。

**size** `number`

本页返回的记录数。

**total** `number`

符合查询条件的商户总数。

**record** `array`

**record 条目字段**

**merchantId** `number`

商户的唯一标识符。

**country** `string`

商户所在国家。

**merchantName** `string`

商户的显示名称。

**email** `string`

商户的邮箱地址。

**merchantType** `number`

商户类型：`1` = INDIVIDUAL（个人），`2` = BUSINESS（企业）。

**status** `number`

KYC/KYB 状态：`1` = 认证中，`2` = 正常，`3` = 失败，`4` = 未完成。

**rejectReason** `string`

KYC/KYB 验证被拒绝时提供的原因。

**upgradeMerchantLimitStatus** `number`

待处理的限额提升申请的状态：`1` = 认证中，`2` = 正常，`3` = 失败，`4` = 未完成。

**upgradeMerchantLimitRejectReason** `string`

限额提升申请被拒绝的原因（如适用）。

**dayFiatLimit** `number`

商户每日可交易的最大法币金额。

**dayFiatUsed** `number`

今日已占用每日限额的法币金额。

**monthFiatLimit** `number`

商户每个自然月可交易的最大法币金额。

**monthFiatUsed** `number`

本月已占用每月限额的法币金额。

**monthCryptoLimit** `number`

商户每月可交易的最大加密货币等值金额（以 USD 计）。

**monthCryptoUsed** `number`

已占用每月加密货币限额的等值金额。

**remark** `string`

附加在商户记录上的自由文本备注。

**createTime** `string`

商户创建时间的 Unix 时间戳（毫秒）。

**updateTime** `string`

商户记录最后更新时间的 Unix 时间戳（毫秒）。

## 示例

```bash cURL theme={null}
curl -G https://api.velafi.com/v2/merchants \
  -H "X-BH-TOKEN: YOUR_TOKEN" \
  --data-urlencode "status=-1" \
  --data-urlencode "currentPage=1" \
  --data-urlencode "pageSize=10"
```

```json Response theme={null}
{
  "code": 200,
  "msg": "SUCCESS",
  "data": {
    "currentPage": 1,
    "size": 10,
    "total": 100,
    "record": [
      {
        "merchantId": 1,
        "country": "Mexico",
        "merchantName": "Example Merchant",
        "email": "merchant@example.com",
        "merchantType": 1,
        "status": 2,
        "rejectReason": "",
        "upgradeMerchantLimitStatus": 2,
        "upgradeMerchantLimitRejectReason": "",
        "dayFiatLimit": 25000.0,
        "dayFiatUsed": 0.0,
        "monthFiatLimit": 25000.0,
        "monthFiatUsed": 0.0,
        "monthCryptoLimit": 15000.0,
        "monthCryptoUsed": 0.0,
        "remark": "",
        "createTime": "1737452292000",
        "updateTime": "1737452344000"
      }
    ]
  }
}
```

> [!NOTE]
>
> 使用 `status=-1` 可获取处于所有 KYC 阶段的商户，包括验证失败或仍在进行中的商户。


## Related topics

- [更新日志](https://docs.velafi.com/cn/docs/changelog.md)
- [商户](https://docs.velafi.com/cn/docs/merchants.md)
- [获取商户账户列表](https://docs.velafi.com/cn/api-reference/merchant/get-a-list-of-merchant-accounts.md)
- [获取虚拟账户列表](https://docs.velafi.com/cn/api-reference/merchant/get-multiple-virtual-account.md)
- [激活个人商户账户](https://docs.velafi.com/cn/api-reference/merchant/activate-merchant-account-for-individual.md)


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