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

# List transactions

> List all transactions in the organization

**Permissions**: `transactions.read`



## OpenAPI

````yaml https://api.moflay.com/openapi get /v1/transactions
openapi: 3.1.0
info:
  title: Moflay API
  description: The fastest way to add M-Pesa payments.
  version: 1.0.0
  contact:
    name: Moflay Support
    email: support@moflay.com
    url: https://moflay.com
  termsOfService: https://moflay.com/legal/terms-of-service
servers:
  - url: https://api.moflay.com
    description: Production server
security:
  - token: []
tags:
  - name: Customers
    description: Create and manage customers in the organization
  - name: Transactions
    description: Everything about transactions in the organization
  - name: Express
    description: >-
      Create M-Pesa Express payments. Use the returned paymentId with the
      Payments API to read status.
  - name: Payments
    description: >-
      Track payment lifecycle and status for paymentIds returned by Express
      payment creation.
externalDocs:
  url: https://moflay.com/docs
  description: Moflay Documentation
paths:
  /v1/transactions:
    get:
      tags:
        - Transactions
      summary: List transactions
      description: |-
        List all transactions in the organization

        **Permissions**: `transactions.read`
      operationId: listTransactions
      parameters:
        - schema:
            type:
              - string
              - 'null'
            example: Premium Subscription
            description: >-
              Search for transactions by description, phone number, or receipt
              number
          required: false
          description: >-
            Search for transactions by description, phone number, or receipt
            number
          name: q
          in: query
        - schema:
            type:
              - string
              - 'null'
            example: eyJpZCI6IjEyMyJ9
            description: >-
              Cursor for pagination, representing the last item from the
              previous page
          required: false
          description: >-
            Cursor for pagination, representing the last item from the previous
            page
          in: query
          name: cursor
        - schema:
            type:
              - string
              - 'null'
            example: cus_MNO345PQR678STU
            description: Filter transactions by specific customer ID
          required: false
          description: Filter transactions by specific customer ID
          name: customerId
          in: query
        - schema:
            type:
              - array
              - 'null'
            items:
              $ref: '#/components/schemas/TransactionStatus'
            example:
              - pending
              - completed
              - canceled
            description: >-
              Array of transaction statuses to filter by. Available statuses:
              'initiating', 'pending', 'completed', 'failed', 'canceled',
              'unknown'
          required: false
          description: >-
            Array of transaction statuses to filter by. Available statuses:
            'initiating', 'pending', 'completed', 'failed', 'canceled',
            'unknown'
          name: statuses
          in: query
        - schema:
            type:
              - array
              - 'null'
            items:
              type: number
            description: >-
              Amount range as [min, max] in cents to filter transactions by
              monetary value. Example: [10000, 50000] for KES 100.00 to KES
              500.00
            example:
              - 10000
              - 50000
          required: false
          description: >-
            Amount range as [min, max] in cents to filter transactions by
            monetary value. Example: [10000, 50000] for KES 100.00 to KES 500.00
          name: amountRange
          in: query
        - schema:
            type:
              - array
              - 'null'
            items:
              type: string
            description: >-
              Array of specific amounts (as strings in KES) to filter
              transactions by exact values. Values are converted to cents
              internally.
            example:
              - '150.75'
              - '299.99'
              - '1000.00'
          required: false
          description: >-
            Array of specific amounts (as strings in KES) to filter transactions
            by exact values. Values are converted to cents internally.
          name: amount
          in: query
        - schema:
            type: number
            minimum: 1
            maximum: 100
            default: 10
            example: 10
            description: The number of transactions to return (1-100)
          required: false
          description: The number of transactions to return (1-100)
          in: query
          name: limit
        - schema:
            type:
              - string
              - 'null'
            format: date-time
            description: >-
              Start date (inclusive) for filtering transactions in ISO 8601
              format
            example: '2024-12-01T00:00:00.000Z'
          required: false
          description: Start date (inclusive) for filtering transactions in ISO 8601 format
          name: start
          in: query
        - schema:
            type:
              - string
              - 'null'
            format: date-time
            description: End date (inclusive) for filtering transactions in ISO 8601 format
            example: '2024-12-31T23:59:59.999Z'
          required: false
          description: End date (inclusive) for filtering transactions in ISO 8601 format
          name: end
          in: query
        - schema:
            type: string
            enum:
              - asc
              - desc
            default: desc
            example: desc
          required: false
          in: query
          name: sortOrder
        - schema:
            type: string
            enum:
              - createdAt
              - paidAt
              - failedAt
              - amount
              - status
              - phoneNumber
              - processedAt
            default: createdAt
            example: createdAt
          required: false
          in: query
          name: sortBy
      responses:
        '200':
          description: List of all transactions
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/TransactionListResponse'
        '401':
          description: Missing API Key Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/MissingApiKeyError'
        '403':
          description: Invalid API Key Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/InvalidApiKeyError'
        '405':
          description: Method Not Allowed Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/MethodNotAllowedError'
        '422':
          description: The validation error(s) or invalid access error
          content:
            application/json:
              schema:
                anyOf:
                  - $ref: '#/components/schemas/ValidationError'
                  - $ref: '#/components/schemas/InvalidAccessError'
                description: The validation error(s) or invalid access error
        '429':
          description: Rate Limit Exceeded Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/RateLimitExceededError'
        '500':
          description: Internal Server Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/InternalServerError'
      security:
        - token: []
components:
  schemas:
    TransactionStatus:
      type: string
      enum:
        - initiating
        - pending
        - completed
        - failed
        - canceled
        - unknown
      example: completed
      description: >-
        Current status. Possible values: initiating, pending, completed, failed,
        canceled, unknown
    TransactionListResponse:
      type: object
      properties:
        data:
          type: array
          items:
            $ref: '#/components/schemas/Transaction'
        meta:
          type: object
          properties:
            cursor:
              type:
                - string
                - 'null'
              example: eyJpZCI6IjEyMyJ9
              description: >-
                Cursor for pagination, representing the last item from the
                previous page
            hasPreviousPage:
              type: boolean
              example: false
            hasNextPage:
              type: boolean
              example: true
          required:
            - cursor
            - hasPreviousPage
            - hasNextPage
      required:
        - data
        - meta
      example:
        data:
          - id: trxn_ABC123DEF456GHI
            customerId: cus_MNO345PQR678STU
            object: transaction
            environment: sandbox
            type: payment
            amount: 1000
            description: 'Payment for Order #12345 - Premium Subscription'
            currency: KES
            status: completed
            phoneNumber: '254712345678'
            receiptNumber: QMF7MBB5ED
            failureReason: null
            metadata: {}
            source: api
            processedAt: '2024-12-19T10:30:00.000Z'
            createdAt: '2024-12-19T10:25:00.000Z'
            paidAt: '2024-12-19T10:32:00.000Z'
            failedAt: null
            unknownAt: null
        meta:
          cursor: eyJpZCI6InRyeG5fQUJDMTIzREVGNDU2R0hJIn0=
          hasPreviousPage: false
          hasNextPage: true
      description: List of all transactions
    MissingApiKeyError:
      type: object
      properties:
        error:
          type: object
          properties:
            status:
              type: number
              description: HTTP status code of the error
              example: 401
            code:
              type: string
              description: Machine-readable error name
              example: missing_api_key
            message:
              type: string
              x-speakeasy-error-message: true
              description: Human-readable error message
              example: Missing API key in the authorization header.
          required:
            - status
            - code
            - message
      required:
        - error
      description: Missing API Key Error
    InvalidApiKeyError:
      type: object
      properties:
        error:
          type: object
          properties:
            status:
              type: number
              description: HTTP status code of the error
              example: 403
            code:
              type: string
              description: Machine-readable error name
              example: invalid_api_key
            message:
              type: string
              x-speakeasy-error-message: true
              description: Human-readable error message
              example: API key is invalid.
          required:
            - status
            - code
            - message
      required:
        - error
      description: Invalid API Key Error
    MethodNotAllowedError:
      type: object
      properties:
        error:
          type: object
          properties:
            status:
              type: number
              description: HTTP status code of the error
              example: 405
            code:
              type: string
              description: Machine-readable error name
              example: method_not_allowed
            message:
              type: string
              x-speakeasy-error-message: true
              description: Human-readable error message
              example: Method is not allowed for the requested path.
          required:
            - status
            - code
            - message
      required:
        - error
      description: Method Not Allowed Error
    ValidationError:
      type: object
      properties:
        error:
          type: object
          properties:
            status:
              type: number
              description: HTTP status code of the error
              example: 422
            code:
              type: string
              description: Machine-readable error name
              example: validation_error
            message:
              type: string
              x-speakeasy-error-message: true
              description: Human-readable error message
              example: We found an error with one or more fields in the request.
            validation:
              type: array
              items:
                type: object
                properties:
                  field:
                    type: string
                    description: The name of the field that failed validation
                    example: email
                  message:
                    type: string
                    description: The validation error message for the field
                    example: Invalid email format
                required:
                  - field
                  - message
              description: List of field-specific validation issues
              example:
                - field: email
                  message: Invalid email format
                - field: age
                  message: Expected number, received string
          required:
            - status
            - code
            - message
            - validation
      required:
        - error
    InvalidAccessError:
      type: object
      properties:
        error:
          type: object
          properties:
            status:
              type: number
              description: HTTP status code of the error
              example: 422
          required:
            - status
        code:
          type: string
          description: Machine-readable error name
          example: invalid_access
        message:
          type: string
          x-speakeasy-error-message: true
          description: Human-readable error message
          example: >-
            The API key does not have the necessary permissions to access this
            resource.
      required:
        - error
        - code
        - message
    RateLimitExceededError:
      type: object
      properties:
        error:
          type: object
          properties:
            status:
              type: number
              description: HTTP status code of the error
              example: 429
            code:
              type: string
              description: Machine-readable error name
              example: rate_limit_exceeded
            message:
              type: string
              x-speakeasy-error-message: true
              description: Human-readable error message
              example: You have exceeded your request limit. Please try again later.
          required:
            - status
            - code
            - message
      required:
        - error
      description: Rate Limit Exceeded Error
    InternalServerError:
      type: object
      properties:
        error:
          type: object
          properties:
            status:
              type: number
              description: HTTP status code of the error
              example: 500
            code:
              type: string
              description: Machine-readable error name
              example: internal_server_error
            message:
              type: string
              x-speakeasy-error-message: true
              description: Human-readable error message
              example: An unexpected error occurred.
          required:
            - status
            - code
            - message
      required:
        - error
      description: Internal Server Error
    Transaction:
      type: object
      properties:
        id:
          type: string
          maxLength: 255
          example: trxn_YGZBY32PBBavYbhL
          description: Unique identifier for the transaction, prefixed with 'trxn_'
        customerId:
          $ref: '#/components/schemas/CustomerId'
        object:
          type: string
          example: transaction
        environment:
          $ref: '#/components/schemas/Environment'
        currency:
          type: string
          example: KES
          description: The transaction currency
        amount:
          type: number
          example: 1000
          description: Transaction amount in cents (e.g., 1000 = KES 10.00)
        description:
          type: string
          example: 'Payment for Order #12345 - Premium Subscription'
          description: Human-readable description of the transaction purpose
        phoneNumber:
          type: string
          description: >-
            Safaricom phone number in local (e.g., 0712345678, 0110123456) or
            international (e.g., 254712345678, 254110123456) format, transformed
            to 254XXXXXXXXX for M-PESA STK Push. Supports all Safaricom prefixes
            (070X, 074X, 0757–0759, 0768–0769, 079X, 0110–0117).
          example: '254712345678'
        status:
          $ref: '#/components/schemas/TransactionStatus'
        type:
          type: string
          enum:
            - payment
          example: payment
          description: The type of transaction
        receiptNumber:
          type:
            - string
            - 'null'
          maxLength: 50
          example: QMF7MBB5ED
          description: The M-Pesa receipt number
        processedAt:
          type:
            - string
            - 'null'
          example: '2024-12-19T10:30:00.000Z'
          description: Timestamp when the transaction was processed (ISO 8601 format)
        paidAt:
          type:
            - string
            - 'null'
          example: '2024-12-19T10:32:00.000Z'
          description: >-
            Timestamp when the transaction was successfully paid (ISO 8601
            format)
        failedAt:
          type:
            - string
            - 'null'
          example: '2024-12-19T10:33:00.000Z'
          description: Timestamp when the transaction failed (ISO 8601 format)
        unknownAt:
          type:
            - string
            - 'null'
          example: '2024-12-19T10:40:00.000Z'
          description: >-
            Timestamp when the transaction moved to an unknown state (ISO 8601
            format)
        failureReason:
          type:
            - string
            - 'null'
          example: Insufficient balance
          description: The transaction decline reason
        metadata:
          $ref: '#/components/schemas/Metadata'
        createdAt:
          type: string
          example: '2024-12-19T10:25:00.000Z'
          description: Timestamp when the transaction was created (ISO 8601 format)
        source:
          $ref: '#/components/schemas/Source'
      required:
        - id
        - customerId
        - object
        - environment
        - currency
        - amount
        - description
        - phoneNumber
        - status
        - type
        - receiptNumber
        - processedAt
        - paidAt
        - failedAt
        - unknownAt
        - failureReason
        - metadata
        - createdAt
        - source
      example:
        id: trxn_ABC123DEF456GHI
        customerId: cus_MNO345PQR678STU
        object: transaction
        environment: sandbox
        type: payment
        amount: 1000
        description: 'Payment for Order #12345 - Premium Subscription'
        currency: KES
        status: completed
        phoneNumber: '254712345678'
        receiptNumber: QMF7MBB5ED
        failureReason: null
        metadata: {}
        source: api
        processedAt: '2024-12-19T10:30:00.000Z'
        createdAt: '2024-12-19T10:25:00.000Z'
        paidAt: '2024-12-19T10:32:00.000Z'
        failedAt: null
        unknownAt: null
    CustomerId:
      type:
        - string
        - 'null'
      maxLength: 255
      example: cus_GqfKXLmg61LURZhB
      description: Unique identifier for the customer, prefixed with 'cus_'
    Environment:
      type: string
      enum:
        - sandbox
        - production
      description: The environment of the transaction. Either 'sandbox' or 'production'
      example: sandbox
    Metadata:
      type: object
      additionalProperties:
        anyOf:
          - type: string
            maxLength: 500
          - type: integer
          - type: number
          - type: boolean
      description: |-
        Key-value object allowing you to store additional information.

        **Key Requirements:**
        - Must be a string
        - Maximum length of 40 characters

        **Value Types:**
        - String (maximum 500 characters)
        - Integer
        - Floating-point number
        - Boolean

        **Limits:**
        - Maximum of 50 key-value pairs
      example:
        user_preference: dark_mode
        last_login: 1640995200
        is_premium: true
        account_balance: 1250.75
        notifications_enabled: false
    Source:
      type: string
      enum:
        - api
        - dashboard
        - checkout
      example: api
      description: The source of the resource. Either 'api', 'dashboard', or 'checkout'
  securitySchemes:
    token:
      type: http
      scheme: bearer
      description: The API key to use for authentication
      x-speakeasy-example: MOFLAY_API_KEY

````