paths:
  /customers/{customerId}:
    get:
      summary: Get customer details
      tags: [Customers]
      security:
        - bearerAuth: []
      parameters:
        - in: path
          name: customerId
          required: true
          schema:
            type: string
            format: uuid
      responses:
        '200':
          description: Customer details
          content:
            application/json:
              schema:
                type: object
                properties:
                  success:
                    type: boolean
                    example: true
                  data:
                    type: object
                    properties:
                      id:
                        type: string
                        format: uuid
                      firstName:
                        type: string
                        example: "John"
                      lastName:
                        type: string
                        example: "Doe"
                      email:
                        type: string
                        example: "john.doe@example.com"
                      kycLevel:
                        type: integer
                        example: 2

  /customers/{customerId}/balance:
    get:
      summary: Get customer balances
      tags: [Customers]
      security:
        - bearerAuth: []
      parameters:
        - in: path
          name: customerId
          required: true
          schema:
            type: string
            format: uuid
      responses:
        '200':
          description: Customer balances
          content:
            application/json:
              schema:
                type: object
                properties:
                  success:
                    type: boolean
                    example: true
                  data:
                    type: array
                    items:
                      type: object
                      properties:
                        currency:
                          type: string
                          example: "NGN"
                        availableBalance:
                          type: number
                          example: 15000.50
                        ledgerBalance:
                          type: number
                          example: 15500.00

  /customers/{customerId}/report:
    get:
      summary: Get customer activity report
      tags: [Customers]
      security:
        - bearerAuth: []
      parameters:
        - in: path
          name: customerId
          required: true
          schema:
            type: string
            format: uuid
      responses:
        '200':
          description: Customer report
          content:
            application/json:
              schema:
                type: object
                properties:
                  success:
                    type: boolean
                    example: true
                  data:
                    type: object
                    properties:
                      totalDeposits:
                        type: number
                        example: 150000
                      totalWithdrawals:
                        type: number
                        example: 45000

  /customers/{customerId}/transactions:
    get:
      summary: Get customer transactions
      tags: [Customers]
      security:
        - bearerAuth: []
      parameters:
        - in: path
          name: customerId
          required: true
          schema:
            type: string
            format: uuid
      responses:
        '200':
          description: Customer transactions list
          content:
            application/json:
              schema:
                type: object
                properties:
                  success:
                    type: boolean
                    example: true
                  data:
                    type: array
                    items:
                      type: object
                      properties:
                        reference:
                          type: string
                          example: "TXN_123456789"
                        amount:
                          type: number
                          example: 5000
                        type:
                          type: string
                          example: "credit"
                        status:
                          type: string
                          example: "successful"
                        createdAt:
                          type: string
                          format: date-time

  /customers/{customerId}/payout:
    post:
      summary: Initiate payout for customer
      tags: [Customers]
      security:
        - bearerAuth: []
      parameters:
        - in: path
          name: customerId
          required: true
          schema:
            type: string
            format: uuid
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                amount:
                  type: number
                  example: 10500
                bankCode:
                  type: string
                  example: "033"
                accountNumber:
                  type: string
                  example: "0123456789"
                narration:
                  type: string
                  example: "Payment for services"
      responses:
        '200':
          description: Payout successful
          content:
            application/json:
              schema:
                type: object
                properties:
                  success:
                    type: boolean
                    example: true
                  message:
                    type: string
                    example: "Payout initiated successfully"
                  data:
                    type: object
                    properties:
                      reference:
                        type: string
                        example: "PAY_987654321"

  /customers/{customerId}/debit:
    post:
      summary: Debit customer virtual account
      tags: [Customers]
      security:
        - bearerAuth: []
      parameters:
        - in: path
          name: customerId
          required: true
          schema:
            type: string
            format: uuid
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                amount:
                  type: number
                  example: 500
                serviceId:
                  type: string
                  format: uuid
                  example: "s1s2s3s4-s5s6-s7s8-s9s0-s1s2s3s4s5s6"
      responses:
        '200':
          description: Debit successful
          content:
            application/json:
              schema:
                type: object
                properties:
                  success:
                    type: boolean
                    example: true
                  message:
                    type: string
                    example: "Customer debited successfully"

  /customers/{customerId}/credit:
    post:
      summary: Credit customer virtual account
      tags: [Customers]
      security:
        - bearerAuth: []
      parameters:
        - in: path
          name: customerId
          required: true
          schema:
            type: string
            format: uuid
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                amount:
                  type: number
                  example: 2000
                serviceId:
                  type: string
                  format: uuid
      responses:
        '200':
          description: Credit successful
          content:
            application/json:
              schema:
                type: object
                properties:
                  success:
                    type: boolean
                    example: true
                  message:
                    type: string
                    example: "Customer credited successfully"

  /customers/{customerId}/kyc/bvn:
    post:
      summary: Verify customer BVN (Stage 1 KYC)
      tags: [Customers]
      security:
        - bearerAuth: []
      parameters:
        - in: path
          name: customerId
          required: true
          schema:
            type: string
            format: uuid
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                bvn:
                  type: string
                  example: "22222222222"
      responses:
        '200':
          description: BVN verified
          content:
            application/json:
              schema:
                type: object
                properties:
                  success:
                    type: boolean
                    example: true
                  message:
                    type: string
                    example: "BVN verification successful, customer upgraded to KYC Stage 1"

  /customers/{customerId}/kyc/id:
    post:
      summary: Verify customer ID (Stage 2 KYC)
      tags: [Customers]
      security:
        - bearerAuth: []
      parameters:
        - in: path
          name: customerId
          required: true
          schema:
            type: string
            format: uuid
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                idType:
                  type: string
                  enum: [NIN, PASSPORT, DRIVERS_LICENSE, VOTERS_CARD]
                  example: "NIN"
                idValue:
                  type: string
                  example: "12345678901"
      responses:
        '200':
          description: ID verified
          content:
            application/json:
              schema:
                type: object
                properties:
                  success:
                    type: boolean
                    example: true
                  message:
                    type: string
                    example: "ID verification successful, customer upgraded to KYC Stage 2"
