openapi: 3.0.3
info:
  title: StixBNK Merchant API
  version: 1.0.0
  description: |
    Merchant API — open banking routing and invoicing & payment links.

    ## Authentication

    Send `X-API-Key` on every authenticated request.

    ## Hosted checkout

    `POST /api/v1/payments/merchant/requests` returns `payment_request_id` and `checkout_url`
    to StixBNK hosted pages (`/checkout/payment/` or `/checkout/sandbox/`).

    ## Sandbox

    - `"sandbox": true` — StixBNK local simulator only (`sb_*`). Never provider sandbox.
    - `"sandbox": false` / omitted — production Open Banking providers (live credentials).

servers:
  - url: https://stixbnk.com
    description: Production
  - url: http://localhost
    description: Local

tags:
  - name: Collections
  - name: Invoices
  - name: Webhooks

paths:
  /api/v1/payments/merchant/requests:
    post:
      tags: [Collections]
      summary: Create collection
      security:
        - ApiKeyAuth: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateCollectionRequest'
            examples:
              live:
                summary: Live
                value:
                  sandbox: false
                  amount: 45.00
                  currency: EUR
                  market: FR
                  reference: ORDER_123
                  product_name: Example product
                  description: Test
                  customer_email: payer@example.com
                  customer_first_name: John
                  customer_lastname: Doe
                  language: en
                  store_name: Example Store
                  success_url: https://example.com/success
                  failure_url: https://example.com/failed
              sandbox:
                summary: Sandbox
                value:
                  sandbox: true
                  amount: 45.00
                  currency: EUR
                  market: FR
                  reference: SANDBOX_123
                  product_name: Sandbox product
                  customer_email: payer@example.com
                  customer_first_name: John
                  customer_lastname: Doe
                  language: en
                  store_name: Example Store
                  success_url: https://example.com/success
                  failure_url: https://example.com/failed
      responses:
        '200':
          description: Collection created
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CreateCollectionResponse'
        '400':
          description: Validation / business error
        '403':
          description: KYB / sandbox / merchant disabled
        '409':
          description: Duplicate reference
        '422':
          description: No provider for market

  /api/v1/invoices:
    get:
      tags: [Invoices]
      summary: List invoices
      security:
        - ApiKeyAuth: []
      parameters:
        - name: status
          in: query
          schema: { type: string }
      responses:
        '200':
          description: Invoice list
    post:
      tags: [Invoices]
      summary: Create invoice
      security:
        - ApiKeyAuth: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateInvoiceRequest'
            example:
              customer:
                name: Acme SAS
                email: billing@acme.example
                company: Acme SAS
                address_country: FR
              line_items:
                - description: Consulting
                  quantity: 1
                  unit_amount: 120.00
                  tax_rate_percent: 20
              currency: EUR
              market: FR
              due_at: '2026-08-15'
              sandbox: false
              issue: true
      responses:
        '201':
          description: Invoice created
        '400':
          description: Validation error
        '403':
          description: KYB / sandbox gate

  /api/v1/invoices/item.php:
    get:
      tags: [Invoices]
      summary: Get invoice
      security:
        - ApiKeyAuth: []
      parameters:
        - name: id
          in: query
          required: true
          schema: { type: integer }
      responses:
        '200':
          description: Invoice object
        '404':
          description: Not found
    post:
      tags: [Invoices]
      summary: Invoice action
      description: Body `action` — update | send | issue | email | void
      security:
        - ApiKeyAuth: []
      parameters:
        - name: id
          in: query
          required: true
          schema: { type: integer }
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required: [action]
              properties:
                action:
                  type: string
                  enum: [update, send, issue, email, void]
            example:
              action: send
      responses:
        '200':
          description: Updated invoice
        '404':
          description: Not found

components:
  securitySchemes:
    ApiKeyAuth:
      type: apiKey
      in: header
      name: X-API-Key

  schemas:
    CreateCollectionRequest:
      type: object
      required: [amount, currency, market, reference, product_name]
      properties:
        sandbox: { type: boolean }
        amount: { type: number }
        currency: { type: string }
        market: { type: string }
        reference: { type: string }
        product_name: { type: string }
        product:
          type: object
          properties:
            product_name: { type: string }
        description: { type: string }
        locale: { type: string }
        language: { type: string }
        customer_email: { type: string, format: email }
        customer_first_name: { type: string }
        customer_lastname: { type: string }
        store_name: { type: string }
        success_url: { type: string, format: uri }
        failure_url: { type: string, format: uri }

    CreateCollectionResponse:
      type: object
      properties:
        success: { type: boolean }
        payment_request_id: { type: string }
        checkout_url: { type: string }
        checkout_expires_at: { type: string }
        funds_destination: { type: string }
        provider: { type: string }
        sandbox: { type: boolean }

    CreateInvoiceRequest:
      type: object
      required: [customer, line_items]
      properties:
        customer: { type: object }
        line_items: { type: array, items: { type: object } }
        currency: { type: string }
        market: { type: string }
        due_at: { type: string }
        notes: { type: string }
        sandbox: { type: boolean }
        issue: { type: boolean }
        send: { type: boolean }
