paths:
  /admin/currencies:
    post:
      summary: Create a new global currency
      description: Allows a SuperAdmin to add a new currency (e.g. KES, GHS) to the platform.
      tags: [Admin - Currencies]
      security:
        - bearerAuth: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                code:
                  type: string
                  example: "KES"
                  description: "Unique ISO currency code"
                name:
                  type: string
                  example: "Kenyan Shilling"
                symbol:
                  type: string
                  example: "KSh"
                status:
                  type: string
                  enum: [active, inactive]
                  example: "active"
                virtualAccountStatus:
                  type: string
                  enum: [active, inactive]
                  default: inactive
                  description: >-
                    Whether merchants should get a wallet in this currency. Defaults to inactive —
                    creating a currency does not automatically give merchants a wallet for it.
                    Picked up by a daily (and startup) background sync that creates/activates
                    wallets for every merchant once this is active.
                  example: "active"
      responses:
        '201':
          description: Currency created successfully
          content:
            application/json:
              schema:
                type: object
                properties:
                  success:
                    type: boolean
                    example: true
                  message:
                    type: string
                    example: "Currency created"
                  data:
                    type: object
                    properties:
                      id:
                        type: string
                        format: uuid
                      code:
                        type: string
                        example: "KES"
                      name:
                        type: string
                        example: "Kenyan Shilling"
                      symbol:
                        type: string
                        example: "KSh"
                      status:
                        type: string
                        example: "active"
                      virtualAccountStatus:
                        type: string
                        example: "active"

    get:
      summary: Get all platform currencies
      description: Returns a list of all active and inactive currencies managed by the platform.
      tags: [Admin - Currencies]
      security:
        - bearerAuth: []
      responses:
        '200':
          description: List of currencies
          content:
            application/json:
              schema:
                type: object
                properties:
                  success:
                    type: boolean
                    example: true
                  data:
                    type: array
                    items:
                      type: object
                      properties:
                        id:
                          type: string
                          format: uuid
                        code:
                          type: string
                          example: "NGN"
                        name:
                          type: string
                          example: "Nigerian Naira"
                        symbol:
                          type: string
                          example: "₦"
                        status:
                          type: string
                          example: "active"
                        virtualAccountStatus:
                          type: string
                          example: "inactive"

  /admin/currencies/{code}/status:
    patch:
      summary: Toggle currency status
      description: Allows a SuperAdmin to activate or deactivate a currency platform-wide.
      tags: [Admin - Currencies]
      security:
        - bearerAuth: []
      parameters:
        - in: path
          name: code
          required: true
          schema:
            type: string
            example: "KES"
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                status:
                  type: string
                  enum: [active, inactive]
                  example: "inactive"
      responses:
        '200':
          description: Currency status updated
          content:
            application/json:
              schema:
                type: object
                properties:
                  success:
                    type: boolean
                    example: true
                  message:
                    type: string
                    example: "Currency status updated to inactive"

  /admin/currencies/{code}/virtual-account-status:
    patch:
      summary: Toggle whether a currency is enabled for merchant wallets
      description: >-
        Controls whether merchants get a wallet in this currency. Not instant — a background
        job (runs at server startup, then every 24 hours) creates/activates or deactivates
        merchant wallets to match. Existing wallet balances are never deleted when deactivated,
        only marked inactive. NGN cannot be toggled — it's the merchant's native balance, not
        part of this system, and this endpoint returns 400 if attempted.
      tags: [Admin - Currencies]
      security:
        - bearerAuth: []
      parameters:
        - in: path
          name: code
          required: true
          schema:
            type: string
            example: "USD"
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required: [virtualAccountStatus]
              properties:
                virtualAccountStatus:
                  type: string
                  enum: [active, inactive]
                  example: "active"
      responses:
        '200':
          description: Virtual account status updated
          content:
            application/json:
              schema:
                type: object
                properties:
                  success:
                    type: boolean
                    example: true
                  message:
                    type: string
                    example: "Virtual account status for USD updated to active"
        '400':
          description: Invalid virtualAccountStatus, or attempted on NGN.
        '404':
          description: Currency not found.
