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

# 查询客户充值支付

> 按充值支付 ID 查询当前商户的客户充值支付详情。资源不存在或不属于当前商户时统一返回 404。

充值支付不存在或不属于当前商户时统一返回 `404 resource_not_found`。



## OpenAPI

````yaml /zh/api/customer-deposits.openapi.json get /api/v1/customer-deposits/{deposit_session_id}
openapi: 3.1.0
info:
  title: StablePay 客户充值支付 API
  version: '2026-10-13'
  summary: 客户充值支付创建和查询 API。
  description: >-
    StablePay 客户充值支付 API 的 OpenAPI 规范。


    说明：

    - 基础 URL：https://api.stablepay.co

    - 认证方式：Bearer API Key + `X-StablePay-Timestamp` + `X-StablePay-Nonce` +
    `X-StablePay-Signature`

    - 签名字符串：`{timestamp}.{nonce}.{requestBody}`

    - 签名算法：HMAC-SHA256，小写 hex

    - GET 请求的 `requestBody` 为空字符串

    - StablePay 根据 `external_customer_id` 在当前商户范围内自动识别或创建客户

    - 商户身份由鉴权网关注入，请求参数不得传入 `merchant_id`
servers:
  - url: https://api.stablepay.co
    description: 生产环境
security:
  - bearerAuth: []
    stablepayTimestamp: []
    stablepayNonce: []
    stablepaySignature: []
tags:
  - name: 客户充值支付
    description: 创建和查询客户充值支付及托管收银台链接。
paths:
  /api/v1/customer-deposits/{deposit_session_id}:
    get:
      tags:
        - 客户充值支付
      summary: 查询客户充值支付
      description: |-
        按充值支付 ID 查询当前商户的客户充值支付详情。资源不存在或不属于当前商户时统一返回 404。

        充值支付不存在或不属于当前商户时统一返回 `404 resource_not_found`。
      operationId: getCustomerDeposit
      parameters:
        - $ref: '#/components/parameters/XStablePayTimestamp'
        - $ref: '#/components/parameters/XStablePayNonce'
        - $ref: '#/components/parameters/XStablePaySignature'
        - name: deposit_session_id
          in: path
          required: true
          description: 充值支付 ID。
          schema:
            type: string
            minLength: 1
          example: '20261013110310801082920000001001'
      responses:
        '200':
          description: 查询成功。
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CustomerDepositSession'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          description: 充值支付不存在或不属于当前商户。
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '500':
          $ref: '#/components/responses/InternalError'
components:
  parameters:
    XStablePayTimestamp:
      name: X-StablePay-Timestamp
      in: header
      required: true
      description: Unix 时间戳（秒）。必须与服务端时间相差不超过 5 分钟。
      schema:
        type: string
      example: '1791878400'
    XStablePayNonce:
      name: X-StablePay-Nonce
      in: header
      required: true
      description: 防重放随机字符串，长度 16-64 个字符，建议每次请求使用新的 UUID。
      schema:
        type: string
        minLength: 16
        maxLength: 64
      example: 550e8400-e29b-41d4-a716-446655440000
    XStablePaySignature:
      name: X-StablePay-Signature
      in: header
      required: true
      description: >-
        使用商户 API Secret 对 `{timestamp}.{nonce}.{requestBody}` 计算
        HMAC-SHA256，结果为小写 hex。GET 请求的 `requestBody` 为空字符串。
      schema:
        type: string
      example: a1b2c3d4e5f6...
  schemas:
    CustomerDepositSession:
      type: object
      required:
        - deposit_session_id
        - customer_id
        - status
        - allow_multiple_deposits
        - expires_at
        - url
        - metadata
        - created
      properties:
        deposit_session_id:
          type: string
          description: 充值支付 ID。
        customer_id:
          type: string
          description: StablePay 客户 ID。
        status:
          type: string
          enum:
            - active
            - closed
            - expired
          description: 充值支付状态。
        allow_multiple_deposits:
          type: boolean
          description: 是否允许使用同一个链接多次充值。
        expires_at:
          type:
            - integer
            - 'null'
          format: int64
          description: 过期时间，Unix 秒；永久有效时固定返回 null。
        url:
          type: string
          format: uri
          description: 托管收银台 URL。
        metadata:
          type: object
          additionalProperties:
            type: string
          description: 商户自定义元数据。
        created:
          type: integer
          format: int64
          description: 创建时间，Unix 秒。
    ErrorResponse:
      type: object
      required:
        - code
        - message
        - errorCode
        - data
      description: 错误响应。
      properties:
        code:
          type: integer
          description: HTTP 状态码。
        message:
          type: string
          description: 错误信息。
        errorCode:
          type: string
          description: 稳定的业务错误代码。
        data:
          type: 'null'
          description: 错误响应中固定为 null。
  responses:
    Unauthorized:
      description: 鉴权失败。
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
    InternalError:
      description: 服务内部错误。
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      bearerFormat: API Key
      description: Bearer API Key，例如 `Bearer sk_live_xxx`。
    stablepayTimestamp:
      type: apiKey
      in: header
      name: X-StablePay-Timestamp
      description: Unix 时间戳（秒）。必须与服务端时间相差不超过 5 分钟。
    stablepayNonce:
      type: apiKey
      in: header
      name: X-StablePay-Nonce
      description: 防重放随机字符串，长度 16-64 个字符。
    stablepaySignature:
      type: apiKey
      in: header
      name: X-StablePay-Signature
      description: 使用商户 API Secret 计算的 HMAC-SHA256 小写 hex 签名。

````

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