openapi: 3.0.3
info:
  title: PayAll 第三方接入 API 文档
  description: |
    PayAll 第三方接入 API 文档
    
    ## 接入流程
    
    第三方系统接入 PayAll 平台需要完成以下步骤：
    
    1. **申请商户账号**
       - 联系 PayAll 商务团队申请商户账号
       - 提供必要的商户信息（商户名称、回调地址等）
    
    2. **获取密钥对**
       - PayAll 将为每个商户生成 RSA2048 密钥对
       - 商户将获得：
         - 公钥（提供给 PayAll，用于验证签名）
         - 私钥（商户保留，用于生成签名）
       - 密钥文件格式：PEM 格式
    
    3. **配置商户信息**
       - `source`: 商户来源标识（唯一标识，如 "SWFTGpt"）
       - `callback_url`: 商户回调地址（用于接收 PayAll 的回调通知）
       - 其他必要信息
    
    4. **调用登录接口**
       - 使用商户私钥对请求数据进行签名
       - 调用 `thirdPartyLogin` 接口获取用户 Token
       - 后续 API 调用使用该 Token 进行身份验证
    
    ## 对接流程图
    
    以下流程图展示了第三方系统与 PayAll 平台的完整对接流程：
    
    ```mermaid
    flowchart LR
        subgraph Phase1["🔧 阶段一：商户接入准备"]
            direction TB
            A1[📝 申请商户账号<br/>联系PayAll商务团队] 
            A2[🔑 获取密钥对<br/>RSA2048公钥/私钥]
            A3[⚙️ 配置商户信息<br/>source、callback_url]
            A1 --> A2 --> A3
        end
        
        subgraph Phase2["🔐 阶段二：用户认证"]
            direction TB
            B1[👤 用户登录<br/>调用 /thirdPartyLogin<br/>使用私钥签名]
            B2{Token有效?}
            B1 --> B2
            B2 -->|无效| B1
        end
        
        subgraph Phase3["💳 阶段三：卡片申请"]
            direction TB
            C1[📋 获取卡片列表<br/>调用 /merchant/cards]
            C2[✅ 检查可申请性<br/>调用 /cards/checkCanApply]
            C3{可以申请?}
            C4[📝 申请卡片<br/>调用 /cards/binding]
            C1 --> C2 --> C3
            C3 -->|否| C1
            C3 -->|是| C4
        end
        
        subgraph Phase4["💰 阶段四：开卡/充值"]
            direction TB
            D1[💵 查询费率<br/>调用 /cards/feeQuote]
            D2[📦 预充值<br/>调用 /charge/preCharge<br/>获取 order_id]
            D3[📱 获取充值地址<br/>调用 /charge/getChargeQrCode<br/>获取二维码]
            D1 --> D2 --> D3
        end
        
        subgraph Phase5["🌐 阶段五：用户转账"]
            direction TB
            E1{选择转账方式}
            E2[📷 二维码扫描转账]
            E3[🔌 插件钱包转账<br/>上传交易Hash]
            E4[⏳ 等待区块链确认]
            E1 -->|方式一| E2
            E1 -->|方式二| E3
            E2 --> E4
            E3 --> E4
        end
        
        subgraph Phase6["📞 阶段六：回调通知"]
            direction TB
            F1[📨 PayAll推送回调<br/>POST到 callback_url<br/>携带签名]
            F2{验证签名}
            F3[✅ 处理业务逻辑<br/>更新订单状态]
            F4[❌ 拒绝回调]
            F1 --> F2
            F2 -->|成功| F3
            F2 -->|失败| F4
        end
        
        subgraph Phase7["🔍 阶段七：状态查询"]
            direction TB
            G1[📊 查询订单状态<br/>调用 /getRecordDetail<br/>验证处理结果]
            G2[✨ 完成]
            G1 --> G2
        end
        
        Phase1 --> Phase2
        Phase2 --> Phase3
        Phase3 --> Phase4
        Phase4 --> Phase5
        Phase5 --> Phase6
        Phase6 --> Phase7
        
        style Phase1 fill:#e3f2fd,stroke:#1976d2,stroke-width:3px
        style Phase2 fill:#f3e5f5,stroke:#7b1fa2,stroke-width:3px
        style Phase3 fill:#e8f5e9,stroke:#388e3c,stroke-width:3px
        style Phase4 fill:#fff3e0,stroke:#f57c00,stroke-width:3px
        style Phase5 fill:#fce4ec,stroke:#c2185b,stroke-width:3px
        style Phase6 fill:#fff9c4,stroke:#f9a825,stroke-width:3px
        style Phase7 fill:#e0f2f1,stroke:#00796b,stroke-width:3px
        
        style A1 fill:#bbdefb
        style A2 fill:#90caf9
        style A3 fill:#64b5f6
        style B1 fill:#ce93d8
        style B2 fill:#ba68c8
        style C1 fill:#a5d6a7
        style C2 fill:#81c784
        style C3 fill:#66bb6a
        style C4 fill:#4caf50
        style D1 fill:#ffe0b2
        style D2 fill:#ffcc80
        style D3 fill:#ffb74d
        style E1 fill:#f8bbd0
        style E2 fill:#f48fb1
        style E3 fill:#f06292
        style E4 fill:#ec407a
        style F1 fill:#fff59d
        style F2 fill:#fff176
        style F3 fill:#ffeb3b
        style F4 fill:#ffc107
        style G1 fill:#b2dfdb
        style G2 fill:#80cbc4
    ```
    
    ### 流程图说明
    
    **阶段一：商户接入准备（步骤1-3）**
    - 申请商户账号并获取密钥对
    - 配置商户信息和回调地址
    
    **阶段二：用户认证（步骤4）**
    - 使用商户私钥签名，调用登录接口获取用户Token
    - 后续所有API调用都需要携带此Token
    
    **阶段三：卡片申请流程（步骤5-7）**
    - 查询可申请的卡片列表
    - 检查卡片申请条件
    - 申请并绑定卡片
    
    **阶段四：开卡/充值流程（步骤8-11）**
    - 查询开卡/充值费率
    - 预充值获取订单号
    - 获取充值地址和二维码
    - 用户通过不同方式完成转账
    
    **阶段五：回调处理（步骤12-13）**
    - PayAll 推送回调通知到商户回调地址
    - 商户验证签名并处理业务逻辑
    
    **阶段六：状态查询（步骤14）**
    - 商户可主动查询订单状态，验证处理结果
    
    ## 完整使用流程
    
    第三方系统接入后的完整使用流程如下：
    
    1. **获取用户 Token**
       - 调用 `/thirdPartyLogin` 接口，使用商户私钥签名获取用户 Token
       - 后续所有 API 调用都需要在请求头中携带此 Token
    
    2. **查询登录态**
       - 调用 `/checkLogin` 接口验证 Token 是否有效
       - 如果 Token 失效，需要重新调用 `/thirdPartyLogin` 获取新 Token
    
    3. **获取卡片列表**
       - 调用 `/merchant/cards` 接口获取商户可以申请的卡片列表
       - 支持按关键字搜索、筛选条件过滤、排序等功能
    
    4. **获取卡片类型配置**
       - 调用 `/cards/getCardbinSettings` 接口获取指定发卡商支持的卡片类型
       - 了解卡片类型、支持的国家、币种、费用、限额等信息
    
    5. **检查卡片是否可以申请**
       - 调用 `/cards/checkCanApply` 接口检查指定卡片是否可以申请
       - 获取申请条件、可绑定卡片数量、申请金额等信息
    
    6. **申请卡片（如需要）**
       - 调用 `/cards/binding` 接口申请/绑定卡片
       - 如果卡片支持 API 对接，会直接绑定并返回卡片信息
    
    7. **查询开卡/充值汇率**
       - 调用 `/cards/feeQuote` 接口查询开卡或充值的汇率及手续费信息
       - 用于向用户展示费用明细
    
    8. **预充值**
       - 调用 `/charge/preCharge` 接口进行预充值
       - 开卡场景：获取 `order_id`，需要提供 `card_issue_info`（如果没有 `card_binding_id`）
       - 充值场景：获取预充值结果
    
    9. **获取充值地址和二维码**
       - 调用 `/charge/getChargeQrCode` 接口获取充值地址和二维码
       - 返回充值地址、最小充值金额、过期时间和二维码（Base64编码）
    
    10. **用户转账操作**
        - **方式一：通过二维码充值**
          - 用户扫描二维码，向充值地址转账
          - 系统自动处理充值并回调商户
        
        - **方式二：插件钱包转账（开卡）**
          - 用户通过插件钱包（如MetaMask）向充值地址转账
          - 调用 `/cards/uploadTransaction` 接口上传交易 Hash
          - 调用 `/cards/getTransactionByHash` 接口查询开卡状态
        
        - **方式三：插件钱包转账（充值）**
          - 用户通过插件钱包向充值地址转账
          - 调用 `/wallet/uploadTransaction` 接口上传交易 Hash
          - 调用 `/wallet/getTransactionByHash` 接口查询充值状态
    
    11. **查询订单详情**
        - 调用 `/getRecordDetail` 接口根据订单号查询交易详情
        - 获取开卡、充值、支付、提现等交易的详细信息
    
    12. **查询交易记录**
        - 调用 `/userTrans` 接口查询所有交易记录（支持分页和筛选）
        - 调用 `/userTransRecord` 接口查询单条交易记录详情
    
    ## 签名机制
    
    使用 RSA2048 私钥对请求数据进行签名：
    
    1. 将请求参数（除 `sign` 字段外）按字典序排序
    2. 将排序后的参数转换为 JSON 字符串
    3. 使用商户私钥对 JSON 字符串进行 RSA 加密
    4. 将加密结果进行 Base64 编码，作为 `sign` 字段的值
    
    ## 安全说明
    
    - 所有请求必须包含有效的签名
    - 时间戳验证：请求时间戳与服务器时间差不能超过 60 秒
    - 过期时间验证：`expirationData` 必须晚于当前时间
    - 私钥必须妥善保管，不得泄露
    
    ## 第三方回调机制
    
    PayAll 平台会在特定事件发生时，主动向商户配置的回调地址推送通知。
    
    ### 回调配置
    
    在申请商户账号时，需要提供回调地址（`callback_url`）。PayAll 会在以下场景触发回调：
    
    - 开卡成功/失败
    - 卡片充值成功/失败
    - 卡片提现成功/失败
    - 卡片交易
    - 其他业务状态变更
    
    ### 回调请求格式
    
    PayAll 会向商户的回调地址发送 POST 请求，请求格式如下：
    
    **请求头：**
    - `Content-Type: application/json`
    - `X-Event-Type: {事件类型}` - 标识回调事件类型
    - `x-api-key: {API密钥}` - 仅对特定商户（如 cat_wallet）需要
    
    **请求体：**
    回调数据以 JSON 格式发送，包含以下字段：
    
    | 字段名 | 类型 | 必填 | 说明 |
    |--------|------|------|------|
    | event_type | string | 是 | 事件类型（见下方事件类型列表） |
    | user_id | integer | 是 | PayAll 用户ID |
    | timestamp | integer | 是 | 时间戳（秒级） |
    | order_id | string | 否 | 订单ID（第三方订单号） |
    | user_name | string | 否 | 第三方用户名 |
    | amount | string | 否 | 金额（根据事件类型可能包含） |
    | currency | string | 否 | 币种（根据事件类型可能包含） |
    | card_binding_id | integer | 否 | 卡片绑定ID（卡片相关事件包含） |
    | sign | string | 否 | RSA 签名（如果商户配置了私钥） |
    
    **回调数据示例：**
    
    ```json
    {
      "event_type": "card.issue.success",
      "user_id": 12345,
      "timestamp": 1698203395,
      "order_id": "open_card_12345_39_abc123",
      "user_name": "user@example.com",
      "card_binding_id": 12345,
      "amount": "30.00",
      "currency": "USD",
      "sign": "AJdzqyM5SSaewz7TF4M6cYK3NyVzz8tTjNpiGrlt3G+9Whncj2r8zMwNSkjyrvulSwZSIPFLCudIYiMI0BGSAGkLmVIwlZgZBvIRZwWlg0tt6hBvvEedRA1gCIVN4SSm4IKmnoxodOoRLL2MNrrTr7QvcUWZoSyElaCO3JL1cqwbReiAkIsy8kh0JQgZVhKX9fGlP07X3eXwdORr86DerBO/2Mv44XlJ8gTHwut9/pMkgveEh1pTKK0iFMIN00TA9wceRUZuuS7QegtK4hTLqoMz3m1saOYLNdTI7J9Qj1Wjf5SzGj5KIUkdqPK5GCAtzghRRWh4roYCiB0PE65crA=="
    }
    ```
    
    ### 支持的事件类型
    
    PayAll 支持以下事件类型的回调通知：
    
    #### 开卡相关
    - `card.issue.success` - 开卡成功
    
    #### 卡片充值相关
    - `card.topup.success` - 卡片充值成功
    
    ### 回调签名验证
    
    如果商户在配置时提供了私钥，PayAll 会对回调数据进行签名。商户可以使用公钥验证签名：
    
    1. 从回调数据中提取 `sign` 字段（Base64 编码的签名）
    2. 将除 `sign` 外的所有字段按字典序排序
    3. 将排序后的数据转换为 JSON 字符串（使用紧凑格式，无空格）
    4. 使用 PayAll 提供的公钥验证签名（SHA256withRSA）
    
    **签名验证示例（伪代码）：**
    
    ```python
    # 1. 提取签名
    sign = callback_data.pop('sign')
    sign_bytes = base64_decode(sign)
    
    # 2. 准备验证数据
    sorted_data = dict(sorted(callback_data.items()))
    data_str = json.dumps(sorted_data, separators=(',', ':'))
    
    # 3. 验证签名
    is_valid = rsa_verify(data_str, sign_bytes, public_key)
    ```
    
    ### 响应要求
    
    商户收到回调后，应该：
    
    1. **验证签名**（如果回调数据包含 `sign` 字段）
    2. **验证时间戳**（建议验证 `timestamp` 是否在合理范围内，防止重放攻击）
    3. **处理业务逻辑**（根据 `event_type` 和 `order_id` 更新本地订单状态）
    4. **返回响应**：
       - 成功处理：返回 HTTP 200 状态码，响应体可以是任意内容（建议返回 JSON 格式的成功响应）
       - 处理失败：返回 HTTP 4xx/5xx 状态码，PayAll 可能会重试
    
    **成功响应示例：**
    
    ```json
    {
      "code": 200,
      "status": "true",
      "message": "Callback processed successfully"
    }
    ```
    
    ### 重试机制
    
    - PayAll 会在回调失败时进行重试
    - 重试间隔和次数由 PayAll 内部策略决定
    - 商户应该保证回调接口的幂等性（相同 `order_id` 的重复回调应该返回相同结果）
    - 建议商户记录所有回调请求，避免重复处理
    
    ### 安全建议
    
    1. **使用 HTTPS**：回调地址必须使用 HTTPS 协议
    2. **验证签名**：始终验证回调数据的签名，确保数据来源可靠
    3. **验证时间戳**：检查 `timestamp` 字段，拒绝过期的回调请求
    4. **幂等性处理**：根据 `order_id` 实现幂等性，避免重复处理
    5. **日志记录**：记录所有回调请求，便于问题排查
    
    ### 回调调试
    
    商户可以通过以下方式调试回调：
    
    1. 使用 `/getRecordDetail` 接口查询订单状态，验证回调是否触发
    2. 检查回调记录（如果 PayAll 提供回调记录查询接口）
    3. 查看商户后台的回调日志
  version: 1.0.0
  contact:
    name: PayAll API Support
    email: support@payall.pro

servers:
  - url: https://api.payall.pro/v1/api
    description: 生产环境

tags:
  - name: 第三方接入
    description: 第三方系统接入相关接口
  - name: 卡片管理
    description: 卡片相关接口
  - name: 交易管理
    description: 交易记录相关接口

paths:
  /thirdPartyLogin:
    post:
      tags:
        - 第三方接入
      summary: 第三方用户登录
      description: |
        第三方系统通过此接口为用户获取 PayAll 平台的访问 Token。
        
        这是第三方接入的第一步，成功调用后将返回用户 Token，后续所有 API 调用都需要使用此 Token 进行身份验证。
        
        ## 请求流程
        
        1. 准备请求参数（account, expirationData, source, timestamp）
        2. 使用商户私钥对参数进行签名，生成 `sign` 字段
        3. 发送 POST 请求到 `/thirdPartyLogin`
        4. 获取返回的 `userToken`，用于后续 API 调用
        
        ## 签名生成示例（伪代码）
        
        ```python
        # 1. 准备参数（不包含 sign）
        params = {
            "account": "user@example.com",
            "expirationData": "2024-10-25 10:09:55",
            "source": "CatWallet",
            "timestamp": 1698203395
        }
        
        # 2. 按字典序排序
        sorted_params = dict(sorted(params.items()))
        
        # 3. 转换为 JSON 字符串
        json_str = json.dumps(sorted_params)
        
        # 4. 使用私钥加密并 Base64 编码
        encrypted = rsa_encrypt(json_str, private_key)
        sign = base64_encode(encrypted)
        
        # 5. 添加到请求参数
        params["sign"] = sign
        ```
      operationId: thirdPartyLogin
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
                - data
              properties:
                data:
                  type: object
                  required:
                    - account
                    - expirationData
                    - source
                    - sign
                    - timestamp
                  properties:
                    account:
                      type: string
                      description: 用户账号（通常是邮箱地址），系统会自动转换为小写处理，也可以是钱包地址等唯一标识
                      example: user@example.com
                      minLength: 1
                    expirationData:
                      type: string
                      description: Token 过期时间，格式为 "YYYY-MM-DD HH:mm:ss"。必须晚于当前时间，且不能超过合理范围
                      example: '2024-10-25 10:09:55'
                      pattern: ^\d{4}-\d{2}-\d{2} \d{2}:\d{2}:\d{2}$
                    source:
                      type: string
                      description: 商户来源标识，由 PayAll 分配的唯一标识（如 "SWFTGpt"）
                      example: CatWallet
                      minLength: 1
                      maxLength: 64
                    sign:
                      type: string
                      description: |
                        RSA 签名，使用商户私钥对请求参数（除 sign 字段外）进行签名。
                        
                        签名步骤：
                        1. 将除 sign 外的所有参数按字典序排序
                        2. 转换为 JSON 字符串
                        3. 使用 RSA2048 私钥加密
                        4. Base64 编码
                      example: >-
                        AJdzqyM5SSaewz7TF4M6cYK3NyVzz8tTjNpiGrlt3G+9Whncj2r8zMwNSkjyrvulSwZSIPFLCudIYiMI0BGSAGkLmVIwlZgZBvIRZwWlg0tt6hBvvEedRA1gCIVN4SSm4IKmnoxodOoRLL2MNrrTr7QvcUWZoSyElaCO3JL1cqwbReiAkIsy8kh0JQgZVhKX9fGlP07X3eXwdORr86DerBO/2Mv44XlJ8gTHwut9/pMkgveEh1pTKK0iFMIN00TA9wceRUZuuS7QegtK4hTLqoMz3m1saOYLNdTI7J9Qj1Wjf5SzGj5KIUkdqPK5GCAtzghRRWh4roYCiB0PE65crA==
                    timestamp:
                      type: integer
                      description: 当前时间戳（秒级），与服务器时间差不能超过 60 秒
                      example: 1698203395
                      minimum: 0
            examples:
              basic:
                summary: 基本请求示例
                value:
                  data:
                    account: "user@example.com"
                    expirationData: "2024-10-25 10:09:55"
                    source: "CatWallet"
                    sign: "AJdzqyM5SSaewz7TF4M6cYK3NyVzz8tTjNpiGrlt3G+9Whncj2r8zMwNSkjyrvulSwZSIPFLCudIYiMI0BGSAGkLmVIwlZgZBvIRZwWlg0tt6hBvvEedRA1gCIVN4SSm4IKmnoxodOoRLL2MNrrTr7QvcUWZoSyElaCO3JL1cqwbReiAkIsy8kh0JQgZVhKX9fGlP07X3eXwdORr86DerBO/2Mv44XlJ8gTHwut9/pMkgveEh1pTKK0iFMIN00TA9wceRUZuuS7QegtK4hTLqoMz3m1saOYLNdTI7J9Qj1Wjf5SzGj5KIUkdqPK5GCAtzghRRWh4roYCiB0PE65crA=="
                    timestamp: 1698203395
      responses:
        '200':
          description: 登录成功
          content:
            application/json:
              schema:
                type: object
                properties:
                  code:
                    type: integer
                    description: 响应状态码，200 表示成功
                    example: 200
                  status:
                    type: string
                    description: 响应状态，"true" 表示成功
                    example: 'true'
                  message:
                    type: string
                    description: 响应消息
                    example: success
                  data:
                    type: object
                    properties:
                      userToken:
                        type: string
                        description: 用户访问 Token，后续所有 API 调用都需要在请求头中携带此 Token
                        example: >-
                          eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJ1c2VyX2lkIjoxMjM0LCJ1c2VyX2tleSI6InVzZXJAZXhhbXBsZS5jb20iLCJleHAiOjE2OTgyMDMzOTV9.xxxxx
                      account:
                        type: string
                        description: 用户账号（小写格式）
                        example: user@example.com
                      userId:
                        type: integer
                        description: 用户 ID
                        example: 12345
              examples:
                success:
                  summary: 成功响应示例
                  value:
                    code: 200
                    status: "true"
                    message: "success"
                    data:
                      userToken: "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJ1c2VyX2lkIjoxMjM0LCJ1c2VyX2tleSI6InVzZXJAZXhhbXBsZS5jb20iLCJleHAiOjE2OTgyMDMzOTV9.xxxxx"
                      account: "user@example.com"
                      userId: 12345
        '400':
          description: 请求参数错误
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              examples:
                params_error:
                  summary: 参数错误
                  value:
                    code: 1001
                    status: "false"
                    message: "Params error"
                invalid_signature:
                  summary: 签名验证失败
                  value:
                    code: 1002
                    status: "false"
                    message: "INVALID_SIGNATURE"
                timestamp_error:
                  summary: 时间戳错误
                  value:
                    code: 1001
                    status: "false"
                    message: "Params error"
        '500':
          description: 服务器内部错误
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              examples:
                system_error:
                  summary: 系统错误
                  value:
                    code: 5000
                    status: "false"
                    message: "System Error"
                service_updating:
                  summary: 服务维护中
                  value:
                    code: 99999
                    status: "false"
                    message: "Service Updating"

  /checkLogin:
    get:
      tags:
        - 第三方接入
      summary: 查询登录态是否可用
      description: |
        查询当前 Token 的登录态是否有效。
        
        ## 功能说明
        
        - 用于验证当前使用的 Token 是否仍然有效
        - 如果 Token 有效，返回用户登录信息
        - 如果 Token 失效，返回 401 错误，需要重新调用 `/thirdPartyLogin` 获取新的 Token
        
        ## 使用场景
        
        - 在应用启动时检查 Token 是否有效
        - 在调用其他 API 前验证 Token 状态
        - 定期检查 Token 是否过期，提前刷新
        
        ## 注意事项
        
        - 此接口需要在请求头中携带 Bearer Token
        - 如果返回 401 错误，表示 Token 已失效，需要重新调用 `/thirdPartyLogin` 获取新 Token
      operationId: checkLogin
      security:
        - BearerAuth: []
      responses:
        '200':
          description: Token 有效，登录态可用
          content:
            application/json:
              schema:
                type: object
                properties:
                  code:
                    type: integer
                    description: 响应状态码，200 表示成功
                    example: 200
                  status:
                    type: string
                    description: 响应状态，"true" 表示成功
                    example: 'true'
                  message:
                    type: string
                    description: 响应消息
                    example: success
                  data:
                    type: object
                    properties:
                      is_login:
                        type: boolean
                        description: 是否已登录（始终为 true）
                        example: true
                      account:
                        type: string
                        description: 用户账号（脱敏后的邮箱或钱包地址）
                        example: u***@example.com
                      user_id:
                        type: integer
                        description: 用户 ID
                        example: 12345
              examples:
                success:
                  summary: Token 有效
                  value:
                    code: 200
                    status: "true"
                    message: "success"
                    data:
                      is_login: true
                      account: "u***@example.com"
                      user_id: 12345
        '401':
          description: Token 失效，需要重新登录
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              examples:
                token_expired:
                  summary: Token 已失效
                  value:
                    code: 1003
                    status: "false"
                    message: "Unauthorized"
                token_invalid:
                  summary: Token 无效
                  value:
                    code: 1003
                    status: "false"
                    message: "Invalid token"
        '500':
          description: 服务器内部错误
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'

  /merchant/cards:
    get:
      tags:
        - 卡片管理
      summary: 获取商户可申请的卡片列表
      description: |
        获取商户可以申请的卡片列表。此接口只返回支持 API 对接的卡片（can_apply = 1），
        返回的卡片信息不包含用户相关的状态信息（如申请状态、绑定状态等）。
        
        ## 功能说明
        
        - 支持按卡名关键字搜索
        - 支持多种筛选条件（KYC要求、支付方式、费用类型等）
        - 支持按评分排序（综合评分、福利评分、隐私评分）
        - 无需登录验证（但建议使用 Token 以获取更好的服务）
      operationId: listCardsForMerchant
      security:
        - BearerAuth: []
      parameters:
        - name: keyword
          in: query
          description: 卡名关键字搜索
          required: false
          schema:
            type: string
            example: Bitcoin
        - name: sort_type
          in: query
          description: 排序类型
          required: false
          schema:
            type: string
            enum: [general, benefit, privacy]
            default: general
            example: general
        - name: sort_direction
          in: query
          description: 排序方向
          required: false
          schema:
            type: string
            enum: [asc, desc]
            default: desc
            example: desc
        - name: filters
          in: query
          description: 筛选条件（JSON 字符串）
          required: false
          schema:
            type: string
            example: '{"kyc_required": 0}'
        - name: no_kyc
          in: query
          description: 筛选不需要 KYC 的卡片
          required: false
          schema:
            type: boolean
            example: true
        - name: kyc_required
          in: query
          description: 筛选需要 KYC 的卡片
          required: false
          schema:
            type: boolean
            example: false
        - name: google_pay
          in: query
          description: 筛选支持 Google Pay 的卡片
          required: false
          schema:
            type: boolean
            example: true
        - name: apple_pay
          in: query
          description: 筛选支持 Apple Pay 的卡片
          required: false
          schema:
            type: boolean
            example: true
        - name: wechat
          in: query
          description: 筛选支持微信支付的卡片
          required: false
          schema:
            type: boolean
            example: true
        - name: alipay
          in: query
          description: 筛选支持支付宝的卡片
          required: false
          schema:
            type: boolean
            example: true
        - name: chatgpt
          in: query
          description: 筛选支持 ChatGPT 支付的卡片
          required: false
          schema:
            type: boolean
            example: false
        - name: no_annualfee
          in: query
          description: 筛选无年费的卡片
          required: false
          schema:
            type: boolean
            example: true
        - name: no_issuancefee
          in: query
          description: 筛选无开卡费的卡片
          required: false
          schema:
            type: boolean
            example: true
        - name: no_monthlyfee
          in: query
          description: 筛选无月费的卡片
          required: false
          schema:
            type: boolean
            example: true
        - name: no_transactionfee
          in: query
          description: 筛选无交易费的卡片
          required: false
          schema:
            type: boolean
            example: true
        - name: no_atmfee
          in: query
          description: 筛选无 ATM 费的卡片
          required: false
          schema:
            type: boolean
            example: true
      responses:
        '200':
          description: 获取成功
          content:
            application/json:
              schema:
                type: object
                properties:
                  code:
                    type: integer
                    description: 响应状态码，200 表示成功
                    example: 200
                  status:
                    type: string
                    description: 响应状态，"true" 表示成功
                    example: 'true'
                  message:
                    type: string
                    description: 响应消息
                    example: success
                  data:
                    type: array
                    description: 卡片列表
                    items:
                      $ref: '#/components/schemas/CardInfo'
              examples:
                success:
                  summary: 成功响应示例
                  value:
                    code: 200
                    status: "true"
                    message: "success"
                    data:
                      - id: 1
                        card_name: "Bitcoin Card"
                        vendor: "BitPay"
                        card_type: "Virtual"
                        kyc_required: 0
                        based_crypto: "BTC"
                        cashback: "2%"
                        fees: '{"annualFee": {"value": 0}, "issuanceFee": {"value": 0}}'
                        spending_limits: '{"daily": 10000, "monthly": 100000}'
                        google_pay_support: 1
                        apple_wallet_support: 1
                        wechat_pay_support: 0
                        alipay_support: 0
                        chatgpt_pay_support: 0
                        summary: "支持比特币的虚拟卡片"
                        intro: "详细的卡片介绍信息"
                        application_url: "https://example.com/apply"
                        card_image_large: "https://example.com/images/card_large.jpg"
                        vendor_logo: "https://example.com/images/vendor_logo.png"
                        card_image_thumbnail: "https://example.com/images/card_thumb.jpg"
                        general_ratings: 4.5
                        benefit_ratings: 4.0
                        privacy_ratings: 4.8
        '400':
          description: 请求参数错误
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              examples:
                params_error:
                  summary: 参数错误
                  value:
                    code: 1001
                    status: "false"
                    message: "Params error"
        '401':
          description: 未授权（Token 无效或过期）
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              examples:
                unauthorized:
                  summary: 未授权
                  value:
                    code: 1003
                    status: "false"
                    message: "Unauthorized"
        '500':
          description: 服务器内部错误
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              examples:
                system_error:
                  summary: 系统错误
                  value:
                    code: 5000
                    status: "false"
                    message: "System Error"

  /cards/getCardbinSettings:
    get:
      tags:
        - 卡片管理
      summary: 获取发卡商支持的卡片类型
      description: |
        获取指定发卡商支持的卡片类型配置信息。
        
        ## 功能说明
        
        - 返回指定卡片ID（card_id）对应的发卡商支持的所有卡片类型
        - 每个卡片类型包含：卡片BIN号、支持的国家、支持的币种、费用信息、限额信息等
        - 用于开卡时选择卡片类型和配置
        
        ## 使用场景
        
        - 在开卡前查询可用的卡片类型
        - 获取卡片类型的详细配置信息（费用、限额、支持的国家和币种等）
        - 根据用户需求选择合适的卡片类型
        
        ## 注意事项
        
        - `card_id` 参数可选，默认为 "23"（Bit2Go）
        - 不同环境（测试/生产）可能返回不同的配置
      operationId: getCardbinSettings
      security:
        - BearerAuth: []
      parameters:
        - name: card_id
          in: query
          description: 卡片ID（可选，默认"23"）
          required: false
          schema:
            type: string
            default: "23"
            example: '23'
      responses:
        '200':
          description: 查询成功
          content:
            application/json:
              schema:
                type: object
                properties:
                  code:
                    type: integer
                    description: 响应状态码，200 表示成功
                    example: 200
                  status:
                    type: string
                    description: 响应状态，"true" 表示成功
                    example: 'true'
                  message:
                    type: string
                    description: 响应消息
                    example: success
                  data:
                    type: array
                    description: 卡片类型配置列表
                    items:
                      $ref: '#/components/schemas/CardbinSetting'
              examples:
                success:
                  summary: 查询成功
                  value:
                    code: 200
                    status: "true"
                    message: "success"
                    data:
                      - id: 112
                        holder_config:
                          flag: 1
                          country:
                            - "HKG"
                          billInfoFlag: 0
                          nativeNameFlag: 0
                        can_diy_date: "1"
                        days_range: "699"
                        min_days: "32"
                        ends_of_month: true
                        phone_prefix_limit: false
                        phone_prefix_range: []
                        phone_prefix_country_range: []
                        card_fee:
                          transaction_fee: 0.5
                          active_fee: 10.0
                          transfer_in_fee:
                            rate: 0
                            fixed_fee: 0
                          apple_pay_fee: 0.5
                          fee_currency: "USD"
                        card_limit:
                          txn_max_amount: 10000
                          daily_max_amount: 50000
                          currency: "USD"
                        card_bin: "525847"
                        country: "HKG"
                        currency:
                          - "USD"
                          - "SGD"
                          - "HKD"
                          - "MYR"
                          - "THB"
                          - "JPY"
                          - "CAD"
                          - "AUD"
                          - "IDR"
                          - "NZD"
                          - "GBP"
                          - "EUR"
                        usage_times: "1"
                        organization: "mastercard"
                        fee_currency: "USD"
        '400':
          description: 请求参数错误
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '401':
          description: 未授权
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '500':
          description: 服务器内部错误
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'

  /cards/checkCanApply:
    post:
      tags:
        - 卡片管理
      summary: 申请前判断卡片是否可以申请
      description: |
        检查指定卡片是否可以申请，返回申请条件和状态信息。
        
        ## 功能说明
        
        - 检查卡片是否支持 API 对接（can_apply 状态）
        - 检查是否有可绑定的卡片
        - 检查商户余额是否充足（如果没有可绑定卡片）
        - 返回申请金额、活跃卡片数量等信息
        
        ## 使用场景
        
        - 在用户申请卡片前，先检查卡片是否可以申请
        - 根据返回的信息决定是否允许用户申请
        - 获取申请所需的最低金额
        
        ## 返回字段说明
        
        - `can_apply`: 卡片是否支持 API 对接（0-不支持，1-支持）
        - `can_bind_card`: 是否可以绑卡（综合考虑可绑定卡片和商户余额）
        - `has_bindable_cards`: 是否有可绑定的卡片
        - `bindable_cards_count`: 可绑定卡片数量
        - `card_binding_id`: 如果有可绑定卡片，返回第一张卡片的绑定ID
        - `apply_amount`: 申请所需的最低金额
        - `active_card_count`: 用户已申请的该类型卡片数量
      operationId: checkCanApply
      security:
        - BearerAuth: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
                - card_id
              properties:
                card_id:
                  type: string
                  description: 卡片ID（PayAll卡片ID）
                  example: '39'
            examples:
              check_card:
                summary: 检查卡片是否可以申请
                value:
                  card_id: "39"
      responses:
        '200':
          description: 查询成功
          content:
            application/json:
              schema:
                type: object
                properties:
                  code:
                    type: integer
                    description: 响应状态码，200 表示成功
                    example: 200
                  status:
                    type: string
                    description: 响应状态，"true" 表示成功
                    example: 'true'
                  message:
                    type: string
                    description: 响应消息
                    example: success
                  data:
                    $ref: '#/components/schemas/CanApplyInfo'
              examples:
                success_can_apply:
                  summary: 可以申请
                  value:
                    code: 200
                    status: "true"
                    message: "success"
                    data:
                      card_id: "39"
                      can_apply: 1
                      card_name: "PayAll Crypto Card"
                      is_bound: false
                      card_binding_id: 12345
                      has_bindable_cards: true
                      bindable_cards_count: 5
                      can_bind_card: true
                      open_card_address: {}
                      apply_amount: "30"
                      can_use_qrcode_charge: true
                      active_card_count: 2
                success_cannot_apply:
                  summary: 不可以申请
                  value:
                    code: 200
                    status: "true"
                    message: "success"
                    data:
                      card_id: "23"
                      can_apply: 0
                      card_name: "PayAll Crypto Card"
                      is_bound: false
                      card_binding_id: null
                      has_bindable_cards: false
                      bindable_cards_count: 0
                      can_bind_card: false
                      open_card_address: {}
                      apply_amount: "21"
                      can_use_qrcode_charge: true
        '400':
          description: 请求参数错误
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '401':
          description: 未授权
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '404':
          description: 卡片不存在
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '500':
          description: 服务器内部错误
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'

  /cards/binding:
    post:
      tags:
        - 卡片管理
      summary: 申请卡片
      description: |
        申请/绑定卡片接口，用于用户申请新的卡片。
        
        ## 功能说明
        
        - 用户通过此接口申请新的卡片
        - 如果卡片支持 API 对接（can_apply = 1），会直接绑定卡片并返回卡片信息
        - 如果卡片不支持 API 对接（can_apply = 0），会创建待确认的绑定记录
        
        ## 使用场景
        
        - 用户在开卡前需要先申请卡片
        - 申请成功后，卡片会被绑定到用户账户
        
        ## 注意事项
        
        - 申请前建议先调用 `/cards/checkCanApply` 接口检查卡片是否可以申请
        - 申请成功后，可以通过 `/cards/getCardDetail` 接口获取卡片详细信息
      operationId: bindCard
      security:
        - BearerAuth: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
                - card_id
              properties:
                card_id:
                  type: string
                  description: 卡片ID（PayAll卡片ID）
                  example: '39'
            examples:
              bind_card:
                summary: 申请卡片
                value:
                  card_id: "39"
      responses:
        '200':
          description: 申请成功
          content:
            application/json:
              schema:
                type: object
                properties:
                  code:
                    type: integer
                    description: 响应状态码，200 表示成功
                    example: 200
                  status:
                    type: string
                    description: 响应状态，"true" 表示成功
                    example: 'true'
                  message:
                    type: string
                    description: 响应消息
                    example: success
                  data:
                    type: object
                    description: 卡片信息（API对接卡片）或绑定状态（非API对接卡片）
                    properties:
                      card_number:
                        type: string
                        description: 卡片号（API对接卡片返回）
                        example: '4111111111111111'
                      brand:
                        type: string
                        description: 卡片品牌（API对接卡片返回）
                        example: Master
                      currency:
                        type: string
                        description: 卡片币种（API对接卡片返回）
                        example: USD
                      nickname:
                        type: string
                        nullable: true
                        description: 卡片昵称（API对接卡片返回）
                        example: My Card
                      issuer_name:
                        type: string
                        nullable: true
                        description: 发卡商名称（API对接卡片返回）
                        example: PayAll
                      binding_time:
                        type: string
                        format: date-time
                        nullable: true
                        description: 绑定时间（API对接卡片返回）
                        example: '2024-10-25T10:30:00'
                      status:
                        type: string
                        description: 卡片状态（API对接卡片返回）
                        example: active
                      binding_status:
                        type: string
                        description: 绑定状态（API对接卡片返回）
                        example: active
                      card_id:
                        type: string
                        description: 卡片ID（非API对接卡片返回）
                        example: '39'
                      card_name:
                        type: string
                        description: 卡片名称（非API对接卡片返回）
                        example: PayAll Crypto Card
                      vendor:
                        type: string
                        description: 供应商名称（非API对接卡片返回）
                        example: MIPAY
              examples:
                success_api_card:
                  summary: API对接卡片申请成功
                  value:
                    code: 200
                    status: "true"
                    message: "success"
                    data:
                      card_number: "4111111111111111"
                      brand: "Master"
                      currency: "USD"
                      nickname: "My Card"
                      issuer_name: "PayAll"
                      binding_time: "2024-10-25T10:30:00"
                      status: "active"
                      binding_status: "active"
                success_pending_card:
                  summary: 非API对接卡片申请成功（待确认）
                  value:
                    code: 200
                    status: "true"
                    message: "success"
                    data:
                      card_id: "39"
                      card_name: "PayAll Crypto Card"
                      vendor: "MIPAY"
                      binding_status: "pending"
        '400':
          description: 请求参数错误
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '401':
          description: 未授权
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '500':
          description: 服务器内部错误
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'

  /cards/feeQuote:
    post:
      tags:
        - 卡片管理
      summary: 查询开卡和充值汇率
      description: |
        查询开卡和充值相关的汇率及手续费信息。
        
        ## 功能说明
        
        - **开卡汇率** (`charge_type: OPEN_CARD`): 查询开卡所需的手续费和汇率信息
        - **卡片余额充值汇率** (`charge_type: CARD_CHARGE`): 查询卡片余额充值的手续费和汇率信息
        - **卡片提现汇率** (`charge_type: CARD_WITHDRAW`): 查询卡片提现的手续费和汇率信息
        
        ## 使用场景
        
        - 在用户进行开卡或充值操作前，可以先调用此接口查询相关费用和汇率
        - 不同卡片（card_id）可能使用不同的费率计算方式
        - card_id=39 (MiPay) 使用统一的费率管理
        - 其他卡片使用 Bit2Go 的费率计算
        
        ## 注意事项
        
        - 卡片余额充值和提现场景必须提供 `card_bin` 参数
        - 充值场景建议提供 `amount` 参数以获取准确的费率计算
      operationId: getCardFeeQuote
      security:
        - BearerAuth: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
                - charge_type
              properties:
                charge_type:
                  type: string
                  description: 充值类型
                  enum: [OPEN_CARD, CARD_CHARGE, CARD_WITHDRAW]
                  example: OPEN_CARD
                card_bin:
                  type: string
                  description: 卡片BIN号（卡片余额充值和提现时必填）
                  example: '411111'
                amount:
                  type: string
                  description: 金额（充值场景建议提供，用于计算准确的费率）
                  example: '100'
                chain:
                  type: string
                  description: 链名称（可选，默认BSC）
                  example: BSC
                card_id:
                  type: string
                  description: 卡片ID（可选，默认"23"）
                  example: '39'
            examples:
              open_card:
                summary: 查询开卡汇率
                value:
                  charge_type: "OPEN_CARD"
                  card_id: "39"
              card_charge:
                summary: 查询卡片余额充值汇率
                value:
                  charge_type: "CARD_CHARGE"
                  card_bin: "411111"
                  amount: "100"
                  chain: "BSC"
                  card_id: "23"
              card_withdraw:
                summary: 查询卡片提现汇率
                value:
                  charge_type: "CARD_WITHDRAW"
                  card_bin: "411111"
                  amount: "50"
                  chain: "TRON"
      responses:
        '200':
          description: 查询成功
          content:
            application/json:
              schema:
                type: object
                properties:
                  code:
                    type: integer
                    description: 响应状态码，200 表示成功
                    example: 200
                  status:
                    type: string
                    description: 响应状态，"true" 表示成功
                    example: 'true'
                  message:
                    type: string
                    description: 响应消息
                    example: success
                  data:
                    type: object
                    properties:
                      fee_info:
                        $ref: '#/components/schemas/FeeQuoteInfo'
              examples:
                success_open_card:
                  summary: 开卡汇率查询成功
                  value:
                    code: 200
                    status: "true"
                    message: "success"
                    data:
                      fee_info:
                        fee: 10
                        open_card_fee: 10
                        recharge_fee: 0.018
                        fee_currency: "USDT"
                        wallet_amount: 30
                        wallet_currency: "USDT"
                        card_amount: 20
                        card_currency: "USD"
                        conversion_steps:
                          - from_currency: "USDT"
                            to_currency: "USD"
                            rate: "1"
                success_card_charge:
                  summary: 卡片余额充值汇率查询成功
                  value:
                    code: 200
                    status: "true"
                    message: "success"
                    data:
                      fee_info:
                        fee: 1.8
                        fee_currency: "USDT"
                        wallet_amount: 100
                        wallet_currency: "USDT"
                        card_amount: 98.2
                        card_currency: "USD"
                        conversion_steps:
                          - from_currency: "USDT"
                            to_currency: "USD"
                            rate: "1"
        '400':
          description: 请求参数错误
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '401':
          description: 未授权
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '500':
          description: 服务器内部错误
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'

  /charge/preCharge:
    post:
      tags:
        - 卡片管理
      summary: 预开卡充值
      description: |
        预开卡充值接口，用于开卡或卡片余额充值的预充值操作。
        
        ## 功能说明
        
        - **开卡充值** (`charge_type: OPEN_CARD`): 用于新卡开卡时的充值
          - 开卡时通常没有 `card_binding_id`，需要提供 `card_issue_info` 用于开卡
          - `card_binding_id` 在开卡场景下为可选参数
        - **卡片余额充值** (`charge_type: CARD_CHARGE`): 用于已绑定卡片的余额充值
          - 必须提供 `card_binding_id`
        
        ## 使用流程
        
        1. 调用此接口进行预充值，获取 `order_id`
        2. 调用 `/charge/getChargeQrCode` 获取充值地址和二维码
        3. 用户向充值地址转账
        4. 系统自动处理充值并回调商户
      operationId: preCharge
      security:
        - BearerAuth: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
                - charge_type
                - card_id
              properties:
                charge_type:
                  type: string
                  description: 充值类型
                  enum: [OPEN_CARD, CARD_CHARGE]
                  example: OPEN_CARD
                card_id:
                  type: string
                  description: 卡片ID
                  example: '39'
                card_binding_id:
                  type: string
                  description: 卡片绑定ID（开卡时不需要传入，卡片余额充值时必填）
                  example: '12345'
                card_issue_info:
                  type: object
                  description: 开卡信息（开卡时必填，用于新卡开卡）
                  properties:
                    card_bin:
                      type: string
                      description: 卡片BIN号
                      example: '411111'
                    expiry_date:
                      type: string
                      description: 卡片过期日期，格式为 "YYYY-MM"
                      example: '2025-12'
                    card_holder_info:
                      type: object
                      description: 持卡人信息
                      required:
                        - first_name
                        - last_name
                        - email
                        - phone
                        - phone_prefix
                      properties:
                        first_name:
                          type: string
                          description: 名
                          example: John
                        last_name:
                          type: string
                          description: 姓
                          example: Doe
                        email:
                          type: string
                          description: 邮箱地址
                          example: john.doe@example.com
                        phone:
                          type: string
                          description: 手机号码
                          example: '1234567890'
                        phone_prefix:
                          type: string
                          description: 手机号码前缀（国家代码）
                          example: '+1'
            examples:
              open_card:
                summary: 开卡充值（新开卡）
                value:
                  charge_type: "OPEN_CARD"
                  card_id: "39"
                  card_issue_info:
                    card_bin: "411111"
                    expiry_date: "2025-12"
                    card_holder_info:
                      first_name: "John"
                      last_name: "Doe"
                      email: "john.doe@example.com"
                      phone: "1234567890"
                      phone_prefix: "+1"
              card_charge:
                summary: 卡片余额充值
                value:
                  charge_type: "CARD_CHARGE"
                  card_id: "39"
                  card_binding_id: "12345"
      responses:
        '200':
          description: 预充值成功
          content:
            application/json:
              schema:
                type: object
                properties:
                  code:
                    type: integer
                    description: 响应状态码，200 表示成功
                    example: 200
                  status:
                    type: string
                    description: 响应状态，"true" 表示成功
                    example: 'true'
                  message:
                    type: string
                    description: 响应消息
                    example: success
                  data:
                    type: object
                    description: 预充值结果（开卡时返回order_id，卡片余额充值时返回true）
                    properties:
                      order_id:
                        type: string
                        description: 订单ID（开卡场景返回）
                        example: open_card_12345_39_abc123
              examples:
                success_open_card:
                  summary: 开卡预充值成功
                  value:
                    code: 200
                    status: "true"
                    message: "success"
                    data:
                      order_id: "open_card_12345_39_abc123"
                success_card_charge:
                  summary: 卡片余额预充值成功
                  value:
                    code: 200
                    status: "true"
                    message: "success"
                    data: true
        '400':
          description: 请求参数错误
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '401':
          description: 未授权
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '500':
          description: 服务器内部错误
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'

  /charge/getChargeQrCode:
    post:
      tags:
        - 卡片管理
      summary: 获取充值地址和二维码
      description: |
        获取充值地址和二维码接口，用于开卡充值或卡片余额充值。
        
        ## 功能说明
        
        - 必须先调用 `/charge/preCharge` 接口进行预充值
        - 返回充值地址、最小充值金额、过期时间和二维码（Base64编码）
        - 币种代码（coin_code）需要传入 USDT 相关的币种（如 USDT_TRC20, USDT_ERC20, USDT_BSC 等）
        
        ## 使用流程
        
        1. 调用 `/charge/preCharge` 进行预充值
        2. 调用此接口获取充值地址和二维码
        3. 用户向充值地址转账（金额需大于等于最小充值金额）
        4. 系统自动处理充值并回调商户
      operationId: getChargeQrCode
      security:
        - BearerAuth: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
                - coin_code
                - chain
                - charge_type
                - card_id
              properties:
                coin_code:
                  type: string
                  description: 币种代码，需要传入 USDT 相关的币种（如 USDT_TRC20, USDT_ERC20, USDT_BSC 等）
                  example: USDT_TRC20
                chain:
                  type: string
                  description: 链名称（如 TRON, ETHEREUM, BSC 等）
                  example: TRON
                charge_type:
                  type: string
                  description: 充值类型
                  enum: [OPEN_CARD, CARD_CHARGE]
                  example: OPEN_CARD
                card_id:
                  type: string
                  description: 卡片ID
                  example: '39'
                card_binding_id:
                  type: string
                  description: 卡片绑定ID（卡片余额充值时必填，开卡时不需要传入）
                  example: '12345'
            examples:
              open_card:
                summary: 开卡充值获取二维码
                value:
                  coin_code: "USDT_TRC20"
                  chain: "TRON"
                  charge_type: "OPEN_CARD"
                  card_id: "39"
              card_charge:
                summary: 卡片余额充值获取二维码
                value:
                  coin_code: "USDT_TRC20"
                  chain: "TRON"
                  charge_type: "CARD_CHARGE"
                  card_id: "39"
                  card_binding_id: "12345"
      responses:
        '200':
          description: 获取成功
          content:
            application/json:
              schema:
                type: object
                properties:
                  code:
                    type: integer
                    description: 响应状态码，200 表示成功
                    example: 200
                  status:
                    type: string
                    description: 响应状态，"true" 表示成功
                    example: 'true'
                  message:
                    type: string
                    description: 响应消息
                    example: success
                  data:
                    $ref: '#/components/schemas/ChargeQrCodeInfo'
              examples:
                success:
                  summary: 成功响应示例
                  value:
                    code: 200
                    status: "true"
                    message: "success"
                    data:
                      deposit_address: "TXYZabcdefghijklmnopqrstuvwxyz123456"
                      min_depositAmt: "10.5"
                      expired_time: "2024-12-25 10:30:00"
                      qr_code: "iVBORw0KGgoAAAANSUhEUgAA..."
        '400':
          description: 请求参数错误
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '401':
          description: 未授权
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '500':
          description: 服务器内部错误
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'

  /cards/uploadTransaction:
    post:
      tags:
        - 卡片管理
      summary: 上传交易Hash（插件钱包转账开卡）
      description: |
        上传交易Hash接口，用于插件钱包转账开卡场景。
        
        ## 功能说明
        
        - 当用户通过插件钱包（如MetaMask、Trust Wallet等）进行转账开卡时，需要调用此接口上传交易Hash
        - 系统会记录该交易信息，用于后续的开卡处理
        - 上传成功后，可以通过 `/cards/getTransactionByHash` 接口查询开卡状态
        
        ## 使用场景
        
        - 用户通过插件钱包向充值地址转账后，需要上传交易Hash
        - 适用于开卡场景，需要提供完整的交易信息
        
        ## 注意事项
        
        - 必须提供 `transaction_hash`、`card_id`、`chain`、`amount`、`from_address`、`to_address` 等必填参数
        - `card_binding_id` 在开卡场景下通常为空
      operationId: uploadCardTransaction
      security:
        - BearerAuth: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
                - transaction_hash
                - card_id
                - chain
                - amount
                - from_address
                - to_address
              properties:
                transaction_hash:
                  type: string
                  description: 交易哈希（必填）
                  example: 0x1234567890abcdef...
                card_id:
                  type: string
                  description: 关联的卡片ID（必填）
                  example: '39'
                card_binding_id:
                  type: string
                  description: 卡片绑定ID（开卡时通常为空）
                  example: null
                chain:
                  type: string
                  description: 区块链ID（必填，如 TRON, ETHEREUM, BSC 等）
                  example: TRON
                token_address:
                  type: string
                  description: 代币合约地址（可选，原生币为null）
                  example: null
                token_symbol:
                  type: string
                  description: 代币符号（可选）
                  example: USDT
                token_name:
                  type: string
                  description: 代币名称（可选）
                  example: Tether USD
                token_decimals:
                  type: integer
                  description: 代币精度（可选，默认18）
                  example: 18
                amount:
                  type: string
                  description: 转账金额（必填，原始金额字符串）
                  example: '1000000000000000000'
                amount_display:
                  type: string
                  description: 显示金额（可选，用户友好的显示金额）
                  example: '1.0'
                from_address:
                  type: string
                  description: 发送方地址（必填）
                  example: 0x1234567890abcdef...
                to_address:
                  type: string
                  description: 接收方地址（必填，充值地址）
                  example: TXYZabcdefghijklmnopqrstuvwxyz123456
                transaction_status:
                  type: string
                  description: 交易状态（可选，默认pending）
                  enum: [pending, success, failed]
                  example: pending
                block_number:
                  type: integer
                  description: 区块号（可选）
                  example: 12345678
                block_hash:
                  type: string
                  description: 区块哈希（可选）
                  example: 0xabcdef...
                gas_used:
                  type: string
                  description: 实际消耗的Gas（可选）
                  example: '21000'
                gas_price:
                  type: string
                  description: Gas价格（可选）
                  example: '20000000000'
                gas_fee:
                  type: string
                  description: Gas费用（可选）
                  example: '0.00042'
                transaction_fee:
                  type: string
                  description: 交易费用（可选）
                  example: '0.00042'
                confirmation_count:
                  type: integer
                  description: 确认数（可选，默认0）
                  example: 0
                transaction_type:
                  type: string
                  description: 交易类型（可选，默认transfer）
                  example: deposit
                description:
                  type: string
                  description: 交易描述（可选）
                  example: Open card transaction
                transaction_time:
                  type: integer
                  description: 交易时间戳（可选）
                  example: 1698203395
            examples:
              open_card_transaction:
                summary: 开卡交易上传
                value:
                  transaction_hash: "0x1234567890abcdef..."
                  card_id: "39"
                  card_binding_id: null
                  chain: "TRON"
                  token_address: null
                  token_symbol: "USDT"
                  token_name: "Tether USD"
                  token_decimals: 18
                  amount: "30000000"
                  amount_display: "30.0"
                  from_address: "TXYZabcdefghijklmnopqrstuvwxyz123456"
                  to_address: "TXYZabcdefghijklmnopqrstuvwxyz123456"
                  transaction_status: "pending"
                  transaction_type: "deposit"
      responses:
        '200':
          description: 上传成功
          content:
            application/json:
              schema:
                type: object
                properties:
                  code:
                    type: integer
                    description: 响应状态码，200 表示成功
                    example: 200
                  status:
                    type: string
                    description: 响应状态，"true" 表示成功
                    example: 'true'
                  message:
                    type: string
                    description: 响应消息
                    example: success
                  data:
                    type: object
                    properties:
                      transaction_id:
                        type: integer
                        description: 交易记录ID
                        example: 12345
                      message:
                        type: string
                        description: 成功消息
                        example: Open card transaction uploaded successfully
              examples:
                success:
                  summary: 上传成功
                  value:
                    code: 200
                    status: "true"
                    message: "success"
                    data:
                      transaction_id: 12345
                      message: "Open card transaction uploaded successfully"
        '400':
          description: 请求参数错误
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '401':
          description: 未授权
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '500':
          description: 服务器内部错误
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'

  /cards/getTransactionByHash:
    post:
      tags:
        - 卡片管理
      summary: 根据交易Hash获取开卡状态
      description: |
        根据交易Hash获取开卡状态接口，用于查询插件钱包转账开卡的处理状态。
        
        ## 功能说明
        
        - 通过交易Hash查询开卡交易的处理状态
        - 返回完整的交易信息，包括交易状态、区块信息、Gas信息等
        - 如果交易已处理（processed.status = 1），还会返回卡片信息
        
        ## 使用场景
        
        - 用户上传交易Hash后，可以定期调用此接口查询开卡状态
        - 用于轮询查询开卡是否成功
        
        ## 交易状态说明
        
        - `pending`: 交易待处理
        - `success`: 交易成功
        - `failed`: 交易失败
        
        ## 处理状态说明
        
        - `processed.status = 0`: 交易未处理
        - `processed.status = 1`: 交易已处理（开卡成功）
      operationId: getCardTransactionByHash
      security:
        - BearerAuth: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
                - transaction_hash
              properties:
                transaction_hash:
                  type: string
                  description: 交易哈希（必填）
                  example: 0x1234567890abcdef...
            examples:
              query_status:
                summary: 查询开卡状态
                value:
                  transaction_hash: "0x1234567890abcdef..."
      responses:
        '200':
          description: 查询成功
          content:
            application/json:
              schema:
                type: object
                properties:
                  code:
                    type: integer
                    description: 响应状态码，200 表示成功
                    example: 200
                  status:
                    type: string
                    description: 响应状态，"true" 表示成功
                    example: 'true'
                  message:
                    type: string
                    description: 响应消息
                    example: success
                  data:
                    $ref: '#/components/schemas/CardTransactionInfo'
              examples:
                success:
                  summary: 查询成功
                  value:
                    code: 200
                    status: "true"
                    message: "success"
                    data:
                      id: 12345
                      transaction_hash: "0x1234567890abcdef..."
                      transaction_hash_url: "https://tronscan.org/#/transaction/0x1234567890abcdef..."
                      user_id: 123
                      card_id: "39"
                      card_binding_id: null
                      chain: "TRON"
                      token_info:
                        address: null
                        symbol: "USDT"
                        name: "Tether USD"
                        decimals: 18
                      amount:
                        raw: "30000000"
                        display: "30.0"
                      addresses:
                        from: "TXYZabcdefghijklmnopqrstuvwxyz123456"
                        to: "TXYZabcdefghijklmnopqrstuvwxyz123456"
                      status: "success"
                      block_info:
                        number: 12345678
                        hash: "0xabcdef..."
                        confirmation_count: 12
                      gas_info:
                        used: "21000"
                        price: "20000000000"
                        fee: "0.00042"
                        transaction_fee: "0.00042"
                      transaction_type: "deposit"
                      description: "Open card transaction"
                      timestamps:
                        created_at: "2024-10-25T10:30:00"
                        updated_at: "2024-10-25T10:35:00"
                        transaction_time: 1698203395
                      processed:
                        status: 1
                        processed_at: "2024-10-25T10:35:00"
                      card_info:
                        card_number: "4111111111111111"
                        brand: "Visa"
                        currency: "USD"
                        nickname: "My Card"
                        issuer_name: "PayAll"
                        binding_time: "2024-10-25T10:35:00"
                        status: "active"
                        binding_status: "active"
                        card_balance: "20.0"
        '400':
          description: 请求参数错误
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '401':
          description: 未授权
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '404':
          description: 交易不存在
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '500':
          description: 服务器内部错误
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'

  /wallet/uploadTransaction:
    post:
      tags:
        - 卡片管理
      summary: 上传交易Hash（插件钱包转账充值）
      description: |
        上传交易Hash接口，用于插件钱包转账充值场景。
        
        ## 功能说明
        
        - 当用户通过插件钱包（如MetaMask、Trust Wallet等）进行转账充值时，需要调用此接口上传交易Hash
        - 系统会记录该交易信息，用于后续的充值处理
        - 上传成功后，可以通过 `/wallet/getTransactionByHash` 接口查询充值状态
        
        ## 使用场景
        
        - 用户通过插件钱包向充值地址转账后，需要上传交易Hash
        - 适用于卡片余额充值场景，需要提供 `card_binding_id`
        
        ## 注意事项
        
        - 必须提供 `transaction_hash`、`card_id`、`card_binding_id`、`chain`、`amount`、`from_address`、`to_address` 等必填参数
        - `card_binding_id` 在充值场景下为必填参数
      operationId: uploadWalletTransaction
      security:
        - BearerAuth: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
                - transaction_hash
                - card_id
                - card_binding_id
                - chain
                - amount
                - from_address
                - to_address
              properties:
                transaction_hash:
                  type: string
                  description: 交易哈希（必填）
                  example: 0x1234567890abcdef...
                card_id:
                  type: string
                  description: 关联的卡片ID（必填）
                  example: '39'
                card_binding_id:
                  type: string
                  description: 卡片绑定ID（必填）
                  example: '12345'
                chain:
                  type: string
                  description: 区块链ID（必填，如 TRON, ETHEREUM, BSC 等）
                  example: TRON
                token_address:
                  type: string
                  description: 代币合约地址（可选，原生币为null）
                  example: null
                token_symbol:
                  type: string
                  description: 代币符号（可选）
                  example: USDT
                token_name:
                  type: string
                  description: 代币名称（可选）
                  example: Tether USD
                token_decimals:
                  type: integer
                  description: 代币精度（可选，默认18）
                  example: 18
                amount:
                  type: string
                  description: 转账金额（必填，原始金额字符串）
                  example: '1000000000000000000'
                amount_display:
                  type: string
                  description: 显示金额（可选，用户友好的显示金额）
                  example: '100.0'
                from_address:
                  type: string
                  description: 发送方地址（必填）
                  example: 0x1234567890abcdef...
                to_address:
                  type: string
                  description: 接收方地址（必填，充值地址）
                  example: TXYZabcdefghijklmnopqrstuvwxyz123456
                transaction_status:
                  type: string
                  description: 交易状态（可选，默认pending）
                  enum: [pending, success, failed]
                  example: pending
                block_number:
                  type: integer
                  description: 区块号（可选）
                  example: 12345678
                block_hash:
                  type: string
                  description: 区块哈希（可选）
                  example: 0xabcdef...
                gas_used:
                  type: string
                  description: 实际消耗的Gas（可选）
                  example: '21000'
                gas_price:
                  type: string
                  description: Gas价格（可选）
                  example: '20000000000'
                gas_fee:
                  type: string
                  description: Gas费用（可选）
                  example: '0.00042'
                transaction_fee:
                  type: string
                  description: 交易费用（可选）
                  example: '0.00042'
                confirmation_count:
                  type: integer
                  description: 确认数（可选，默认0）
                  example: 0
                transaction_type:
                  type: string
                  description: 交易类型（可选，默认transfer）
                  example: deposit
                description:
                  type: string
                  description: 交易描述（可选）
                  example: Card recharge transaction
                transaction_time:
                  type: integer
                  description: 交易时间戳（可选）
                  example: 1698203395
            examples:
              recharge_transaction:
                summary: 充值交易上传
                value:
                  transaction_hash: "0x1234567890abcdef..."
                  card_id: "39"
                  card_binding_id: "12345"
                  chain: "TRON"
                  token_address: null
                  token_symbol: "USDT"
                  token_name: "Tether USD"
                  token_decimals: 18
                  amount: "100000000"
                  amount_display: "100.0"
                  from_address: "TXYZabcdefghijklmnopqrstuvwxyz123456"
                  to_address: "TXYZabcdefghijklmnopqrstuvwxyz123456"
                  transaction_status: "pending"
                  transaction_type: "deposit"
      responses:
        '200':
          description: 上传成功
          content:
            application/json:
              schema:
                type: object
                properties:
                  code:
                    type: integer
                    description: 响应状态码，200 表示成功
                    example: 200
                  status:
                    type: string
                    description: 响应状态，"true" 表示成功
                    example: 'true'
                  message:
                    type: string
                    description: 响应消息
                    example: success
                  data:
                    type: object
                    properties:
                      transaction_id:
                        type: integer
                        description: 交易记录ID
                        example: 12345
                      message:
                        type: string
                        description: 成功消息
                        example: Wallet transaction uploaded successfully
              examples:
                success:
                  summary: 上传成功
                  value:
                    code: 200
                    status: "true"
                    message: "success"
                    data:
                      transaction_id: 12345
                      message: "Wallet transaction uploaded successfully"
        '400':
          description: 请求参数错误
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '401':
          description: 未授权
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '500':
          description: 服务器内部错误
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'

  /wallet/getTransactionByHash:
    post:
      tags:
        - 卡片管理
      summary: 根据交易Hash获取充值状态
      description: |
        根据交易Hash获取充值状态接口，用于查询插件钱包转账充值的处理状态。
        
        ## 功能说明
        
        - 通过交易Hash查询充值交易的处理状态
        - 返回完整的交易信息，包括交易状态、区块信息、Gas信息等
        - 用于轮询查询充值是否成功
        
        ## 使用场景
        
        - 用户上传交易Hash后，可以定期调用此接口查询充值状态
        - 用于轮询查询充值是否成功
        
        ## 交易状态说明
        
        - `pending`: 交易待处理
        - `success`: 交易成功
        - `failed`: 交易失败
        
        ## 处理状态说明
        
        - `processed.status = 0`: 交易未处理
        - `processed.status = 1`: 交易已处理（充值成功）
      operationId: getWalletTransactionByHash
      security:
        - BearerAuth: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
                - transaction_hash
              properties:
                transaction_hash:
                  type: string
                  description: 交易哈希（必填）
                  example: 0x1234567890abcdef...
            examples:
              query_status:
                summary: 查询充值状态
                value:
                  transaction_hash: "0x1234567890abcdef..."
      responses:
        '200':
          description: 查询成功
          content:
            application/json:
              schema:
                type: object
                properties:
                  code:
                    type: integer
                    description: 响应状态码，200 表示成功
                    example: 200
                  status:
                    type: string
                    description: 响应状态，"true" 表示成功
                    example: 'true'
                  message:
                    type: string
                    description: 响应消息
                    example: success
                  data:
                    $ref: '#/components/schemas/WalletTransactionInfo'
              examples:
                success:
                  summary: 查询成功
                  value:
                    code: 200
                    status: "true"
                    message: "success"
                    data:
                      id: 12345
                      transaction_hash: "0x1234567890abcdef..."
                      transaction_hash_url: "https://tronscan.org/#/transaction/0x1234567890abcdef..."
                      user_id: 123
                      card_id: "39"
                      card_binding_id: 12345
                      chain: "TRON"
                      token_info:
                        address: null
                        symbol: "USDT"
                        name: "Tether USD"
                        decimals: 18
                      amount:
                        raw: "100000000"
                        display: "100.0"
                      addresses:
                        from: "TXYZabcdefghijklmnopqrstuvwxyz123456"
                        to: "TXYZabcdefghijklmnopqrstuvwxyz123456"
                      status: "success"
                      block_info:
                        number: 12345678
                        hash: "0xabcdef..."
                        confirmation_count: 12
                      gas_info:
                        used: "21000"
                        price: "20000000000"
                        fee: "0.00042"
                        transaction_fee: "0.00042"
                      transaction_type: "deposit"
                      description: "Card recharge transaction"
                      timestamps:
                        created_at: "2024-10-25T10:30:00"
                        updated_at: "2024-10-25T10:35:00"
                        transaction_time: 1698203395
                      processed:
                        status: 1
                        processed_at: "2024-10-25T10:35:00"
        '400':
          description: 请求参数错误
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '401':
          description: 未授权
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '404':
          description: 交易不存在
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '500':
          description: 服务器内部错误
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'

  /getRecordDetail:
    post:
      tags:
        - 交易管理
      summary: 根据订单号查询交易详情
      description: |
        根据订单号或交易记录ID查询详细的交易信息。
        
        ## 功能说明
        
        - 支持通过 `trans_id`（交易记录ID）或 `order_id`（第三方订单号）查询
        - 返回详细的交易信息，包括：
          - 开卡交易：包含充值地址、交易哈希、汇率等信息
          - 充值交易：包含充值地址、交易哈希、手续费、汇率等信息
          - 支付交易：包含商户信息、支付详情等
          - 提现交易：包含提现地址、交易哈希、手续费、汇率等信息
        
        ## 使用场景
        
        - 查询开卡交易的详细信息
        - 查询充值交易的详细信息
        - 查询支付交易的详细信息
        - 查询提现交易的详细信息
      operationId: getRecordDetail
      security:
        - BearerAuth: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
                - trans_id
              properties:
                trans_id:
                  type: integer
                  description: 交易记录ID（与order_id二选一）
                  example: 12345
                order_id:
                  type: string
                  description: 第三方订单号（与trans_id二选一）
                  example: open_card_12345_39_abc123
            examples:
              by_trans_id:
                summary: 通过交易记录ID查询
                value:
                  trans_id: 12345
              by_order_id:
                summary: 通过订单号查询
                value:
                  order_id: "open_card_12345_39_abc123"
      responses:
        '200':
          description: 查询成功
          content:
            application/json:
              schema:
                type: object
                properties:
                  code:
                    type: integer
                    description: 响应状态码，200 表示成功
                    example: 200
                  status:
                    type: string
                    description: 响应状态，"true" 表示成功
                    example: 'true'
                  message:
                    type: string
                    description: 响应消息
                    example: success
                  data:
                    type: object
                    description: 交易详情（根据交易类型返回不同的详细信息）
                    properties:
                      trans_id:
                        type: integer
                        description: 交易记录ID
                        example: 12345
                      third_party_order_id:
                        type: string
                        description: 第三方订单号
                        example: open_card_12345_39_abc123
                      trans_type:
                        type: string
                        description: 交易类型
                        enum: [recharge, payment, open_card, withdraw]
                        example: open_card
                      status:
                        type: string
                        description: 交易状态
                        enum: [success, failed, pending, cancelled, timeout]
                        example: success
                      amount:
                        type: string
                        description: 交易金额
                        example: '30.00'
                      currency:
                        type: string
                        description: 交易币种
                        example: USD
                      fee:
                        type: string
                        description: 手续费
                        example: '10.00'
                      fee_currency:
                        type: string
                        description: 手续费币种
                        example: USD
                      merchant_name:
                        type: string
                        nullable: true
                        description: 商户名称（支付交易）
                        example: Example Merchant
                      create_time:
                        type: string
                        description: 创建时间
                        example: '2024-10-25 10:30:00'
                      finish_time:
                        type: string
                        nullable: true
                        description: 完成时间
                        example: '2024-10-25 10:35:00'
                      card_info:
                        type: object
                        nullable: true
                        description: 卡片信息
                      open_card_transaction:
                        type: object
                        nullable: true
                        description: 开卡交易详情（仅开卡交易返回）
                        properties:
                          network:
                            type: string
                            description: 网络名称
                            example: TRON
                          deposit_address:
                            type: string
                            description: 充值地址
                            example: TXYZabcdefghijklmnopqrstuvwxyz123456
                          transaction_hash:
                            type: string
                            description: 交易哈希
                            example: 0x1234567890abcdef...
                          transaction_hash_url:
                            type: string
                            description: 交易哈希在区块链浏览器中的URL
                            example: >-
                              https://tronscan.org/#/transaction/0x1234567890abcdef...
                      card_charge_transaction:
                        type: object
                        nullable: true
                        description: 充值交易详情（仅充值交易返回）
                        properties:
                          network:
                            type: string
                            description: 网络名称
                            example: TRON
                          deposit_address:
                            type: string
                            description: 充值地址
                            example: TXYZabcdefghijklmnopqrstuvwxyz123456
                          deposit_token_symbol:
                            type: string
                            description: 充值币种
                            example: USDT
                          transaction_hash:
                            type: string
                            description: 交易哈希
                            example: 0x1234567890abcdef...
                          transaction_hash_url:
                            type: string
                            description: 交易哈希在区块链浏览器中的URL
                            example: >-
                              https://tronscan.org/#/transaction/0x1234567890abcdef...
                      exchange_rate:
                        type: string
                        nullable: true
                        description: 汇率
                        example: '1.0'
                      payment_detail:
                        type: object
                        nullable: true
                        description: 支付详情（仅支付交易返回）
                      withdraw_transaction:
                        type: object
                        nullable: true
                        description: 提现详情（仅提现交易返回）
              examples:
                success_open_card:
                  summary: 开卡交易详情
                  value:
                    code: 200
                    status: "true"
                    message: "success"
                    data:
                      trans_id: 12345
                      third_party_order_id: "open_card_12345_39_abc123"
                      trans_type: "open_card"
                      status: "success"
                      amount: "30.00"
                      currency: "USD"
                      fee: "10.00"
                      fee_currency: "USD"
                      create_time: "2024-10-25 10:30:00"
                      finish_time: "2024-10-25 10:35:00"
                      open_card_transaction:
                        network: "TRON"
                        deposit_address: "TXYZabcdefghijklmnopqrstuvwxyz123456"
                        transaction_hash: "0x1234567890abcdef..."
                        transaction_hash_url: "https://tronscan.org/#/transaction/0x1234567890abcdef..."
                      exchange_rate: "1.0"
                success_recharge:
                  summary: 充值交易详情
                  value:
                    code: 200
                    status: "true"
                    message: "success"
                    data:
                      trans_id: 12346
                      third_party_order_id: "charge_12345_39_12345_abc123"
                      trans_type: "recharge"
                      status: "success"
                      amount: "100.00"
                      currency: "USD"
                      fee: "1.80"
                      fee_currency: "USDT"
                      create_time: "2024-10-25 10:30:00"
                      finish_time: "2024-10-25 10:35:00"
                      card_charge_transaction:
                        network: "TRON"
                        deposit_address: "TXYZabcdefghijklmnopqrstuvwxyz123456"
                        deposit_token_symbol: "USDT"
                        transaction_hash: "0x1234567890abcdef..."
                        transaction_hash_url: "https://tronscan.org/#/transaction/0x1234567890abcdef..."
                      exchange_rate: "0.982"
        '400':
          description: 请求参数错误
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '401':
          description: 未授权
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '404':
          description: 交易记录不存在
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '500':
          description: 服务器内部错误
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'

  /userTrans:
    get:
      tags:
        - 交易管理
      summary: 查询所有交易记录
      description: |
        查询用户的所有交易记录，支持分页和多种筛选条件。
        
        ## 功能说明
        
        - 支持按交易类型筛选（recharge、payment、open_card）
        - 支持按卡片绑定ID筛选
        - 支持按日期范围筛选
        - 支持分页查询
        
        ## 交易类型说明
        
        - `recharge`: 充值交易
        - `payment`: 支付交易
        - `open_card`: 开卡交易
      operationId: getUserTransactions
      security:
        - BearerAuth: []
      parameters:
        - name: page
          in: query
          description: 页码（从1开始）
          required: false
          schema:
            type: integer
            default: 1
            example: 1
        - name: page_num
          in: query
          description: 每页数量
          required: false
          schema:
            type: integer
            default: 20
            example: 20
        - name: trans_type
          in: query
          description: 交易类型筛选（recharge、payment、open_card）
          required: false
          schema:
            type: string
            enum: [recharge, payment, open_card]
            example: recharge
        - name: card_binding_id
          in: query
          description: 卡片绑定ID筛选
          required: false
          schema:
            type: integer
            example: 12345
        - name: start_date
          in: query
          description: 开始日期（格式：YYYY-MM-DD 或时间戳）
          required: false
          schema:
            type: string
            example: '2024-10-01'
        - name: end_date
          in: query
          description: 结束日期（格式：YYYY-MM-DD 或时间戳）
          required: false
          schema:
            type: string
            example: '2024-10-31'
      responses:
        '200':
          description: 查询成功
          content:
            application/json:
              schema:
                type: object
                properties:
                  code:
                    type: integer
                    description: 响应状态码，200 表示成功
                    example: 200
                  status:
                    type: string
                    description: 响应状态，"true" 表示成功
                    example: 'true'
                  message:
                    type: string
                    description: 响应消息
                    example: success
                  data:
                    type: object
                    properties:
                      list:
                        type: array
                        description: 交易记录列表
                        items:
                          type: object
                          properties:
                            trans_id:
                              type: integer
                              description: 交易记录ID
                              example: 12345
                            card:
                              type: string
                              description: 卡片显示名称（包含卡号后四位）
                              example: PayAll Crypto Card **** 1234
                            time:
                              type: string
                              description: 交易时间
                              example: '2024-10-25 10:30:00'
                            amount:
                              type: string
                              description: 交易金额
                              example: '100.00'
                            desc:
                              type: string
                              description: 交易描述
                              example: USD recharge
                            trans_type:
                              type: string
                              description: 交易类型
                              example: recharge
                            transaction_id:
                              type: string
                              description: 交易ID
                              example: tx_123456
                            deposit_addr:
                              type: string
                              description: 充值地址
                              example: ""
                            status:
                              type: string
                              description: 交易状态
                              enum: [success, failed, pending, cancelled, timeout]
                              example: success
                      pagination:
                        type: object
                        description: 分页信息
                        properties:
                          total:
                            type: integer
                            description: 总记录数
                            example: 100
                          page:
                            type: integer
                            description: 当前页码
                            example: 1
                          page_num:
                            type: integer
                            description: 每页数量
                            example: 20
                          total_pages:
                            type: integer
                            description: 总页数
                            example: 5
        '400':
          description: 请求参数错误
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '401':
          description: 未授权
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '500':
          description: 服务器内部错误
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'

  /userTransRecord:
    get:
      tags:
        - 交易管理
      summary: 查询某条记录详情
      description: |
        根据交易ID查询单条交易记录的详情。
        
        ## 功能说明
        
        - 通过 `transaction_id` 查询交易记录
        - 返回完整的交易记录信息
      operationId: getTransactionRecord
      security:
        - BearerAuth: []
      parameters:
        - name: transaction_id
          in: query
          description: 交易ID
          required: true
          schema:
            type: string
            example: tx_123456
      responses:
        '200':
          description: 查询成功
          content:
            application/json:
              schema:
                type: object
                properties:
                  code:
                    type: integer
                    description: 响应状态码，200 表示成功
                    example: 200
                  status:
                    type: string
                    description: 响应状态，"true" 表示成功
                    example: 'true'
                  message:
                    type: string
                    description: 响应消息
                    example: success
                  data:
                    type: object
                    description: 交易记录详情
        '400':
          description: 请求参数错误
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '401':
          description: 未授权
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '500':
          description: 服务器内部错误
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'

security:
  - BearerAuth: []

components:
  securitySchemes:
    BearerAuth:
      type: http
      scheme: bearer
      bearerFormat: JWT
      description: |
        使用从 `/thirdPartyLogin` 接口获取的 `userToken` 进行身份验证。
        
        在请求头中添加：
        ```
        Authorization: Bearer {userToken}
        ```
        
        示例：
        ```
        Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJ1c2VyX2lkIjoxMjM0LCJ1c2VyX2tleSI6InVzZXJAZXhhbXBsZS5jb20iLCJleHAiOjE2OTgyMDMzOTV9.xxxxx
        ```
        
        **注意：**
        - `/thirdPartyLogin` 接口不需要 Authorization header（用于获取 token）
        - 其他所有接口都需要在请求头中携带 Authorization header
        - Token 过期后需要重新调用 `/thirdPartyLogin` 获取新 Token
