# 查询持卡人列表

> 分页查询商户账户下的持卡人，并支持可选筛选条件。

```yaml
openapi: 3.1.0
info:
  title: 查询持卡人列表
  version: 1.0.0
  description: 分页查询商户账户下的持卡人，并支持可选筛选条件。
paths:
  /api/v1/merchant/cardholder/queryCardholder:
    post:
      summary: 查询持卡人列表
      description: 分页查询商户账户下的持卡人，并支持可选筛选条件。
      parameters:
        - name: ApiKey
          in: header
          required: true
          description: Onerway 分配的发卡 API key 请求 Header。
          schema:
            type: string
            description: Onerway 分配的发卡 API key 请求 Header。
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                merchantNo:
                  type: integer
                  description: 商户号筛选条件；仅在已开通跨商户查询权限时使用。
                cardholderId:
                  type: integer
                  description: 持卡人 ID 筛选条件。
                clientRequestId:
                  type: string
                  description: 幂等请求 ID 筛选条件。
                pageNum:
                  type: integer
                  description: 页码。
                  x-onerway-constraints:
                    - kind: range
                      min: 1
                pageSize:
                  type: integer
                  description: 每页条数。
                  x-onerway-constraints:
                    - kind: range
                      min: 1
                      max: 100
              required:
                - pageNum
                - pageSize
            examples:
              default:
                summary: 查询持卡人列表
                value:
                  pageNum: 1
                  pageSize: 10
      responses:
        "200":
          description: 成功
          content:
            application/json:
              schema:
                type: object
                properties:
                  respCode:
                    type: string
                    description: 业务响应码；`20000` 表示成功。
                  respMsg:
                    type: string
                    description: 响应信息。
                  data:
                    type:
                      - object
                      - "null"
                    properties:
                      records:
                        type: array
                        description: 当前页持卡人记录。
                        items:
                          type: object
                          properties:
                            cardholderId:
                              type: integer
                              description: 持卡人 ID。
                            firstName:
                              type: string
                              description: 持卡人名。
                            lastName:
                              type: string
                              description: 持卡人姓。
                            email:
                              type: string
                              description: 持卡人邮箱。
                            mobile:
                              type:
                                - string
                                - "null"
                              description: 持卡人手机号。
                              x-onerway-value:
                                nullable: true
                                when:
                                  en: No mobile number is available.
                                  zh: 无手机号时返回 `null`。
                            mobileAreaCode:
                              type:
                                - string
                                - "null"
                              description: 手机国际区号。
                              x-onerway-value:
                                nullable: true
                                when:
                                  en: No mobile area code is available.
                                  zh: 无手机国际区号时返回 `null`。
                            birthDay:
                              type:
                                - string
                                - "null"
                              description: 出生日期。
                              x-onerway-value:
                                nullable: true
                                when:
                                  en: No date of birth is available.
                                  zh: 无出生日期时返回 `null`。
                            nationality:
                              type:
                                - string
                                - "null"
                              description: 国籍。
                              x-onerway-value:
                                nullable: true
                                when:
                                  en: No nationality is available.
                                  zh: 无国籍时返回 `null`。
                            addressRegionCode:
                              type:
                                - string
                                - "null"
                              description: 地址国家或地区代码。
                              x-onerway-value:
                                nullable: true
                                when:
                                  en: No address region is available.
                                  zh: 无地址国家或地区时返回 `null`。
                            addressStateCode:
                              type:
                                - string
                                - "null"
                              description: 州 / 省代码。
                              x-onerway-value:
                                nullable: true
                                when:
                                  en: No state or province is available.
                                  zh: 无州 / 省代码时返回 `null`。
                            addressCityCode:
                              type:
                                - string
                                - "null"
                              description: 城市代码。
                              x-onerway-value:
                                nullable: true
                                when:
                                  en: No city is available.
                                  zh: 无城市代码时返回 `null`。
                            addressDetailLine1:
                              type:
                                - string
                                - "null"
                              description: 地址行 1。
                              x-onerway-value:
                                nullable: true
                                when:
                                  en: No address line is available.
                                  zh: 无地址行时返回 `null`。
                            addressDetailLine2:
                              type:
                                - string
                                - "null"
                              description: 地址行 2。
                              x-onerway-value:
                                nullable: true
                                when:
                                  en: No address line 2 is available.
                                  zh: 无地址行 2 时返回 `null`。
                            addressPostalCode:
                              type:
                                - string
                                - "null"
                              description: 邮编。
                              x-onerway-value:
                                nullable: true
                                when:
                                  en: No postal code is available.
                                  zh: 无邮编时返回 `null`。
                            remark:
                              type:
                                - string
                                - "null"
                              description: 备注。
                              x-onerway-value:
                                nullable: true
                                when:
                                  en: No remark is available.
                                  zh: 无备注时返回 `null`。
                        x-onerway-value:
                          empty: true
                          when:
                            en: Returned as an empty array when no cardholder matches.
                            zh: 无匹配持卡人时返回空数组。
                      total:
                        type: integer
                        description: 总记录数。
                      current:
                        type: integer
                        description: 当前页码。
                      size:
                        type: integer
                        description: 每页条数。
                    description: 分页持卡人查询结果。
                    x-onerway-value:
                      nullable: true
                      when:
                        en: Returned as `null` when the query fails.
                        zh: 查询失败时返回 `null`。
              examples:
                success:
                  summary: 成功
                  value:
                    respCode: "20000"
                    respMsg: success
                    data:
                      records:
                        - cardholderId: 300001
                          firstName: Alex
                          lastName: Chen
                          email: example_cardholder@example.com
                          mobile: null
                          mobileAreaCode: null
                          birthDay: null
                          nationality: CN
                          addressRegionCode: CN
                          addressStateCode: GD
                          addressCityCode: SZ
                          addressDetailLine1: Example address line 1
                          addressDetailLine2: null
                          addressPostalCode: "518000"
                          remark: null
                      total: 1
                      current: 1
                      size: 10
```