subotiz-com Payment API

openapi: 3.2.0
info:
  title: Subotiz Com Payment API
  version: 1.0.0
  description: 'Operations tagged Payment across 2 of this provider''s published API definitions: subotiz-com-openapi.yml, v1-en.yaml. Each path carries the servers of the definition it was published in.'
servers:
- url: https://{api}.subotiz.com
  variables:
    api:
      default: api
security:
- sec0: []
tags:
- name: Payment
  description: 支付流水
paths:
  /api/v1/payments:
    get:
      tags:
      - Payment
      summary: List Payments by Trade ID
      description: Get payment flow list by trade_id. Returns all payment flows (including retries) for a specific trade.
      operationId: v1-payment-list-payments-by-trade-id
      parameters:
      - name: trade_id
        in: query
        description: Trade ID
        required: true
        schema:
          type: string
      - $ref: '#/components/parameters/HeaderRequestID'
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ListPaymentsResponse'
        '400':
          description: trade_id is required
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BaseResponse'
              example:
                code: parameter_missing
                message: trade_id is required
        '404':
          description: trade_id does not exist
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BaseResponse'
              example:
                code: resource_missing
                message: trade_id does not exist
    servers:
    - url: https://{api}.subotiz.com
      variables:
        api:
          default: api
  /api/v1/payments/list:
    get:
      tags:
      - Payment
      summary: List Payments by Time Range
      description: Query payment flows by time range and filters. Supports pagination with cursor-based navigation. Merchants can filter payments by creation time.
      operationId: v1-payment-query-payments
      parameters:
      - name: created_at.gt
        in: query
        description: Minimum value to filter by (exclusive, UTC time in RFC3339 format, such as '2025-01-01T00:00:00Z')
        schema:
          type: string
      - name: created_at.gte
        in: query
        description: Minimum value to filter by (inclusive, UTC time in RFC3339 format, such as '2025-01-01T00:00:00Z')
        schema:
          type: string
      - name: created_at.lt
        in: query
        description: Maximum value to filter by (exclusive, UTC time in RFC3339 format, such as '2025-01-01T00:00:00Z')
        schema:
          type: string
      - name: created_at.lte
        in: query
        description: Maximum value to filter by (inclusive, UTC time in RFC3339 format, such as '2025-01-01T00:00:00Z')
        schema:
          type: string
      - name: limit
        in: query
        description: "A limit on the number of objects to be returned. Limit can range between 1 and 100.\n Default: 50 if not specified."
        schema:
          type: integer
          format: int32
      - name: starting_after
        in: query
        description: "Pagination: starting_after ID for forward pagination.\n Use an id from the previous response as starting_after to fetch the next page.\n Mutually exclusive with ending_before."
        schema:
          type: string
      - name: ending_before
        in: query
        description: "Pagination: ending_before ID for backward pagination.\n Use an id from the previous response as ending_before to fetch the previous page.\n Mutually exclusive with starting_after."
        schema:
          type: string
      - $ref: '#/components/parameters/HeaderRequestID'
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ListPaymentResponse'
        '400':
          description: Invalid request parameters
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BaseResponse'
              example:
                code: parameters_exclusive
                message: starting_after and ending_before are mutually exclusive, only one can be provided
    servers:
    - url: https://{api}.subotiz.com
      variables:
        api:
          default: api
components:
  schemas:
    Payment:
      type: object
      properties:
        id:
          type: string
          description: Database primary key ID (Snowflake ID, string format)
        out_trans_id:
          type: string
          description: Payment flow ID
        trade_id:
          type: string
          description: Order ID / Trade ID
        merchant_id:
          type: string
          description: Merchant ID
        payment_method:
          type: string
          description: Payment method
        payment_channel:
          type: string
          description: Payment channel
        status:
          type: string
          description: Payment status
        amount:
          type: string
          description: Payment amount, truncated to two decimal places
        currency:
          type: string
          description: Currency
        channel_trade_id:
          type: string
          description: Channel transaction ID
        order_trans_id:
          type: string
          description: Order transaction ID (globally unique, represents one payment attempt)
        channel_payment_method:
          allOf:
          - $ref: '#/components/schemas/ChannelPaymentMethod'
          description: Payment method information
        created_at:
          type: string
          description: Creation time
        channel_ret_code:
          type: string
          description: Channel return code
        channel_ret_msg:
          type: string
          description: Channel return message
        verification:
          allOf:
          - $ref: '#/components/schemas/Verification'
          description: Card payment verification result (CVC / AVS / 3DS); null for non-card payments or when unavailable
      description: Payment
    ListPaymentsResponse:
      type: object
      properties:
        code:
          type: string
          description: error code
        message:
          type: string
          description: error message
        data:
          $ref: '#/components/schemas/ListPaymentsResponse_Data'
      description: ListPaymentsResponse
    ListPaymentResponse:
      type: object
      properties:
        code:
          type: string
          description: error code
        message:
          type: string
          description: error message
        data:
          $ref: '#/components/schemas/ListPaymentResponse_Data'
      description: ListPaymentResponse
    Verification:
      type: object
      properties:
        cvc_check:
          type: string
          description: 'CVC check result: pass / fail / unchecked / unavailable'
        avs:
          allOf:
          - $ref: '#/components/schemas/Avs'
          description: Address verification results; null when not triggered
        three_d_secure:
          allOf:
          - $ref: '#/components/schemas/ThreeDSecure'
          description: 3DS verification results; null when 3DS not performed
      description: Verification - Card payment verification results
    Avs:
      type: object
      properties:
        line1_check:
          type: string
          description: 'Address line check: pass / fail / unchecked / unavailable'
        postal_code_check:
          type: string
          description: 'Postal code check: pass / fail / unchecked / unavailable'
      description: Avs - Address verification results
    ListPaymentsResponse_Data:
      type: object
      properties:
        total:
          type: string
          description: Total count
        list:
          type: array
          items:
            $ref: '#/components/schemas/Payment'
          description: Payment flow list
      description: ListPaymentsResponse
    ListPaymentResponse_Data:
      type: object
      properties:
        list:
          type: array
          items:
            $ref: '#/components/schemas/Payment'
          description: Payment flow list (ordered by created_at DESC, id DESC)
        has_more:
          type: boolean
          description: "Whether or not there are more elements available after this set. \n If false, this set comprises the end of the list."
      description: ListPaymentResponse
    ChannelPaymentMethod:
      type: object
      properties:
        type:
          type: string
          description: Type, fixed value "card"
        card:
          allOf:
          - $ref: '#/components/schemas/CardInfo'
          description: Card information
      description: ChannelPaymentMethod
    ThreeDSecure:
      type: object
      properties:
        authentication_flow:
          type: string
          description: 'Authentication flow: frictionless / challenge'
        result:
          type: string
          description: 'Result: authenticated / attempt_acknowledged / not_supported / failed / exempted / processing_error'
        result_reason:
          type: string
          description: Failure or downgrade reason, empty when successful
        version:
          type: string
          description: 3DS protocol version, e.g. 2.2.0
        eci:
          type: string
          description: ECI indicator; empty when not returned
      description: ThreeDSecure - 3DS verification details
    BaseResponse:
      type: object
      properties:
        code:
          type: string
          description: error code
        message:
          type: string
          description: error message
    CardInfo:
      type: object
      properties:
        brand:
          type: string
          description: Card brand
        country:
          type: string
          description: Issuing country
        last4:
          type: string
          description: Last 4 digits of card number
        funding:
          type: string
          description: Card type (credit/debit)
        authcode:
          type: string
          description: Issuer authorization code; present for card payments, empty otherwise
        network_transaction_id:
          type: string
          description: Card network transaction ID; present for card payments, empty otherwise
        bin:
          type: string
          description: First 6 digits of the card number (BIN); present for card payments, empty otherwise
      description: CardInfo
  parameters:
    HeaderRequestID:
      name: Request-Id
      in: header
      description: The unique identifier of the request
      required: true
      schema:
        type: string
        default: 008e3967-a1b5-48bb-be14-d5bff5092e61
  securitySchemes:
    sec0:
      type: http
      description: 'Bearer API Key authentication. Format: Authorization: Bearer {your_api_key}'
      scheme: bearer
x-refined-from:
- subotiz-com-openapi.yml
- v1-en.yaml