openapi: 3.0.0
info:
  title: Boya Statement API
  version: 1.0.0
  description: API for retrieving business wallet balance and statements
servers:
  - url: https://api.boyahq.com/v1
    description: Boya API server
security:
  - ApiKeyAuth: []
paths:
  /wallet/:
    get:
      summary: Retrieve Business Balance
      description: Get main account balance
      parameters:
        - in: header
          name: org_wallet_ref
          schema:
            type: integer
            default: 1
          description: wallet ref currency
      responses:
        '200':
          description: Successful response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/StatementResponse'
  /wallet/all-in-one/{org_wallet_ref}:
    get:
      summary: Retrieve Business Statements
      description: Get a paginated list of statement entries
      parameters:
        - in: header
          name: org_wallet_ref
          schema:
            type: integer
            default: 1
          description: wallet ref currency
        - in: query
          name: from
          schema:
            type: string
            required: true
          description: from date yyyy-mm-dd
        - in: query
          name: to
          schema:
            type: string
            required: true
          description: to date yyyy-mm-dd
        - in: query
          name: page
          schema:
            type: integer
            default: 1
          description: Page number for pagination
        - in: query
          name: limit
          schema:
            type: integer
            default: 25
          description: Number of items per page
      responses:
        '200':
          description: Successful response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/StatementResponse'
  /wallet/topup-history/{accountNumber}/{org_wallet_ref}:
    get:
      summary: Retrieve Account Topup History
      description: Get a paginated list of topup history
      parameters:
        - in: path
          name: accountNumber
          schema:
            type: string
            default: 1
          description: wallet accountNumber
        - in: header
          name: org_wallet_ref
          schema:
            type: integer
            default: 1
          description: wallet ref currency
        - in: query
          name: from
          schema:
            type: string
            required: true
          description: from date yyyy-mm-dd
        - in: query
          name: to
          schema:
            type: string
            required: true
          description: to date yyyy-mm-dd
        - in: query
          name: page
          schema:
            type: integer
            default: 1
          description: Page number for pagination
        - in: query
          name: limit
          schema:
            type: integer
            default: 25
          description: Number of items per page
      responses:
        '200':
          description: Successful response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BalanceResponse'
components:
  securitySchemes:
    ApiKeyAuth:
      type: apiKey
      in: header
      name: X-API-KEY
  schemas:
    BalanceResponse:
      type: object
      properties:
        availableBalance:
          type: double
          description: Total amount available in business wallets
        allocatedAmount:
          type: double
          description: Total Amount allocated & Available in employee wallets
    StatementResponse:
      type: object
      properties:
        docs:
          type: array
          items:
            $ref: '#/components/schemas/StatementEntry'
        total:
          type: integer
        limit:
          type: string
        page:
          type: string
        pages:
          type: integer
    StatementEntry:
      type: object
      properties:
        _id:
          type: string
        currency:
          type: string
        org_wallet_ref:
          type: string
        account:
          type: string
        credit:
          type: number
        debit:
          type: number
        counter:
          type: integer
        description:
          type: string
        ref:
          type: string
        created_by:
          type: string
        transaction_type:
          type: string
          enum:
            - EXPENSE
            - TOPUP
            - REFUND
            - REVERSAL
        running_balance:
          type: number
        business_running_balance:
          type: number
        createdAt:
          type: string
          format: date-time
        updatedAt:
          type: string
          format: date-time
        expense:
          $ref: '#/components/schemas/Expense'
        topup:
          $ref: '#/components/schemas/Topup'
        refund:
          $ref: '#/components/schemas/Refund'
    Expense:
      type: object
      properties:
        _id:
          type: string
        amount:
          type: number
        fees:
          type: number
        charge:
          type: number
        original_currency:
          type: string
        currency:
          type: string
        original_amount:
          type: number
        transaction_ref:
          type: string
        provider_ref:
          type: string
        employee_id:
          type: string
        person:
          type: string
        transaction_date:
          type: string
          format: date-time
        MerchantCategoryCode:
          type: string
        MerchantIdentifier:
          type: string
        fx_rate:
          type: number
        card_vcn:
          type: string
        receiver:
          type: string
        payment_type:
          type: string
        channel:
          type: string
        subcategory:
          type: object
          nullable: true
        team:
          type: object
          properties:
            _id:
              type: string
            name:
              type: string
            code:
              type: string
        tag:
          type: array
          items:
            type: string
        notes:
          type: string
        risk:
          type: string
        risk_notes:
          type: string
        attachments:
          type: array
          items:
            type: string
        payment_status:
          type: string
        status:
          type: string
        review_participants:
          type: array
          items:
            type: string
        review_mandate:
          type: integer
        review_level:
          type: integer
        events:
          type: array
          items:
            type: object
        exported:
          type: boolean
        sync_successful:
          type: boolean
        org_wallet_ref:
          type: string
        vendor:
          type: string
        customer:
          type: object
          nullable: true
        subscription_id:
          type: string
        account_number:
          type: string
        reviews:
          type: array
          items:
            type: object
        createdAt:
          type: string
          format: date-time
        updatedAt:
          type: string
          format: date-time
    Topup:
      type: object
      properties:
        _id:
          type: string
        ref:
          type: string
        description:
          type: string
        amount:
          type: number
        account:
          type: string
        channel:
          type: string
        is_employee_topup:
          type: boolean
        exported:
          type: boolean
        sync_successful:
          type: boolean
        created_by:
          type: string
        status:
          type: string
        createdAt:
          type: string
          format: date-time
        updatedAt:
          type: string
          format: date-time
    Refund:
      type: object
      properties:
        _id:
          type: string
        ref:
          type: string
        transaction_ref:
          type: string
        description:
          type: string
        amount:
          type: number
        account:
          type: string
        employee_id:
          type: string
        status:
          type: string
        org_wallet_ref:
          type: string
        currency:
          type: string
        createdAt:
          type: string
          format: date-time
        updatedAt:
          type: string
          format: date-time
