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

# 获取收款人列表

> 获取已注册收款人的分页列表，可按国家、状态、法币和商户 ID 进行筛选，以定位特定记录。

使用此端点列出您账户下注册的所有收款人。可按国家、法币、认证状态或商户 ID 筛选结果，以便在创建出金订单之前快速定位特定收款人。结果采用分页形式——使用 `currentPage` 和 `pageSize` 浏览大型结果集。每条记录上的 `status` 字段表示 VelaFi 已验证该账户（`1`）、仍在验证中（`2`），还是验证失败（`3`）。

## 端点

```text theme={null}
GET https://api.velafi.com/v2/payments
```

> [!NOTE]
>
> 沙盒环境测试请使用 `https://api-test.velafi.com/v2/payments`。

## 查询参数

**country** `string`

用于筛选结果的国家完整名称（例如 `"Mexico"`、`"Brazil"`）。

**status** `integer`

按认证状态筛选：`0` = 全部（默认），`1` = 有效，`2` = 认证中，`3` = 认证失败。

**fiat** `string`

用于筛选结果的 ISO 4217 法币代码（例如 `"MXN"`、`"BRL"`）。

**merchantId** `integer`

数字商户 ID，用于将结果筛选为特定商户。

**currentPage** `integer`

要获取的页码。默认为 `1`。

**pageSize** `integer`

每页记录数。默认为 `10`。

## 响应字段

**code** `integer`

响应状态码。`200` 表示成功。

**msg** `string`

人类可读的响应消息。

**data** `object`

分页结果集。

**data 字段**

**data.currentPage** `integer`

返回的当前页码。

**data.size** `integer`

每页记录数。

**data.total** `integer`

所有页面中匹配的收款人记录总数。

**data.record** `array`

收款人对象数组。

**record 条目字段**

**id** `integer`

唯一的用户支付（收款人）ID。创建出金订单时将其作为 `userPaymentId` 传入。

**merchantId** `integer`

此收款人所属的商户 ID。

**country** `string`

收款人所在国家的完整名称。

**fiat** `string`

与此收款人关联的法币代码。

**paymentId** `integer`

支付方式配置 ID。

**paymentMethodName** `string`

支付方式的显示名称（例如 `"CHATS"`、`"SPEI"`）。

**realName** `string`

账户持有人的法定真实姓名。

**status** `integer`

认证状态：`1` = 有效，`2` = 认证中，`3` = 失败。

**hasRefundAccount** `integer`

如果此收款人被指定为退款账户则为 `1`，否则为 `0`。

**fieldList** `object`

为此收款人存储的支付字段键值映射。

**remark** `string`

关于此收款人的可选自由文本备注。

**createTime** `integer`

收款人创建时的 Unix 时间戳（毫秒）。

## 示例

```bash theme={null}
curl -X GET "https://api.velafi.com/v2/payments?country=Mexico&status=1&currentPage=1&pageSize=10" \
  -H "X-BH-TOKEN: YOUR_TOKEN"
```

```json theme={null}
{
  "code": 200,
  "msg": "SUCCESS",
  "data": {
    "record": [
      {
        "id": 228,
        "merchantId": 67,
        "country": "Hong Kong",
        "fiat": "USD",
        "paymentId": 123,
        "paymentMethodName": "CHATS (CPN)",
        "realName": "test",
        "remark": "11",
        "createTime": 0,
        "fieldList": {
          "Account Owner Type": "Business",
          "Account Number": "000000000",
          "Bank Name": "Citibank, N.A., Hong Kong Branch",
          "Bank Country/Region": "HK",
          "Bank Identifier": "CITIHKHX",
          "Remarks": "111",
          "Street": "1 EXAMPLE STREET",
          "City": "Hong Kong",
          "State": "HK-HK",
          "Country/Region": "HK",
          "Postal Code": "00000"
        },
        "status": 1,
        "hasRefundAccount": 0
      }
    ],
    "size": 10,
    "currentPage": 1,
    "total": 1
  }
}
```


## Related topics

- [管理收款人](https://docs.velafi.com/cn/docs/guides/managing-beneficiaries.md)
- [获取模板元数据](https://docs.velafi.com/cn/api-reference/beneficiary/get-payment-templates-metamessage.md)
- [添加收款人](https://docs.velafi.com/cn/api-reference/beneficiary/add-beneficiary.md)
- [删除收款人](https://docs.velafi.com/cn/api-reference/beneficiary/delete-beneficiary.md)
- [获取支付方式模板](https://docs.velafi.com/cn/api-reference/beneficiary/get-payment-templates.md)


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