paths:
  /admin/service-pricing:
    post:
      summary: Create new service pricing rule
      description: |
        Allows a SuperAdmin to define a new pricing rule for a specific service and currency.

        **`serviceName` is a free-text slug** — not a dropdown. The following are standard names used in this system:

        | serviceName | Description |
        |---|---|
        | `wallet_deposit` | Fee charged when a customer deposits into their wallet |
        | `payout` | Fee charged on payout/withdrawal transactions |
        | `card_decline_fee` | Flat fee charged when a virtual card transaction is declined |
        | `card_fx_charge` | Foreign exchange (FX) markup on international card spend |

        **Pricing Fields:**
        - `providerPercentage` — % the provider charges Airpero (decimal: `0.015` = 1.5%)
        - `providerFixedFee` — Flat fee the provider charges Airpero
        - `customerPercentage` — % Airpero charges the merchant/customer
        - `customerFixedFee` — Flat fee Airpero charges the merchant/customer
        - `customerMinCap` — Minimum fee charged to the customer
        - `customerMaxCap` — Maximum fee charged (`999999999.99` = uncapped)

        **SuperAdmin only.**
      tags: [Admin - Service Pricing]
      security:
        - bearerAuth: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ServicePricingCreate'
            examples:
              wallet_deposit:
                summary: Wallet deposit fee
                value:
                  serviceName: "wallet_deposit"
                  currency: "NGN"
                  providerPercentage: 0.0150
                  providerFixedFee: 0
                  customerPercentage: 0.0200
                  customerFixedFee: 0
                  isActive: true
              payout:
                summary: Payout flat fee
                value:
                  serviceName: "payout"
                  currency: "NGN"
                  providerPercentage: 0
                  providerFixedFee: 35
                  customerPercentage: 0
                  customerFixedFee: 50
                  isActive: true
              card_decline_fee:
                summary: Card decline flat fee (NEW)
                value:
                  serviceName: "card_decline_fee"
                  currency: "NGN"
                  providerPercentage: 0
                  providerFixedFee: 50
                  customerPercentage: 0
                  customerFixedFee: 100
                  customerMinCap: 0
                  customerMaxCap: 999999999.99
                  isActive: true
              card_fx_charge:
                summary: FX card charge for international spend (NEW)
                value:
                  serviceName: "card_fx_charge"
                  currency: "USD"
                  providerPercentage: 0.0150
                  providerFixedFee: 0
                  customerPercentage: 0.0200
                  customerFixedFee: 0
                  customerMinCap: 0
                  customerMaxCap: 999999999.99
                  isActive: true
      responses:
        '201':
          description: Service pricing created successfully
          content:
            application/json:
              schema:
                type: object
                properties:
                  success:
                    type: boolean
                    example: true
                  message:
                    type: string
                    example: "Service pricing created"
                  data:
                    $ref: '#/components/schemas/ServicePricingResponse'
        '400':
          description: Missing serviceName or currency
        '403':
          description: Forbidden - SuperAdmin only

    get:
      summary: Get all service pricing rules
      description: Returns all service pricing rules (active and inactive).
      tags: [Admin - Service Pricing]
      security:
        - bearerAuth: []
      responses:
        '200':
          description: List of service pricing rules
          content:
            application/json:
              schema:
                type: object
                properties:
                  success:
                    type: boolean
                    example: true
                  data:
                    type: array
                    items:
                      $ref: '#/components/schemas/ServicePricingResponse'

  /admin/service-pricing/{id}:
    patch:
      summary: Update a service pricing rule
      description: Update any pricing field of an existing rule. Send only what you want to change. SuperAdmin only.
      tags: [Admin - Service Pricing]
      security:
        - bearerAuth: []
      parameters:
        - in: path
          name: id
          required: true
          schema:
            type: string
            format: uuid
            example: "p1q2r3s4-t5u6-7890-vwxy-z12345678901"
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                providerPercentage:
                  type: number
                  example: 0.0180
                providerFixedFee:
                  type: number
                  example: 0
                customerPercentage:
                  type: number
                  example: 0.0250
                customerFixedFee:
                  type: number
                  example: 0
                customerMinCap:
                  type: number
                  example: 50
                customerMaxCap:
                  type: number
                  example: 2000
                isActive:
                  type: boolean
                  example: false
      responses:
        '200':
          description: Service pricing updated successfully
        '404':
          description: Service pricing not found
        '403':
          description: Forbidden - SuperAdmin only

    delete:
      summary: Delete a service pricing rule
      description: Permanently removes a pricing rule. SuperAdmin only.
      tags: [Admin - Service Pricing]
      security:
        - bearerAuth: []
      parameters:
        - in: path
          name: id
          required: true
          schema:
            type: string
            format: uuid
            example: "p1q2r3s4-t5u6-7890-vwxy-z12345678901"
      responses:
        '200':
          description: Service pricing deleted successfully
        '404':
          description: Service pricing not found
        '403':
          description: Forbidden - SuperAdmin only

components:
  schemas:
    ServicePricingCreate:
      type: object
      required: [serviceName, currency]
      properties:
        serviceName:
          type: string
          example: "card_decline_fee"
          description: "Free-text slug. Standard: wallet_deposit, payout, card_decline_fee, card_fx_charge"
        currency:
          type: string
          example: "NGN"
          description: "ISO 4217 currency code (e.g. NGN, USD)"
        providerPercentage:
          type: number
          example: 0.0150
          description: "% provider charges Airpero (0.015 = 1.5%)"
        providerFixedFee:
          type: number
          example: 50.00
        providerMinCap:
          type: number
          example: 0
        providerMaxCap:
          type: number
          example: 999999999.99
        customerPercentage:
          type: number
          example: 0.0200
          description: "% Airpero charges merchant/customer (0.02 = 2%)"
        customerFixedFee:
          type: number
          example: 100.00
        customerMinCap:
          type: number
          example: 0
        customerMaxCap:
          type: number
          example: 999999999.99
          description: "999999999.99 = uncapped"
        isActive:
          type: boolean
          example: true

    ServicePricingResponse:
      type: object
      properties:
        id:
          type: string
          format: uuid
        serviceName:
          type: string
          example: "card_decline_fee"
        currency:
          type: string
          example: "NGN"
        providerPercentage:
          type: number
          example: 0.0000
        providerFixedFee:
          type: number
          example: 50.00
        providerMinCap:
          type: number
          example: 0.00
        providerMaxCap:
          type: number
          example: 999999999.99
        customerPercentage:
          type: number
          example: 0.0000
        customerFixedFee:
          type: number
          example: 100.00
        customerMinCap:
          type: number
          example: 0.00
        customerMaxCap:
          type: number
          example: 999999999.99
        isActive:
          type: boolean
          example: true
        createdAt:
          type: string
          format: date-time
        updatedAt:
          type: string
          format: date-time
