searchpipe-tech Payments API

openapi: 3.2.0
info:
  title: SearchPipe Payments API
  version: 0.2.0
tags:
- name: Payments
paths:
  /payments/catalog:
    get:
      tags:
      - Payments
      summary: Catalog
      description: 购买目录。登录用户附带当前订阅状态（供前端决定显示订阅/管理入口）。
      operationId: catalog_payments_catalog_get
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CatalogResponse'
  /payments/packages:
    get:
      tags:
      - Payments
      summary: Packages
      description: 充值套餐列表（兼容旧接口）。
      operationId: packages_payments_packages_get
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                items:
                  $ref: '#/components/schemas/PackageItem'
                type: array
                title: Response Packages Payments Packages Get
  /payments/orders:
    post:
      tags:
      - Payments
      summary: Create Order Route
      operationId: create_order_route_payments_orders_post
      security:
      - HTTPBearer: []
      parameters:
      - name: authorization
        in: header
        required: false
        schema:
          anyOf:
          - type: string
          - type: 'null'
          title: Authorization
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateOrderRequest'
      responses:
        '201':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CreateOrderResponse'
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
    get:
      tags:
      - Payments
      summary: List Orders Route
      description: '当前用户的订单列表（含 pending），控制台「Your orders」据此渲染。


        pending 单带 `can_resume` / `can_cancel`，前端据此显示 Continue / Cancel。'
      operationId: list_orders_route_payments_orders_get
      security:
      - HTTPBearer: []
      parameters:
      - name: limit
        in: query
        required: false
        schema:
          type: integer
          default: 20
          title: Limit
      - name: offset
        in: query
        required: false
        schema:
          type: integer
          default: 0
          title: Offset
      - name: authorization
        in: header
        required: false
        schema:
          anyOf:
          - type: string
          - type: 'null'
          title: Authorization
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/OrderListResponse'
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
  /payments/webhooks/{provider}:
    post:
      tags:
      - Payments
      summary: Payment Webhook
      description: '支付平台 webhook。验签失败 400；暂时性处理失败 500（平台会重试）。


        provider 路径段对应支付方名（creem/dodo；测试环境为注入的 fake provider 名）。'
      operationId: payment_webhook_payments_webhooks__provider__post
      parameters:
      - name: provider
        in: path
        required: true
        schema:
          type: string
          title: Provider
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                type: object
                additionalProperties: true
                title: Response Payment Webhook Payments Webhooks  Provider  Post
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
  /payments/subscription/cancel:
    post:
      tags:
      - Payments
      summary: Cancel Subscription Route
      description: '站内退订（H39 期末取消）：服务端直调平台 cancel API（mode=scheduled），

        不跳 Customer Portal，也**不立即终止**——订阅保留到 period_end（status 保持

        active，期间降级/另起新订阅照旧被拦），期末由 webhook/惰性过期收尾。

        已发积分不回收（按各自批次有效期自然失效）。

        平台成功才落本地排期标记；随后到达的 scheduled_cancel webhook 幂等。'
      operationId: cancel_subscription_route_payments_subscription_cancel_post
      security:
      - HTTPBearer: []
      parameters:
      - name: authorization
        in: header
        required: false
        schema:
          anyOf:
          - type: string
          - type: 'null'
          title: Authorization
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                type: object
                additionalProperties: true
                title: Response Cancel Subscription Route Payments Subscription Cancel Post
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
  /payments/subscription/resume:
    post:
      tags:
      - Payments
      summary: Resume Subscription Route
      description: '撤销期末取消（H39 反悔）：平台 resume 成功才清本地排期标记，

        订阅恢复自动续费。无排期 404；平台失败 502（标记保持）。'
      operationId: resume_subscription_route_payments_subscription_resume_post
      security:
      - HTTPBearer: []
      parameters:
      - name: authorization
        in: header
        required: false
        schema:
          anyOf:
          - type: string
          - type: 'null'
          title: Authorization
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                type: object
                additionalProperties: true
                title: Response Resume Subscription Route Payments Subscription Resume Post
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
  /payments/orders/{order_id}/resume:
    post:
      tags:
      - Payments
      summary: Resume Order Route
      description: '继续支付 pending 单：同一订单号重新生成托管收银台会话并返回 URL。


        邮箱未验证同样拦下（与下单一致）；订单已被支付/取消 → 409。'
      operationId: resume_order_route_payments_orders__order_id__resume_post
      security:
      - HTTPBearer: []
      parameters:
      - name: order_id
        in: path
        required: true
        schema:
          type: string
          title: Order Id
      - name: authorization
        in: header
        required: false
        schema:
          anyOf:
          - type: string
          - type: 'null'
          title: Authorization
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ResumeOrderResponse'
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
  /payments/orders/{order_id}/cancel:
    post:
      tags:
      - Payments
      summary: Cancel Order Route
      description: 取消 pending 单（→ cancelled）。不涉及退款：未扣款、未发积分。
      operationId: cancel_order_route_payments_orders__order_id__cancel_post
      security:
      - HTTPBearer: []
      parameters:
      - name: order_id
        in: path
        required: true
        schema:
          type: string
          title: Order Id
      - name: authorization
        in: header
        required: false
        schema:
          anyOf:
          - type: string
          - type: 'null'
          title: Authorization
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CancelOrderResponse'
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
  /payments/orders/{order_id}/confirm-paid:
    post:
      tags:
      - Payments
      summary: Confirm Paid Route
      description: '用户点「Payment succeeded」后的后台判定（H36：状态不依赖用户点击）。


        只读订单状态：paid → 200（前端走成功跳转）；其余一律 409（前端提示

        「未收到支付确认」并引导工单）。绝不因用户点击改写支付状态——paid 只能

        由 webhook 驱动（迟到付款经 fulfill_order 兜底，同效）。'
      operationId: confirm_paid_route_payments_orders__order_id__confirm_paid_post
      security:
      - HTTPBearer: []
      parameters:
      - name: order_id
        in: path
        required: true
        schema:
          type: string
          title: Order Id
      - name: authorization
        in: header
        required: false
        schema:
          anyOf:
          - type: string
          - type: 'null'
          title: Authorization
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CancelOrderResponse'
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
  /payments/orders/{order_id}/confirm-failed:
    post:
      tags:
      - Payments
      summary: Confirm Failed Route
      description: '用户点「Payment failed」：先读状态防误点，未支付则取消并给工单入口。


        paid → 409（实际已成功，前端走成功流程）；pending → 取消订单 + 返回工单

        URL（提醒用户提交工单）；已取消/failed → 幂等返回同口径。Creem 无失败

        webhook 也无状态查询端点，「失败」无法向平台核实，这是既定兜底口径（H36 D4）。'
      operationId: confirm_failed_route_payments_orders__order_id__confirm_failed_post
      security:
      - HTTPBearer: []
      parameters:
      - name: order_id
        in: path
        required: true
        schema:
          type: string
          title: Order Id
      - name: authorization
        in: header
        required: false
        schema:
          anyOf:
          - type: string
          - type: 'null'
          title: Authorization
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ConfirmFailedResponse'
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
  /payments/orders/{order_id}:
    get:
      tags:
      - Payments
      summary: Order Status
      operationId: order_status_payments_orders__order_id__get
      security:
      - HTTPBearer: []
      parameters:
      - name: order_id
        in: path
        required: true
        schema:
          type: string
          title: Order Id
      - name: authorization
        in: header
        required: false
        schema:
          anyOf:
          - type: string
          - type: 'null'
          title: Authorization
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/OrderStatusResponse'
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
  /payments/orders/{order_id}/events:
    get:
      tags:
      - Payments
      summary: Order Events Stream
      description: '订单状态 SSE 推送（H40：等待弹窗的服务端回调，替代 4s 轮询）。


        连接即发当前状态快照；此后 webhook 入账/取消把新状态推过来（Redis

        pub/sub，发布在 commit 之后），终态推完关流。EventSource 断线自动重连，

        重连重新拿快照——发布失败/Redis 抖动自然降级为 ~3s 重连轮询。

        鉴权走会话 cookie（EventSource 无法带 Authorization 头，get_current_user

        无 Bearer 时兜底读 cookie）。'
      operationId: order_events_stream_payments_orders__order_id__events_get
      security:
      - HTTPBearer: []
      parameters:
      - name: order_id
        in: path
        required: true
        schema:
          type: string
          title: Order Id
      - name: authorization
        in: header
        required: false
        schema:
          anyOf:
          - type: string
          - type: 'null'
          title: Authorization
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema: {}
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
components:
  schemas:
    HTTPValidationError:
      properties:
        detail:
          items:
            $ref: '#/components/schemas/ValidationError'
          type: array
          title: Detail
      type: object
      title: HTTPValidationError
    OrderStatusResponse:
      properties:
        order_id:
          type: string
          title: Order Id
        status:
          type: string
          title: Status
        credits:
          type: string
          title: Credits
        amount_cents:
          type: integer
          title: Amount Cents
        kind:
          type: string
          title: Kind
        pay_channel:
          anyOf:
          - type: string
          - type: 'null'
          title: Pay Channel
        provider_checkout_id:
          anyOf:
          - type: string
          - type: 'null'
          title: Provider Checkout Id
        paid_at:
          anyOf:
          - type: string
            format: date-time
          - type: 'null'
          title: Paid At
        created_at:
          type: string
          format: date-time
          title: Created At
        expires_at:
          type: string
          format: date-time
          title: Expires At
      type: object
      required:
      - order_id
      - status
      - credits
      - amount_cents
      - kind
      - pay_channel
      - paid_at
      - created_at
      - expires_at
      title: OrderStatusResponse
    ConfirmFailedResponse:
      properties:
        order_id:
          type: string
          title: Order Id
        status:
          type: string
          title: Status
        ticket_url:
          type: string
          title: Ticket Url
      type: object
      required:
      - order_id
      - status
      - ticket_url
      title: ConfirmFailedResponse
      description: 「付款失败」确认结果：pending/已取消单 → cancelled + 工单入口。
    CatalogResponse:
      properties:
        recharge_plans:
          items:
            $ref: '#/components/schemas/PlanInfo'
          type: array
          title: Recharge Plans
        subscription_plans:
          items:
            $ref: '#/components/schemas/PlanInfo'
          type: array
          title: Subscription Plans
        credit_price_rate:
          type: string
          title: Credit Price Rate
        max_recharge_amount:
          type: integer
          title: Max Recharge Amount
        min_recharge_amount:
          type: integer
          title: Min Recharge Amount
        currency:
          type: string
          title: Currency
        pay_channels:
          items:
            type: string
          type: array
          title: Pay Channels
        subscription:
          anyOf:
          - $ref: '#/components/schemas/SubscriptionInfo'
          - type: 'null'
      type: object
      required:
      - recharge_plans
      - subscription_plans
      - credit_price_rate
      - max_recharge_amount
      - min_recharge_amount
      - currency
      - pay_channels
      - subscription
      title: CatalogResponse
    PlanInfo:
      properties:
        id:
          type: string
          title: Id
        name:
          type: string
          title: Name
        kind:
          type: string
          title: Kind
        level:
          anyOf:
          - type: integer
          - type: 'null'
          title: Level
        credits:
          type: integer
          title: Credits
        price_cents:
          type: integer
          title: Price Cents
        price:
          type: number
          title: Price
        original_price:
          anyOf:
          - type: number
          - type: 'null'
          title: Original Price
        period:
          anyOf:
          - type: string
          - type: 'null'
          title: Period
      type: object
      required:
      - id
      - name
      - kind
      - level
      - credits
      - price_cents
      - price
      - original_price
      - period
      title: PlanInfo
    CreateOrderRequest:
      properties:
        kind:
          type: string
          title: Kind
          default: recharge
        plan_id:
          anyOf:
          - type: string
          - type: 'null'
          title: Plan Id
        amount_cents:
          anyOf:
          - type: integer
          - type: 'null'
          title: Amount Cents
        pay_channel:
          anyOf:
          - type: string
          - type: 'null'
          title: Pay Channel
      type: object
      title: CreateOrderRequest
    PackageItem:
      properties:
        id:
          type: string
          title: Id
        name:
          type: string
          title: Name
        credits:
          type: integer
          title: Credits
        price:
          type: number
          title: Price
      type: object
      required:
      - id
      - name
      - credits
      - price
      title: PackageItem
    ValidationError:
      properties:
        loc:
          items:
            anyOf:
            - type: string
            - type: integer
          type: array
          title: Location
        msg:
          type: string
          title: Message
        type:
          type: string
          title: Error Type
        input:
          title: Input
        ctx:
          type: object
          title: Context
      type: object
      required:
      - loc
      - msg
      - type
      title: ValidationError
    OrderListItem:
      properties:
        order_id:
          type: string
          title: Order Id
        kind:
          type: string
          title: Kind
        status:
          type: string
          title: Status
        amount_cents:
          type: integer
          title: Amount Cents
        credits:
          type: string
          title: Credits
        pay_channel:
          anyOf:
          - type: string
          - type: 'null'
          title: Pay Channel
        plan_name:
          anyOf:
          - type: string
          - type: 'null'
          title: Plan Name
        provider_checkout_id:
          anyOf:
          - type: string
          - type: 'null'
          title: Provider Checkout Id
        paid_at:
          anyOf:
          - type: string
            format: date-time
          - type: 'null'
          title: Paid At
        created_at:
          type: string
          format: date-time
          title: Created At
        can_resume:
          type: boolean
          title: Can Resume
        can_cancel:
          type: boolean
          title: Can Cancel
      type: object
      required:
      - order_id
      - kind
      - status
      - amount_cents
      - credits
      - pay_channel
      - plan_name
      - provider_checkout_id
      - paid_at
      - created_at
      - can_resume
      - can_cancel
      title: OrderListItem
      description: 订单中心列表项（含 pending 单的续付/取消入口）。
    CancelOrderResponse:
      properties:
        order_id:
          type: string
          title: Order Id
        status:
          type: string
          title: Status
      type: object
      required:
      - order_id
      - status
      title: CancelOrderResponse
    OrderListResponse:
      properties:
        items:
          items:
            $ref: '#/components/schemas/OrderListItem'
          type: array
          title: Items
        total:
          type: integer
          title: Total
      type: object
      required:
      - items
      - total
      title: OrderListResponse
    CreateOrderResponse:
      properties:
        order_id:
          type: string
          title: Order Id
        pay_url:
          type: string
          title: Pay Url
        amount_cents:
          type: integer
          title: Amount Cents
        credits:
          type: string
          title: Credits
        status:
          type: string
          title: Status
        pay_channel:
          type: string
          title: Pay Channel
        expires_at:
          type: string
          format: date-time
          title: Expires At
      type: object
      required:
      - order_id
      - pay_url
      - amount_cents
      - credits
      - status
      - pay_channel
      - expires_at
      title: CreateOrderResponse
    SubscriptionInfo:
      properties:
        plan_id:
          type: string
          title: Plan Id
        plan_name:
          type: string
          title: Plan Name
        level:
          anyOf:
          - type: integer
          - type: 'null'
          title: Level
        period_start:
          type: string
          format: date-time
          title: Period Start
        period_end:
          type: string
          format: date-time
          title: Period End
        status:
          type: string
          title: Status
          default: active
        cancel_scheduled_at:
          anyOf:
          - type: string
            format: date-time
          - type: 'null'
          title: Cancel Scheduled At
      type: object
      required:
      - plan_id
      - plan_name
      - level
      - period_start
      - period_end
      title: SubscriptionInfo
    ResumeOrderResponse:
      properties:
        order_id:
          type: string
          title: Order Id
        pay_url:
          type: string
          title: Pay Url
        status:
          type: string
          title: Status
        expires_at:
          type: string
          format: date-time
          title: Expires At
      type: object
      required:
      - order_id
      - pay_url
      - status
      - expires_at
      title: ResumeOrderResponse
  securitySchemes:
    HTTPBearer:
      type: http
      scheme: bearer