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

# List transactions

> List transactions within a date range. Both startDate and endDate are required. Results are returned in descending order by creation time.



## OpenAPI

````yaml api-reference/openapi.json get /v1/transactions
openapi: 3.1.0
info:
  title: Fingo Pay API
  description: >-
    Fingo Pay's unified payments API for M-Pesa C2B (STK Push), B2C
    disbursements, B2B transfers, bank transfers, account balances, and
    transactions.
  version: 1.0.0
servers:
  - url: https://api.fingopay.io
security:
  - bearerAuth: []
tags:
  - name: Payments
    description: Receive payments from customers
  - name: Payouts
    description: Send payments to recipients
  - name: Accounts
    description: Account balances and management
  - name: Transactions
    description: Transaction history and lookup
  - name: Verification
    description: Pre-transaction verification and lookup
  - name: Webhooks
    description: Webhook event notifications
paths:
  /v1/transactions:
    get:
      tags:
        - Transactions
      summary: List transactions
      description: >-
        List transactions within a date range. Both startDate and endDate are
        required. Results are returned in descending order by creation time.
      operationId: listTransactions
      parameters:
        - name: startDate
          in: query
          required: true
          description: Start date for the query range (ISO 8601 format, e.g., 2025-01-01).
          schema:
            type: string
            format: date
        - name: endDate
          in: query
          required: true
          description: End date for the query range (ISO 8601 format, e.g., 2025-01-31).
          schema:
            type: string
            format: date
        - name: type
          in: query
          required: false
          description: Filter by transaction type.
          schema:
            type: string
            enum:
              - charge
              - transfer
              - payment
              - settlement
              - airtime
              - reversal
              - bank_deposit
              - bank_withdrawal
        - name: status
          in: query
          required: false
          description: Filter by transaction status.
          schema:
            type: string
            enum:
              - pending
              - completed
              - failed
              - settled
              - initiated
              - rejected
        - name: accountType
          in: query
          required: false
          description: Filter by account type.
          schema:
            type: string
            enum:
              - collections
              - payouts
        - name: accountNo
          in: query
          required: false
          description: Filter by specific account number.
          schema:
            type: string
        - name: customerId
          in: query
          required: false
          description: Filter by customer ID.
          schema:
            type: string
        - name: shortcode
          in: query
          required: false
          description: >-
            **[Enterprise]** Filter transactions by dedicated shortcode number.
            Returns only transactions routed through the specified shortcode.
            The shortcode must belong to your organization.
          schema:
            type: string
          x-enterprise: true
        - name: limit
          in: query
          required: false
          description: Maximum number of results to return.
          schema:
            type: integer
            minimum: 1
            maximum: 10000
            default: 10000
      responses:
        '200':
          description: Transactions fetched successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/TransactionsListResponse'
        '400':
          $ref: '#/components/responses/ErrorResponse'
        '401':
          $ref: '#/components/responses/ErrorResponse'
        '404':
          $ref: '#/components/responses/ErrorResponse'
components:
  schemas:
    TransactionsListResponse:
      type: object
      properties:
        status:
          type: string
          example: success
        message:
          type: string
          example: Transactions fetched
        data:
          type: object
          properties:
            items:
              type: array
              items:
                $ref: '#/components/schemas/Transaction'
            count:
              type: integer
              example: 150
              description: Number of transactions returned
            startDate:
              type: string
              format: date
              example: '2025-01-01'
            endDate:
              type: string
              format: date
              example: '2025-01-31'
          required:
            - items
            - count
            - startDate
            - endDate
      required:
        - status
        - message
        - data
    Transaction:
      type: object
      description: Transaction object returned in API responses.
      properties:
        publicId:
          type: string
          example: txn_01j7b6f9p5y9h
          description: Fingo transaction ID
        merchantTransactionId:
          type:
            - string
            - 'null'
          example: mtx_123
          description: Your merchant reference
        status:
          type: string
          enum:
            - pending
            - completed
            - failed
            - settled
            - initiated
            - rejected
          example: completed
        message:
          type:
            - string
            - 'null'
          example: Payment completed successfully
        amount:
          type:
            - integer
            - 'null'
          example: 10000
          description: Transaction amount in smallest unit
        chargedAmount:
          type:
            - integer
            - 'null'
          example: 10000
          description: Amount charged to customer
        currency:
          type: string
          example: KES
        accountType:
          type: string
          enum:
            - collections
            - payouts
          example: collections
        type:
          type: string
          enum:
            - charge
            - transfer
            - payment
            - settlement
            - airtime
            - reversal
            - bank_deposit
            - bank_withdrawal
          example: charge
        paymentMethod:
          type: string
          enum:
            - mobile_money
            - bank
          example: mobile_money
        processor:
          type: string
          enum:
            - mpesa
            - choicebank
          example: mpesa
        processorReference:
          type:
            - string
            - 'null'
          example: ODI31ABC123
          description: Reference from payment processor
        phoneNumber:
          type:
            - string
            - 'null'
          example: '+254712345678'
        narration:
          type:
            - string
            - 'null'
          example: 'Invoice #1234'
        customerId:
          type:
            - string
            - 'null'
          description: Internal customer ID
        customer:
          type:
            - object
            - 'null'
          description: Customer details if available
        fees:
          type:
            - integer
            - 'null'
          example: 100
          description: Total fees charged (in smallest unit)
        metadata:
          type:
            - object
            - 'null'
          description: >-
            Metadata echoed from the original request. Can include enterprise
            keys such as subMerchantDetails.
          additionalProperties: true
        subMerchantId:
          type:
            - string
            - 'null'
          description: Organization-scoped sub-merchant identifier supplied in the request.
        subMerchantDetails:
          oneOf:
            - $ref: '#/components/schemas/SubMerchantDetails'
            - type: 'null'
          description: Optional sub-merchant enrichment details when available.
        createdAt:
          type: integer
          example: 1723717200000
          description: Unix timestamp in milliseconds
        updatedAt:
          type: integer
          example: 1723717320000
          description: Unix timestamp in milliseconds
      required:
        - publicId
        - status
        - currency
        - accountType
        - type
        - paymentMethod
        - processor
        - createdAt
        - updatedAt
    Error:
      type: object
      properties:
        error:
          type: object
          properties:
            type:
              type: string
              enum:
                - invalid_request_error
                - authentication_error
                - rate_limit_error
                - api_error
                - idempotency_error
                - not_found_error
                - conflict_error
              description: Error category
            code:
              type: string
              enum:
                - missing_parameter
                - invalid_parameter
                - unauthorized
                - forbidden
                - too_many_requests
                - internal_error
                - duplicate
                - resource_not_found
                - missing_header
                - validation_error
              description: Specific error code
            message:
              type: string
              description: Human-readable error message
            param:
              type:
                - string
                - 'null'
              description: The parameter that caused the error, if applicable
            requestId:
              type: string
              description: Request ID for support reference
          required:
            - type
            - code
            - message
      required:
        - error
    SubMerchantDetails:
      type: object
      description: >-
        Optional sub-merchant enrichment details used when creating or updating
        a sub-merchant reference from API traffic.
      properties:
        name:
          type: string
          description: Display/trading name for the sub-merchant.
          example: Nairobi West Branch
        legalName:
          type: string
          description: Registered legal name for the sub-merchant.
          example: Nairobi West Branch Limited
        businessType:
          type: string
          description: Optional business entity type.
          example: Limited Liability Company
        email:
          type: string
          format: email
          description: Optional sub-merchant contact email.
        phoneNumber:
          type: string
          description: Optional sub-merchant contact phone number.
          example: '+254712345678'
        businessCertNo:
          type: string
          description: Optional business registration certificate number.
        taxId:
          type: string
          description: Optional tax identifier (for example KRA PIN).
        economicSector:
          type: string
          description: Optional economic sector reference.
        riskLevel:
          type: string
          enum:
            - low
            - medium
            - high
          description: >-
            Optional risk tier used for reconciliation and post-transaction
            controls.
      additionalProperties: false
  responses:
    ErrorResponse:
      description: Error response
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      description: >-
        Use your API key as a Bearer token. Example: Authorization: Bearer
        sk_live_...

````