> ## Documentation Index
> Fetch the complete documentation index at: https://docs.usebila.com/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# List transfers

> Retrieve a paginated list of transfers/payouts for the authenticated merchant



## OpenAPI

````yaml /api-reference/openapi.json get /api/v1/bila/transfers
openapi: 3.0.0
info:
  title: Bila Payment Gateway API
  description: |-

    Bila Payment Gateway API - A payment processing API for Africa.

    ## Overview

    This API provides payment gateway functionality for:
    - **Account Management**: Manage payment accounts/wallets
    - **Bank Operations**: Access bank reference data
    - **Account Resolution**: Verify bank and mobile money accounts
    - **Transfer Recipients**: Manage saved transfer recipients
    - **Transfers (Payouts)**: Send money to bank accounts and mobile money
    - **Collections (Receive Payments)**: Collect payments via mobile money
    - **Transaction History**: View all transactions

    ## Mobile Money Providers

    - Airtel Money
    - MTN Mobile Money (MoMo)
    - Zamtel Kwacha

    ## Countries Supported

    - Zambia (zm)
    - Nigeria (ng)

    ## Authentication

    Use your merchant API key in the `x-api-key` header.
    You can generate API keys from your merchant dashboard.

    ## Base URL

    ```
    https://api.usebila.com/api/v1
    ```

    For sandbox/testing:
    ```
    https://sandbox.usebila.com/api/v1
    ```
        
  version: '2.0'
  contact: {}
servers:
  - url: https://api.usebila.com
    description: Production
  - url: https://sandbox.usebila.com
    description: Sandbox
security:
  - x-api-key: []
tags:
  - name: Accounts
    description: Account/wallet management endpoints
  - name: Banks
    description: Bank reference data endpoints
  - name: Resolve
    description: Account resolution/verification endpoints
  - name: Transfer Recipients
    description: Transfer recipient management endpoints
  - name: Transfers
    description: Payout/transfer operation endpoints
  - name: Collections
    description: Payment collection operation endpoints
  - name: Transactions
    description: Transaction history endpoints
  - name: Webhooks
    description: Webhook configuration and delivery history
paths:
  /api/v1/bila/transfers:
    get:
      tags:
        - Transfers
      summary: List transfers
      description: >-
        Retrieve a paginated list of transfers/payouts for the authenticated
        merchant
      operationId: BilaTransfersController_getTransfers
      parameters:
        - name: page
          required: false
          in: query
          description: 'Page number (default: 1)'
          schema:
            minimum: 1
            example: 1
            type: number
        - name: perPage
          required: false
          in: query
          description: 'Items per page (default: 50)'
          schema:
            minimum: 1
            maximum: 100
            example: 50
            type: number
        - name: status
          required: false
          in: query
          description: Filter by transfer status
          schema:
            type: string
            enum:
              - pending
              - successful
              - failed
        - name: type
          required: false
          in: query
          description: Filter by transfer type
          schema:
            type: string
            enum:
              - bank-account
              - mobile-money
        - name: accountId
          required: false
          in: query
          description: Filter by account ID
          schema:
            example: 68f11209-451f-4a15-bfcd-d916eb8b09f4
            type: string
        - name: startDate
          required: false
          in: query
          description: Filter by start date (ISO 8601)
          schema:
            example: '2024-01-01T00:00:00Z'
            type: string
        - name: endDate
          required: false
          in: query
          description: Filter by end date (ISO 8601)
          schema:
            example: '2024-12-31T23:59:59Z'
            type: string
      responses:
        '200':
          description: Transfers retrieved successfully
          content:
            application/json:
              schema:
                allOf:
                  - $ref: '#/components/schemas/BilaResponseDto'
                  - properties:
                      data:
                        $ref: '#/components/schemas/PaginatedTransfersResponseDto'
        '400':
          description: Bad request
      security:
        - x-api-key: []
components:
  schemas:
    BilaResponseDto:
      type: object
      properties:
        status:
          type: boolean
          description: Request success status
          example: true
        message:
          type: string
          description: Response message
          example: Operation completed successfully
      required:
        - status
        - message
    PaginatedTransfersResponseDto:
      type: object
      properties:
        data:
          description: List of transfers
          type: array
          items:
            $ref: '#/components/schemas/TransferResponseDto'
        meta:
          description: Pagination metadata
          allOf:
            - $ref: '#/components/schemas/PaginationMetaDto'
      required:
        - data
        - meta
    TransferResponseDto:
      type: object
      properties:
        id:
          type: string
          description: Transfer ID
          example: txn-001
        reference:
          type: string
          description: Client reference
          example: payout-12345
        type:
          type: string
          description: Transfer type
          enum:
            - bank-account
            - mobile-money
          example: bank-account
        status:
          type: string
          description: Transfer status
          enum:
            - pending
            - successful
            - failed
          example: successful
        amount:
          type: number
          description: Transfer amount
          example: 1000
        currency:
          type: string
          description: Currency code
          example: ZMW
        narration:
          type: string
          description: Transfer narration
          example: Salary payment
        recipient:
          description: Recipient details
          allOf:
            - $ref: '#/components/schemas/TransferRecipientDto'
        createdAt:
          type: string
          description: Creation timestamp (from Payment)
          example: '2024-01-15T10:30:00Z'
          format: date-time
        completedAt:
          type: string
          description: Completion timestamp (from Payment.processedAt)
          example: '2024-01-15T10:31:00Z'
          format: date-time
      required:
        - id
        - reference
        - type
        - status
        - amount
        - currency
        - recipient
        - createdAt
    PaginationMetaDto:
      type: object
      properties:
        total:
          type: number
          description: Total number of records
          example: 150
        perPage:
          type: number
          description: Items per page
          example: 50
        currentPage:
          type: number
          description: Current page number
          example: 1
        pageCount:
          type: number
          description: Total number of pages
          example: 3
      required:
        - total
        - perPage
        - currentPage
        - pageCount
    TransferRecipientDto:
      type: object
      properties:
        accountNumber:
          type: string
          description: Bank account number (bank-account only)
          example: '1234567890'
        accountName:
          type: string
          description: Account holder / recipient name
          example: JOHN DOE
        bankName:
          type: string
          description: Bank name (bank-account only)
          example: Zambia National Commercial Bank
        phone:
          type: string
          description: Phone number (mobile-money only)
          example: '0977123456'
        operator:
          type: string
          description: Mobile money operator (mobile-money only)
          example: airtel
      required:
        - accountName
  securitySchemes:
    x-api-key:
      type: apiKey
      in: header
      name: x-api-key
      description: Merchant API key (e.g., sk_live_xxx or sk_test_xxx)

````