openapi: 3.1.0
info:
  title: NineLogix API
  version: 1.0.0-test
  description: Provider-neutral NineLogix Orders and Hosted Checkout API. Production access is merchant-specific and approval-gated.
servers:
  - url: https://www.ninelogix.com/api/v1
security:
  - bearerAuth: []
paths:
  /orders:
    post:
      summary: Create a one-time order and hosted checkout
      parameters:
        - $ref: '#/components/parameters/IdempotencyKey'
      requestBody:
        required: true
        content:
          application/json:
            schema: { $ref: '#/components/schemas/CreateCheckout' }
      responses:
        '201': { description: Created, content: { application/json: { schema: { $ref: '#/components/schemas/CheckoutResponse' } } } }
        '403': { $ref: '#/components/responses/Error' }
  /checkout-sessions:
    post:
      summary: Create a hosted checkout session
      parameters:
        - $ref: '#/components/parameters/IdempotencyKey'
      requestBody:
        required: true
        content:
          application/json:
            schema: { $ref: '#/components/schemas/CreateCheckout' }
      responses:
        '201': { description: Created, content: { application/json: { schema: { $ref: '#/components/schemas/CheckoutResponse' } } } }
  /checkout-sessions/{session_id}:
    get:
      summary: Retrieve a checkout session
      parameters:
        - { name: session_id, in: path, required: true, schema: { type: string, format: uuid } }
      responses:
        '200': { description: Current NineLogix state, content: { application/json: { schema: { $ref: '#/components/schemas/CheckoutResponse' } } } }
components:
  securitySchemes:
    bearerAuth: { type: http, scheme: bearer }
  parameters:
    IdempotencyKey: { name: Idempotency-Key, in: header, required: true, schema: { type: string, minLength: 8, maxLength: 128 } }
  schemas:
    CreateCheckout:
      type: object
      required: [order_id, amount_minor, currency, payment_method]
      additionalProperties: false
      properties:
        order_id: { type: string, minLength: 1, maxLength: 32 }
        amount_minor: { type: integer, minimum: 1 }
        currency: { type: string, pattern: '^[A-Z]{3}$' }
        payment_method: { type: string, enum: [alipay_plus, wechat_pay] }
        description: { type: string, maxLength: 128 }
    CheckoutResponse:
      type: object
      properties:
        ok: { type: boolean }
        request_id: { type: string, format: uuid }
        data:
          type: object
          properties:
            id: { type: string, format: uuid }
            object: { type: string, enum: [order, checkout_session] }
            order_id: { type: string }
            amount_minor: { type: integer }
            currency: { type: string }
            status: { type: string, enum: [created, pending, succeeded, failed, cancelled, expired] }
            checkout_url: { type: string, format: uri, description: NineLogix-hosted URL only }
            livemode: { type: boolean }
  responses:
    Error:
      description: NineLogix error
      content:
        application/json:
          schema:
            type: object
            properties:
              ok: { type: boolean, const: false }
              request_id: { type: string }
              error:
                type: object
                properties: { code: { type: string }, message: { type: string } }