alrahma_sunday_school/public/docs/openapi_refund_controller.yaml

openapi: 3.0.3
info:
  title: Refund API - Al Rahma Sunday School
  version: 1.0.0
  description: Refund request and processing endpoints.
servers:
  - url: https://alrahmaisgl.org/api/v1
security:
  - BearerAuth: []
tags:
  - name: Refunds
    description: Manage refund requests

paths:
  /refunds:
    get:
      tags: [Refunds]
      summary: List refunds
      parameters:
        - name: page
          in: query
          schema: { type: integer, example: 1 }
        - name: per_page
          in: query
          schema: { type: integer, example: 20 }
        - name: parent_id
          in: query
          schema: { type: integer }
        - name: status
          in: query
          schema: { type: string, example: pending }
      responses:
        200:
          description: Paginated refunds
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PaginatedRefundsResponse'
    post:
      tags: [Refunds]
      summary: Create refund request
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateRefundRequest'
      responses:
        201:
          description: Refund created
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/RefundResponse'

  /refunds/{id}:
    get:
      tags: [Refunds]
      summary: Get refund by ID
      parameters:
        - name: id
          in: path
          required: true
          schema: { type: integer }
      responses:
        200:
          description: Refund
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/RefundResponse'
        404:
          description: Not found
    put:
      tags: [Refunds]
      summary: Update refund
      parameters:
        - name: id
          in: path
          required: true
          schema: { type: integer }
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/UpdateRefundRequest'
      responses:
        200:
          description: Updated refund
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/RefundResponse'

components:
  securitySchemes:
    BearerAuth:
      type: http
      scheme: bearer
      bearerFormat: JWT

  schemas:
    BasicSuccess:
      type: object
      properties:
        status: { type: string, example: "success" }
        message: { type: string }
        data: {}

    Refund:
      type: object
      properties:
        id: { type: integer }
        parent_id: { type: integer }
        invoice_id: { type: integer }
        refund_amount: { type: number }
        reason: { type: string }
        request: { type: string, nullable: true }
        status: { type: string, example: pending }
        requested_at: { type: string, format: date-time }
        approved_at: { type: string, format: date-time, nullable: true }
        refunded_at: { type: string, format: date-time, nullable: true }
        approved_by: { type: integer, nullable: true }
        refund_paid_amount: { type: number, nullable: true }
        refund_method: { type: string, nullable: true }
        check_nbr: { type: string, nullable: true }
        note: { type: string, nullable: true }
        school_year: { type: string }
        semester: { type: string }

    PaginatedRefundsResponse:
      type: object
      properties:
        status: { type: string }
        message: { type: string }
        data:
          type: object
          properties:
            data:
              type: array
              items: { $ref: '#/components/schemas/Refund' }
            pagination:
              type: object
              properties:
                current_page: { type: integer }
                per_page: { type: integer }
                total: { type: integer }
                total_pages: { type: integer }

    RefundResponse:
      type: object
      properties:
        status: { type: string }
        message: { type: string }
        data:
          $ref: '#/components/schemas/Refund'

    CreateRefundRequest:
      type: object
      required: [parent_id, invoice_id, refund_amount, reason]
      properties:
        parent_id: { type: integer }
        invoice_id: { type: integer }
        refund_amount: { type: number }
        reason: { type: string }
        request: { type: string, nullable: true }

    UpdateRefundRequest:
      type: object
      properties:
        status: { type: string, enum: [pending, approved, refunded, rejected] }
        refund_paid_amount: { type: number }
        refund_method: { type: string }
        check_nbr: { type: string }
        note: { type: string }