> ## Documentation Index > Fetch the complete documentation index at: https://developers.uqpay.com/llms.txt > Use this file to discover all available pages before exploring further. # List Cardholders > 返回签发持卡人对象的列表。对象按创建时间降序排列，最近创建的对象排在最前。 ## OpenAPI ````yaml /zh/card-issuance/v1.6/issuing.yaml get /v1/issuing/cardholders openapi: 3.0.2 info: title: Issuing API version: 0.0.1 x-source-en-commit: fdf4a2b x-source-en-path: card-issuance/v1.6/issuing.yaml description: > UQPAY Issuing API 让你签发虚拟卡、管理持卡人，并监控卡交易。 ## 功能概览 - 创建并管理虚拟卡（签发、激活、冻结、注销） - 通过 KYC 完成持卡人入驻与验证 - 设置消费限额与卡控制 - 为卡余额充值与提现 - 查询卡交易与账户余额 - 在发卡账户之间转账 - 生成并下载报表 ## 身份认证 所有请求都需要携带有效的鉴权 Token，Token 通过 [Access Token](/zh/account-center/v1.6/api-reference/access-token) 接口获取。请在 `x-auth-token` 请求头中携带该 Token。 ## 幂等性 POST 请求支持 `x-idempotency-key` 请求头，可安全重试而不会创建重复资源。 contact: name: UQPAY Support Team url: https://www.uqpay.com/support email: support@uqpay.com license: name: Proprietary url: https://www.uqpay.com/legal/api-terms termsOfService: https://www.uqpay.com/legal/terms x-api-id: uqpay-issuing-api-v1.6.0 x-categories: - Card Issuing - Transaction Processing x-features: - Virtual Card Issuance - Real-time Processing - Webhook Notifications - Comprehensive Reporting - Transaction Monitoring servers: - url: https://api-sandbox.uqpaytech.com/api description: 沙盒环境基础 URL。 - url: https://api.uqpay.com/api description: 生产环境基础 URL。 security: [] tags: - name: Card Lifecycle description: 创建卡片并管理其完整生命周期——签发、查询、更新、激活、绑定与变更状态。 - name: Card Secure Data description: 通过 PCI 合规接口或令牌化 iframe 访问敏感卡数据（PAN、CVV）。是否可用取决于你的 PCI 状态，而非卡产品。 - name: Card Funding description: 为预付类卡片充值或提取其卡内储值余额。 - name: Card PIN description: 设置并管理卡片 PIN 码。`reset-pin` 用于实体卡，`manage-card-pin` 用于虚拟卡。 - name: Card Add-ons description: >- 产品专属的卡功能。每个操作仅适用于特定卡产品——参见 [卡产品](/zh/card-issuance/v1.6/guide/card-products)。 - name: Card Arts description: >- 管理发卡账户可用的视觉设计（卡面）。可设置账户级默认卡面，或在签发/更新卡片时传入 `card_art_id` 以按卡覆盖。仅 Personal Visa 支持。 - name: Cardholders description: 你可以创建持卡人。持卡人是你企业的授权代表，可被签发卡片。 - name: Transactions description: 这些接口用于查询在你用户卡片上发生的交易信息。 - name: Products description: 通过这组接口，你可以为客户创建卡订单。 - name: Balances description: 各币种的可用金额与待处理金额会进一步按资金来源类型细分。你可以查询它，查看发卡账户当前的余额。 - name: Transfers description: 在发卡账户之间转账。 - name: Reports description: 生成并下载发卡报表。 - name: Simulator description: 在沙盒环境中模拟卡交易。 paths: /v1/issuing/cardholders: get: tags: - Cardholders summary: List Cardholders description: 返回签发持卡人对象的列表。对象按创建时间降序排列，最近创建的对象排在最前。 operationId: list-cardholders parameters: - $ref: '#/components/parameters/XOnBehalfOf' - $ref: '#/components/parameters/PageSize' - $ref: '#/components/parameters/PageNumber' - $ref: '#/components/parameters/PathCardholderStatus' responses: '200': description: 成功获取持卡人列表。 headers: x-response-id: $ref: '#/components/headers/XResponseId' content: application/json: schema: title: ListCardholdersResponse properties: total_pages: $ref: '#/components/schemas/TotalPages' total_items: $ref: '#/components/schemas/TotalItems' data: type: array items: $ref: '#/components/schemas/CardholderListResponse' security: - XAuthToken: [] components: parameters: XOnBehalfOf: in: header name: x-on-behalf-of schema: type: string required: false description: > 指定代表哪个子账户发起请求。应设置为 `account_id`，该值可通过 [List Connected Accounts](/zh/account-center/v1.6/api-reference/list-connected-accounts) 接口获取。若省略或为空，则请求以主账户身份执行。 更多信息参见 [关联账户](/zh/account-center/v1.6/guide/connected-accounts)。 example: 18523f72-f4de-4f9c-bb8e-ec7d1c4f32be PageSize: name: page_size description: 每页返回的最大条目数。取值范围为 10 - 100，默认为 10。 in: query required: true schema: type: integer minimum: 10 maximum: 100 default: 10 PageNumber: name: page_number description: 用于获取下一组条目的页码。取值必须大于 1，默认为 1。 in: query required: true schema: type: integer minimum: 1 default: 1 PathCardholderStatus: name: cardholder_status description: 按指定持卡人状态检索条目。未指定时匹配任意持卡人状态。 in: query required: false schema: type: string example: PENDING enum: - PENDING - SUCCESS - INCOMPLETE - FAILED headers: XResponseId: description: 响应的全局唯一标识符（UUID v4）。在联系 UQPAY 支持团队时有助于定位某次请求。 schema: type: string format: uuid example: 2adba88e-9d63-44bc-b975-9b6ae3440dde schemas: TotalPages: type: integer example: 1 description: 可用条目的总页数。 TotalItems: type: integer example: 10 description: 可用条目的总数。 CardholderListResponse: type: object properties: cardholder_id: $ref: '#/components/schemas/CardholderId' email: $ref: '#/components/schemas/CardholderEmail' number_of_cards: $ref: '#/components/schemas/CardholderNumberOfCards' first_name: description: 该持卡人的名字。激活卡片前必填。此字段不能包含任何数字、特殊字符（句点、逗号、连字符、空格和撇号除外）或非拉丁字母。 type: string example: Emily last_name: description: 该持卡人的姓氏。激活卡片前必填。此字段不能包含任何数字、特殊字符（句点、逗号、连字符、空格和撇号除外）或非拉丁字母。 type: string example: Toy create_time: description: 对象的创建时间。 type: string example: '2024-05-09 15:52:23' cardholder_status: $ref: '#/components/schemas/CardholderStatus' date_of_birth: $ref: '#/components/schemas/CardholderDateOfBirth' country_code: $ref: '#/components/schemas/CountryCode' phone_number: $ref: '#/components/schemas/CardholderPhoneNumber' gender: $ref: '#/components/schemas/Gender' nationality: $ref: '#/components/schemas/Nationality' residential_address: $ref: '#/components/schemas/ResidentialAddress' review_status: $ref: '#/components/schemas/ReviewStatus' idv_status: type: string description: | IDV 验证状态。在适用时返回。 * `PENDING` - IDV 待处理。 * `PASSED` - IDV 通过。 * `FAILED` - IDV 失败。 enum: - PENDING - PASSED - FAILED idv_verification_url: type: string description: IDV 验证 URL。在适用时返回。 example: https://idv.sumsub.com/verify/abc123 idv_url_expires_at: type: string description: IDV 验证 URL 的过期时间，RFC 3339 格式。 example: '2026-04-10T10:00:00+08:00' CardholderId: type: string description: 持卡人的唯一标识符。 example: 7c4ff2cd-1bf6-4aaa-bf16-266771425011 format: uuid CardholderEmail: type: string description: 持卡人的电子邮箱地址。 example: demo@example.com CardholderNumberOfCards: type: integer description: 与持卡人关联的卡片总数，包含所有状态。 example: 1 CardholderStatus: description: 持卡人的状态。 type: string default: SUCCESS enum: - FAILED - PENDING - SUCCESS - INCOMPLETE CardholderDateOfBirth: description: 持卡人的出生日期，格式为 `yyyy-mm-dd`。 type: string example: '1990-01-01' CountryCode: type: string description: >- 两位国家代码 [ISO 3166-1 alpha-2](https://en.wikipedia.org/wiki/ISO_3166-1_alpha-2)。 maxLength: 2 example: SG CardholderPhoneNumber: description: > 持卡人的电话号码。 长度校验详情参见 [电话号码校验规则](/zh/card-issuance/v1.6/guide/phone-number-validation-rules-for-cardholder)。 type: string example: '86683306' Gender: type: string description: | 持卡人的性别。 * `MALE` - 男。 * `FEMALE` - 女。 enum: - MALE - FEMALE example: MALE Nationality: type: string description: 持卡人的国籍，采用 ISO 3166-1 alpha-2 格式。STANDARD 和 ENHANCED KYC 等级必填。 minLength: 2 maxLength: 2 example: SG ResidentialAddress: type: object description: > 持卡人的居住地址。 所有字段只接受字母（A-Z、a-z）、数字（0-9）、空格，以及以下标点：`, . ' / # ( ) - &`。包含其他任何字符的请求都会被拒绝——请修正后重新提交。为空的可选字段不做校验。 required: - country - city - line1 properties: country: $ref: '#/components/schemas/Country' state: type: string description: 州/县/省/地区。 maxLength: 128 example: Singapore city: type: string description: 城市/区/郊区/镇/村。 maxLength: 128 example: Singapore district: type: string description: 城市内的区或子区域。 maxLength: 128 example: Buona Vista line1: type: string description: 地址行 1（如街道、邮政信箱或公司名称）。 maxLength: 255 example: 9 N Buona Vista Dr line2: type: string description: 地址行 2（如公寓、套房、单元或楼宇）。 maxLength: 255 example: THE METROPOLIS line_en: type: string description: 英文地址。 maxLength: 255 example: 9 N Buona Vista Dr, THE METROPOLIS postal_code: type: string description: 邮编或邮政编码。如果你打算签发 Enhanced 卡，此字段长度必须为 4-10 个字符。 maxLength: 16 example: '138666' ReviewStatus: type: string description: 持卡人的审核状态。 enum: - SUCCESS - FAILED - PENDING example: SUCCESS Country: type: string description: >- 两位国家代码 [ISO 3166-1 alpha-2](https://en.wikipedia.org/wiki/ISO_3166-1_alpha-2)。 maxLength: 2 example: SG securitySchemes: XAuthToken: type: apiKey in: header name: x-auth-token description: 由 UQPay 提供的登录 API Token。 ````