> ## Documentation Index
> Fetch the complete documentation index at: https://docs.gate.com/llms.txt
> Use this file to discover all available pages before exploring further.

# 查询认证状态

> 查询机构子账户 KYB 认证当前状态。

## 概述

本页说明「查询认证状态」接口。完整的请求参数、响应结构与示例由上方关联的 OpenAPI 定义渲染。

## 说明

* 认证方式使用 GatePay 标准签名请求头。
* 这个机构专属接口不使用 `X-GatePay-On-Behalf-Of`。
* 通过 `subAccountId` 查询指定子账户的 KYB 认证状态。
* 通用签名规则请参见 [/api-reference/version/100/cn/common/securityAndSignature](/api-reference/version/100/cn/common/securityAndSignature)。

## 使用场景

* 机构商户轮询子账户认证进度
* 在发起业务操作前校验子账户 `currentAuthStatus` 是否为 `succeeded`

## 注意事项

* `currentAuthStatus` 取值包括：`un_open`、`submitted`、`succeeded`、`rejected`
* `auditTime` 仅在状态为 `succeeded` 或 `rejected` 时返回
* `rejectReason` 仅在状态为 `rejected` 时返回；`succeeded` 时不返回该字段
* 认证审核完成后，GatePay 也会通过 [子账户认证结果通知](/api-reference/version/100/cn/endpoint/institutional/verifyResultNotification) 主动推送结果


## OpenAPI

````yaml api-reference/version/100/cn/openapi/institutional-openapi.json GET /pay-cashier/open/v1/certification/verify/query
openapi: 3.1.0
info:
  title: GatePay 机构 API
  description: Gate Pay 机构 API 接口文档
  license:
    name: MIT
  version: 1.0.0
servers:
  - url: https://openplatform.gateapi.io
security: []
paths:
  /pay-cashier/open/v1/certification/verify/query:
    get:
      tags:
        - Institutional
      summary: 查询认证状态
      description: 查询机构子账户 KYB 认证当前状态。
      operationId: queryVerify
      parameters:
        - $ref: '#/components/parameters/X-GatePay-Certificate-ClientId'
        - $ref: '#/components/parameters/X-GatePay-Timestamp'
        - $ref: '#/components/parameters/X-GatePay-Nonce'
        - $ref: '#/components/parameters/X-GatePay-Signature'
        - name: subAccountId
          in: query
          required: true
          description: 机构子账户唯一 ID
          schema:
            type: integer
            format: int64
            example: 53695180
      responses:
        '200':
          description: 成功响应
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/QueryVerifyResponseWrapper'
              examples:
                success:
                  summary: 认证通过
                  value:
                    code: '2'
                    message: success
                    data:
                      merchantNo: '12345678'
                      subAccountId: '53695180'
                      currentAuthStatus: succeeded
                      accountType: KYB
                      submitTime: 1780036614339
                      auditTime: 1780036714339
                rejected:
                  summary: 认证驳回
                  value:
                    code: '2'
                    message: success
                    data:
                      merchantNo: '12345678'
                      subAccountId: '53695180'
                      currentAuthStatus: rejected
                      accountType: KYB
                      submitTime: 1780036614339
                      auditTime: 1780036714339
                      rejectReason: 证件照片不清晰
components:
  parameters:
    X-GatePay-Certificate-ClientId:
      name: X-GatePay-Certificate-ClientId
      in: header
      required: true
      description: 商户在Gate商户后台注册应用时分配的clientId
      schema:
        type: string
        example: 4186d0c6-6a35-55a9-8dc6-5312769dbff8
    X-GatePay-Timestamp:
      name: X-GatePay-Timestamp
      in: header
      required: true
      description: 请求生成时的UTC时间戳，milliseconds。请注意，GatePay不处理收到请求时间与这个时间戳差距大于10秒钟的请求
      schema:
        type: string
        example: '1672905655498'
    X-GatePay-Nonce:
      name: X-GatePay-Nonce
      in: header
      required: true
      description: 随机字符串，字符符合HTTP Header头部的规范，建议长度在32个字符以内，字符串组成为数字和字母
      schema:
        type: string
        example: '9578'
    X-GatePay-Signature:
      name: X-GatePay-Signature
      in: header
      required: true
      description: 请求签名。GatePay通过此签名来确定此请求是否合法
      schema:
        type: string
  schemas:
    QueryVerifyResponseWrapper:
      type: object
      description: 查询认证状态响应
      properties:
        code:
          type: string
          description: 响应码
          example: '2'
        message:
          type: string
          description: 响应消息
          example: success
        data:
          $ref: '#/components/schemas/GatePayVerifyQueryData'
    GatePayVerifyQueryData:
      type: object
      description: 认证状态查询结果
      properties:
        merchantNo:
          type: string
          description: 机构主商户 ID
        subAccountId:
          type: string
          description: 机构子账户唯一 ID
        currentAuthStatus:
          type: string
          description: 子账户当前最新总状态
          enum:
            - un_open
            - submitted
            - succeeded
            - rejected
        accountType:
          type: string
          description: 认证类型，固定为 KYB
          enum:
            - KYB
        submitTime:
          type: integer
          format: int64
          description: 提交时间（毫秒）
        auditTime:
          type: integer
          format: int64
          description: 审核完成时间（毫秒），仅在 `succeeded` 或 `rejected` 时返回
        rejectReason:
          type: string
          description: 驳回原因，仅在 `rejected` 时返回

````