paths:
  /admin/merchants/{merchantId}:
    get:
      summary: Get full merchant profile
      tags: [Admin]
      security:
        - bearerAuth: []
      parameters:
        - in: path
          name: merchantId
          required: true
          schema:
            type: string
            format: uuid
            example: "b1b2b3b4-b5b6-b7b8-b9b0-b1b2b3b4b5b6"
      responses:
        '200':
          description: Merchant profile details
          content:
            application/json:
              schema:
                type: object
                properties:
                  success:
                    type: boolean
                    example: true
                  data:
                    type: object
                    properties:
                      id:
                        type: string
                        format: uuid
                      businessName:
                        type: string
                        example: "Tech Innovators Ltd"
                      email:
                        type: string
                        example: "contact@techinnovators.com"
                      status:
                        type: string
                        example: "active"

  /admin/merchants/{merchantId}/status:
    patch:
      summary: Update merchant status
      tags: [Admin]
      security:
        - bearerAuth: []
      parameters:
        - in: path
          name: merchantId
          required: true
          schema:
            type: string
            format: uuid
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                status:
                  type: string
                  enum: [active, inactive, suspended]
                  example: "suspended"
      responses:
        '200':
          description: Status updated successfully
          content:
            application/json:
              schema:
                type: object
                properties:
                  success:
                    type: boolean
                    example: true
                  message:
                    type: string
                    example: "Merchant status updated to suspended"

  /admin/merchants/{merchantId}/stats:
    get:
      summary: Get merchant specific statistics
      tags: [Admin]
      security:
        - bearerAuth: []
      parameters:
        - in: path
          name: merchantId
          required: true
          schema:
            type: string
            format: uuid
      responses:
        '200':
          description: Merchant statistics
          content:
            application/json:
              schema:
                type: object
                properties:
                  success:
                    type: boolean
                    example: true
                  data:
                    type: object
                    properties:
                      totalTransactions:
                        type: integer
                        example: 1250
                      totalVolume:
                        type: number
                        example: 5400000.50
                      activeCustomers:
                        type: integer
                        example: 300

  /admin/customers/{customerId}:
    get:
      summary: Get full customer profile
      tags: [Admin]
      security:
        - bearerAuth: []
      parameters:
        - in: path
          name: customerId
          required: true
          schema:
            type: string
            format: uuid
      responses:
        '200':
          description: Customer profile 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

  /admin/customers/{customerId}/status:
    patch:
      summary: Update customer status
      tags: [Admin]
      security:
        - bearerAuth: []
      parameters:
        - in: path
          name: customerId
          required: true
          schema:
            type: string
            format: uuid
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                status:
                  type: string
                  enum: [active, inactive, suspended]
                  example: "active"
      responses:
        '200':
          description: Status updated
          content:
            application/json:
              schema:
                type: object
                properties:
                  success:
                    type: boolean
                    example: true
                  message:
                    type: string
                    example: "Customer status successfully changed"

  /admin/merchants/{merchantId}/fees:
    patch:
      summary: Update custom fees for a merchant
      description: >-
        Dual-purpose based on the request body. Omit `serviceName`/`currency` to set the legacy
        flat NGN deposit/payout override on the merchant record directly. Include `serviceName`
        and `currency` to instead set a per-service/per-currency pricing override (upserted into
        a dedicated MerchantServicePricing record) — see `/admin/merchants/{merchantId}/service-pricing`
        to list or remove these. This override takes priority over any subscription-plan override
        and the platform default for that merchant/service/currency combination.
      tags: [Admin]
      security:
        - bearerAuth: []
      parameters:
        - in: path
          name: merchantId
          required: true
          schema:
            type: string
            format: uuid
      requestBody:
        required: true
        content:
          application/json:
            schema:
              oneOf:
                - type: object
                  title: Legacy flat NGN fee override
                  properties:
                    customDepositFeePercent:
                      type: number
                      example: 0.4
                    customDepositFeeCap:
                      type: number
                      example: 80
                    customPayoutFeeFlat:
                      type: number
                      example: 15
                - type: object
                  title: Per-service/per-currency pricing override
                  required: [serviceName, currency]
                  properties:
                    serviceName:
                      type: string
                      example: "ngn_payout_service"
                    currency:
                      type: string
                      example: "NGN"
                    providerPercentage:
                      type: number
                      example: 0.003
                    providerFixedFee:
                      type: number
                      example: 10
                    providerMinCap:
                      type: number
                      example: 0
                    providerMaxCap:
                      type: number
                      example: 999999999.99
                    customerPercentage:
                      type: number
                      example: 0.004
                    customerFixedFee:
                      type: number
                      example: 15
                    customerMinCap:
                      type: number
                      example: 0
                    customerMaxCap:
                      type: number
                      example: 999999999.99
      responses:
        '200':
          description: Fees updated
          content:
            application/json:
              schema:
                type: object
                properties:
                  success:
                    type: boolean
                    example: true
                  message:
                    type: string
                    example: "Merchant custom fees updated"
                  data:
                    type: object
                    description: Only present when a per-service/per-currency override was set.

  /admin/merchants/{merchantId}/service-pricing:
    get:
      summary: List a merchant's per-service/per-currency pricing overrides
      tags: [Admin]
      security:
        - bearerAuth: []
      parameters:
        - in: path
          name: merchantId
          required: true
          schema:
            type: string
            format: uuid
      responses:
        '200':
          description: List of overrides
          content:
            application/json:
              schema:
                type: object
                properties:
                  success:
                    type: boolean
                    example: true
                  data:
                    type: array
                    items:
                      type: object
                      properties:
                        id:
                          type: string
                          format: uuid
                        serviceName:
                          type: string
                          example: "ngn_payout_service"
                        currency:
                          type: string
                          example: "NGN"
                        providerPercentage:
                          type: number
                          example: 0.003
                        customerPercentage:
                          type: number
                          example: 0.004
                        isActive:
                          type: boolean
                          example: true

  /admin/merchants/{merchantId}/service-pricing/{id}:
    delete:
      summary: Remove a merchant's per-service/per-currency pricing override
      description: >-
        Reverts that service+currency back to any subscription-plan override, or the platform
        default, for this merchant.
      tags: [Admin]
      security:
        - bearerAuth: []
      parameters:
        - in: path
          name: merchantId
          required: true
          schema:
            type: string
            format: uuid
        - in: path
          name: id
          required: true
          schema:
            type: string
            format: uuid
      responses:
        '200':
          description: Override removed
          content:
            application/json:
              schema:
                type: object
                properties:
                  success:
                    type: boolean
                    example: true
                  message:
                    type: string
                    example: "Merchant service pricing override removed"
        '404':
          description: Override not found.

  /admin/kyc/stages:
    get:
      summary: List all KYC stages
      tags: [Admin]
      security:
        - bearerAuth: []
      responses:
        '200':
          description: List of KYC stages
          content:
            application/json:
              schema:
                type: object
                properties:
                  success:
                    type: boolean
                    example: true
                  data:
                    type: array
                    items:
                      type: object
                      properties:
                        id:
                          type: string
                          format: uuid
                        level:
                          type: integer
                          example: 1
                        name:
                          type: string
                          example: "BVN Verification"

  /admin/services:
    get:
      summary: List all system services
      tags: [Admin]
      security:
        - bearerAuth: []
      responses:
        '200':
          description: List of system services
          content:
            application/json:
              schema:
                type: object
                properties:
                  success:
                    type: boolean
                    example: true
                  data:
                    type: array
                    items:
                      type: object
                      properties:
                        id:
                          type: string
                          format: uuid
                        providerName:
                          type: string
                          example: "9PSB"
                        isActive:
                          type: boolean
                          example: true

  /admin/services/{serviceId}/status:
    patch:
      summary: Toggle global service status
      tags: [Admin]
      security:
        - bearerAuth: []
      parameters:
        - in: path
          name: serviceId
          required: true
          schema:
            type: string
            format: uuid
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                isActive:
                  type: boolean
                  example: false
      responses:
        '200':
          description: Service status toggled
          content:
            application/json:
              schema:
                type: object
                properties:
                  success:
                    type: boolean
                    example: true
                  message:
                    type: string
                    example: "Service is now globally disabled"

  /admin/kyc/stages/{stageId}/services:
    post:
      summary: Map a system service to a KYC stage
      tags: [Admin]
      security:
        - bearerAuth: []
      parameters:
        - in: path
          name: stageId
          required: true
          schema:
            type: string
            format: uuid
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                serviceId:
                  type: string
                  format: uuid
                  example: "s1s2s3s4-s5s6-s7s8-s9s0-s1s2s3s4s5s6"
      responses:
        '201':
          description: Service mapped successfully
          content:
            application/json:
              schema:
                type: object
                properties:
                  success:
                    type: boolean
                    example: true
                  message:
                    type: string
                    example: "Service successfully mapped to KYC stage"

  /admin/kyc/stages/{stageId}/services/{serviceId}:
    patch:
      summary: Toggle active status of a service inside a KYC stage
      tags: [Admin]
      security:
        - bearerAuth: []
      parameters:
        - in: path
          name: stageId
          required: true
          schema:
            type: string
            format: uuid
        - in: path
          name: serviceId
          required: true
          schema:
            type: string
            format: uuid
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                isActive:
                  type: boolean
                  example: true
      responses:
        '200':
          description: Status toggled successfully
          content:
            application/json:
              schema:
                type: object
                properties:
                  success:
                    type: boolean
                    example: true
                  message:
                    type: string
                    example: "Service enabled for this KYC stage"
