openapi: 3.0.3
info:
  title: HamerzPay Core API
  version: 0.1.0
  description: Baseline API contract for customer, merchant, organization and admin panels.
servers:
  - url: https://app.hamerzpay.com/api/customer
    description: Customer panel
  - url: https://merchant.hamerzpay.com/api/merchant
    description: Merchant panel
  - url: https://org.hamerzpay.com/api/org
    description: Organization panel
  - url: https://admin.hamerzpay.com/api/admin
    description: Admin panel
paths:
  /health:
    get:
      summary: Panel health check
      responses:
        "200":
          description: Panel is healthy
          content:
            application/json:
              schema:
                type: object
                properties:
                  panel:
                    type: string
                  status:
                    type: string
  /credit/summary:
    get:
      summary: Customer credit summary
      responses:
        "200":
          description: Customer credit snapshot
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/CreditSummary"
  /checkout/session:
    post:
      summary: Create merchant checkout session
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/CheckoutSessionRequest"
      responses:
        "202":
          description: Session accepted for processing
  /budget/summary:
    get:
      summary: Organization budget summary
      responses:
        "200":
          description: Budget snapshot
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/BudgetSummary"
  /kpi/summary:
    get:
      summary: Admin KPI summary
      responses:
        "200":
          description: KPI snapshot
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/KpiSummary"
components:
  schemas:
    CreditSummary:
      type: object
      properties:
        credit_limit:
          type: integer
          nullable: true
        used_credit:
          type: integer
          nullable: true
        remaining_credit:
          type: integer
          nullable: true
    BudgetSummary:
      type: object
      properties:
        allocated_budget:
          type: integer
          nullable: true
        used_budget:
          type: integer
          nullable: true
        remaining_budget:
          type: integer
          nullable: true
    KpiSummary:
      type: object
      properties:
        registered_users:
          type: integer
          nullable: true
        approved_credits:
          type: integer
          nullable: true
        merchant_count:
          type: integer
          nullable: true
        organization_count:
          type: integer
          nullable: true
    CheckoutSessionRequest:
      type: object
      required:
        - order_id
        - amount
      properties:
        order_id:
          type: string
        amount:
          type: integer
        callback_url:
          type: string
          format: uri

