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

# List transactions

> List the account's transactions with filters, for an overview or reconciliation.

Useful for an overview or periodic reconciliation. To check a specific transaction you have just created, prefer [Retrieve a transaction](https://docs.i-pay.money/en/api-reference/transactions/retrieve-a-payment.md), which is more direct and accepts your own `transaction_id`.

* **Filters.** `query` filters on free text; the other parameters filter on an exact value or a date range. They all apply at the same time (logical AND), not as alternatives. The example only shows a subset: add or remove parameters as needed.
* **Displayed values.** The values of `status` and `payment_method` (see the [payment methods](https://docs.i-pay.money/en/guides/payouts-and-fees.md#fees-by-payment-method)) are formatted for display and do not match the machine values used by the other operations: do not compare them in your code, and only use this list for display or export.
* **Limits.** No rate limit is documented: to be confirmed with support before heavy use. For real-time tracking of a given transaction, prefer [webhooks](https://docs.i-pay.money/en/guides/webhooks.md) over repeatedly polling this list.

Common error messages: [Errors](https://docs.i-pay.money/en/api-reference/errors.md).


## OpenAPI

````yaml en/openapi.yaml GET /payments
openapi: 3.1.0
info:
  title: iPayMoney Merchant API
  version: 1.0.0
  description: >-
    v1 merchant contracts verified against the Rails routes, controllers and
    services. Partner contracts and non-operational v2 routes are not part of
    this public specification. Payment links must use private random references.
servers:
  - url: https://i-pay.money/api/v1
    description: Sandbox or Live depending on the headers and the key used
security: []
tags:
  - name: Payments
    description: Creation and tracking of merchant transactions
  - name: Payment links
    description: Hosted payment links
paths:
  /payments:
    get:
      tags:
        - Payments
      summary: List transactions
      description: >-
        Server-side pagination: the number of items per page is set with the
        `items` parameter (25 by default). The response remains a raw JSON
        array, without any structured pagination metadata: no `meta` envelope,
        no `Link` or `Total-Count` header. The page parameter is not documented
        by this contract, and the API returns neither a total nor a next-page
        link that would let the client build it.
      parameters:
        - $ref: '#/components/parameters/ContentType'
        - $ref: '#/components/parameters/TargetEnvironment'
        - $ref: '#/components/parameters/PaymentType'
        - name: query
          in: query
          schema:
            type: string
        - name: status
          in: query
          schema:
            type: string
            enum:
              - initiated
              - pending
              - succeeded
              - failed
              - refunded
        - name: created_from
          in: query
          schema:
            type: string
            format: date
        - name: created_to
          in: query
          schema:
            type: string
            format: date
        - name: items
          in: query
          schema:
            type: integer
            default: 25
            minimum: 1
      responses:
        '200':
          description: >-
            List of transactions (raw JSON array, without a pagination
            envelope). The `status` and `payment_method` values are formatted
            for display (e.g. `Succeeded`, `Airtel Ne`) and not normalized: do
            not compare them with the status values used by the other
            operations.
          x-verified: >-
            Internal verification note (not intended for the public
            documentation). Formatting rendered by `payment.displayed_status`
            and `payment.displayed_payment_method` — see
            app/views/api/v1/payments/_payment.json.jbuilder:3,6.
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/PaymentListItem'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '406':
          $ref: '#/components/responses/NotAcceptable'
      security:
        - bearerAuth: []
components:
  parameters:
    ContentType:
      name: Content-Type
      in: header
      required: true
      description: >-
        Required by the API authentication, including on GET requests, even
        though they have no body.
      schema:
        type: string
        const: application/json
    TargetEnvironment:
      name: Ipay-Target-Environment
      in: header
      required: true
      schema:
        type: string
        enum:
          - sandbox
          - live
    PaymentType:
      name: Ipay-Payment-Type
      in: header
      required: true
      description: >-
        Payment method. `POST /payments` only supports `mobile` (mobile money).
        Other payment methods (bank card and other channels) are not used here:
        they are available through payment links (`POST /external_payments`).
        Full list: [payment
        methods](/en/guides/payouts-and-fees#fees-by-payment-method).
      x-verified: >-
        Internal verification note (not intended for the public documentation).
        Scope decision: only the `mobile` value is documented for `POST
        /payments`; the other values handled by `Live::PaymentService` are still
        accepted by the API but belong to the "payment link" flow.
        `external_payment` is reserved for `POST /external_payments` (dedicated
        parameter of that operation).
      schema:
        type: string
        const: mobile
        example: mobile
  schemas:
    PaymentListItem:
      type: object
      properties:
        id:
          type: integer
        reference:
          type: string
        status:
          type: string
          example: Succeeded
        amount:
          type: integer
        fees:
          type: integer
        payment_method:
          type: string
          example: Airtel Ne
          description: >-
            Payment method used by the customer — see the list of [payment
            methods](/en/guides/payouts-and-fees#fees-by-payment-method).
        net_amount:
          type: integer
        platform:
          type: string
        device:
          type: string
        failure_reason:
          type:
            - string
            - 'null'
        country:
          type: string
        currency:
          type: string
        external_reference:
          type: string
        msisdn:
          type: string
        customer_name:
          type: string
        created_at:
          type: string
          format: date-time
        validated_at:
          type:
            - string
            - 'null'
          format: date-time
    Error:
      type: object
      properties:
        message:
          type: string
        status:
          type: string
          description: >-
            Only present on some application failures, e.g. a duplicate payment
            on `POST /payments`, where `status` is always `failed`. Absent from
            the other errors of this contract (e.g. 404 `Payment Not Found`,
            header/authentication errors).
          x-verified: >-
            Internal verification note (not intended for the public
            documentation). See `Live::PaymentService#error_response`
            (app/services/live/payment_service.rb:994-1005).
          example: failed
  responses:
    BadRequest:
      description: Invalid header or parameter, detected before any business logic.
      x-verified: >-
        Internal verification note (not intended for the public documentation).
        Detected by `ApiAuthService#authenticate`
        (app/services/api_auth_service.rb:20-26) — exact messages verified on
        2026-09-16.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
          examples:
            missingHeaderParams:
              summary: Missing authentication header
              value:
                message: 'Bad Request: Missing params'
            notAllowedEnvironment:
              summary: Ipay-Target-Environment not allowed
              value:
                message: 'Bad Request: Not Allowed Environment'
            notAllowedPaymentType:
              summary: Ipay-Payment-Type not allowed
              value:
                message: 'Bad Request: Not Allowed Payment Type'
            missingAuthenticationKey:
              summary: Authorization Bearer missing or malformed
              value:
                message: 'Bad Request: Missing Authentication Key'
    Unauthorized:
      description: Invalid key
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
    Forbidden:
      description: Account or environment not available
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
    NotAcceptable:
      description: Content-Type other than application/json
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      description: Secret key of the Sandbox or Live account

````

This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.