twtapi-com Payment API

openapi: 3.2.0
info:
  title: TwtAPI Backend Payment API
  description: API proxy & billing platform for Twitter/RapidAPI
  version: 0.1.0
tags:
- name: Payment
paths:
  /payment/create-checkout:
    post:
      summary: Create Checkout
      description: '为已存在的 pending 订单创建渠道收银台会话，返回 checkout_url。


        校验顺序：订单存在 → 属于当前用户 → 未过期 → 仍为 pending →

        免费 API 单拦截 → 订阅单只允许刷卡 → 支付方式可用。

        任何一步不过都直接返回业务错误码，不会改动订单。


        渠道下单失败时会把订单置为 cancelled 并打上失败原因标记，

        避免订单一直悬在 pending 占位；成功后只写回 provider_session_id。'
      operationId: create_checkout_payment_create_checkout_post
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateCheckoutRequest'
        required: true
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema: {}
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
      tags:
      - Payment
  /payment/webhook/{provider_name}:
    post:
      summary: Payment Webhook
      description: Receive and process payment callbacks from providers.
      operationId: payment_webhook_payment_webhook__provider_name__post
      parameters:
      - name: provider_name
        in: path
        required: true
        schema:
          type: string
          title: Provider Name
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema: {}
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
      tags:
      - Payment
  /payment/status/{order_no}:
    get:
      summary: Payment Status
      description: '查询订单状态，供前端支付页轮询。


        不只读库：若订单处于「可能已成功但回调丢了」的状态（_SUCCESS_RECOVERABLE_STATUSES）

        且存有渠道会话信息，会主动向渠道查一次实时状态并做补偿

        —— 渠道返回 succeeded 就补记为已支付，返回 failed 且本地仍为 pending 则置为 cancelled。

        查渠道失败只记日志，不影响本次按本地状态返回，避免渠道抖动把查询接口打挂。'
      operationId: payment_status_payment_status__order_no__get
      parameters:
      - name: order_no
        in: path
        required: true
        schema:
          type: string
          title: Order No
      - name: lang
        in: query
        required: false
        schema:
          type: string
          default: en
          title: Lang
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema: {}
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
      tags:
      - Payment
  /payment/cancel-subscription:
    post:
      summary: Cancel Subscription
      description: Cancel a Stripe subscription (at period end). Only for paid subscription orders of current user.
      operationId: cancel_subscription_payment_cancel_subscription_post
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CancelSubscriptionRequest'
        required: true
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema: {}
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
      tags:
      - Payment
components:
  schemas:
    HTTPValidationError:
      properties:
        detail:
          items:
            $ref: '#/components/schemas/ValidationError'
          type: array
          title: Detail
      type: object
      title: HTTPValidationError
    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
    CancelSubscriptionRequest:
      properties:
        order_no:
          type: string
          title: Order No
        lang:
          type: string
          title: Lang
          default: en
      type: object
      required:
      - order_no
      title: CancelSubscriptionRequest
      description: 取消订阅。lang 用于把取消结果文案按用户语言返回。
    CreateCheckoutRequest:
      properties:
        order_no:
          type: string
          title: Order No
        payment_method:
          type: string
          title: Payment Method
          default: credit_card
        lang:
          type: string
          title: Lang
          default: en
        source:
          anyOf:
          - type: string
            maxLength: 80
          - type: 'null'
          title: Source
        page_slug:
          anyOf:
          - type: string
            maxLength: 160
          - type: 'null'
          title: Page Slug
        entry_path:
          anyOf:
          - type: string
            maxLength: 300
          - type: 'null'
          title: Entry Path
      type: object
      required:
      - order_no
      title: CreateCheckoutRequest
      description: '为已存在的 pending 订单发起支付（生成渠道支付页/会话）。


        source / page_slug / entry_path 是前端埋点：记录用户从哪个入口下单，

        带长度上限是为了防止有人塞超长字符串撑爆日志与统计表。'