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

# List Payment Transactions

> Query payment collections and payouts with filters by status, type, external ID, and date range.

## Overview

`GET /payment/transactions` returns a paginated list of your company's payment transactions (collections and payouts), with optional filtering by status, type, external ID, or date range.

## When to use it

* Reconcile your books against Cartevo's records.
* Find a transaction by `external_id` when you've lost the Cartevo `transaction_id`.
* Build a dashboard view of recent payment activity.

## Prerequisites

* Authenticated as a company user.

## Request

### Headers

| Name            | Required | Description             |
| --------------- | -------- | ----------------------- |
| `Authorization` | Yes      | `Bearer <access_token>` |

### Query parameters

| Name          | Type    | Default | Description                                                                                              |
| ------------- | ------- | ------- | -------------------------------------------------------------------------------------------------------- |
| `status`      | string  | —       | Filter by status. One of `PENDING`, `PROCESSING`, `SUCCESS`, `FAILED`.                                   |
| `type`        | string  | —       | Filter by direction. One of `COLLECTION`, `PAYOUT`.                                                      |
| `external_id` | string  | —       | Filter by your idempotency key. Substring match.                                                         |
| `from_date`   | string  | —       | ISO 8601 datetime. Includes transactions created on/after this instant. Example: `2026-04-01T00:00:00Z`. |
| `to_date`     | string  | —       | ISO 8601 datetime. Includes transactions created strictly before this instant.                           |
| `page`        | integer | `1`     | 1-indexed page number.                                                                                   |
| `limit`       | integer | `20`    | Items per page. Max recommended: `100`.                                                                  |

## Response

### 200 — Success

```json theme={null}
{
  "success": true,
  "statusCode": 200,
  "message": "20 items retrieved successfully",
  "data": [
    {
      "transaction_id": "550e8400-e29b-41d4-a716-446655440000",
      "external_id": "ORD-2026-001",
      "status": "SUCCESS",
      "type": "COLLECTION",
      "amount": 1000,
      "currency": "XAF",
      "operator": "mtn",
      "country": "CM",
      "phone_number": "237670000000",
      "reason": "Payment completed",
      "description": "Invoice payment",
      "created_at": "2026-05-09T10:15:00.000Z",
      "updated_at": "2026-05-09T10:15:42.000Z",
      "error_message": null
    }
  ],
  "meta": {
    "page": 1,
    "limit": 20,
    "total": 137,
    "totalPages": 7
  }
}
```

The per-transaction shape matches [`GET /payment/transactions/{id}/status`](/api-reference/endpoint/get-payment-transaction-status).

### Error responses

| Status | Trigger                                   |
| ------ | ----------------------------------------- |
| `400`  | Invalid `status`, `type`, or date format. |

## Code examples

```bash cURL theme={null}
curl -G https://api.cartevo.co/api/v1/payment/transactions \
  -H "Authorization: Bearer $TOKEN" \
  --data-urlencode "type=COLLECTION" \
  --data-urlencode "status=SUCCESS" \
  --data-urlencode "from_date=2026-04-01T00:00:00Z" \
  --data-urlencode "to_date=2026-05-01T00:00:00Z" \
  --data-urlencode "limit=100"
```

## Related

* [`GET /payment/transactions/{id}/status`](/api-reference/endpoint/get-payment-transaction-status) — single transaction detail.
* [`GET /payment/balance`](/api-reference/endpoint/get-payment-balance) — current wallet balances.


## OpenAPI

````yaml GET /payment/transactions
openapi: 3.1.0
info:
  title: Cartevo API
  description: Essential endpoints for wallets, transactions, customers and conversion.
  version: 1.0.0
servers:
  - url: https://api.cartevo.co/api/v1
security:
  - bearerAuth: []
paths:
  /payment/transactions:
    get:
      summary: Query Transactions
      description: Query payment transactions with various filters and pagination
      parameters:
        - name: status
          in: query
          required: false
          schema:
            type: string
            enum:
              - PENDING
              - SUCCESS
              - FAILED
              - PROCESSING
          description: Filter by status (PENDING, SUCCESS, FAILED)
        - name: type
          in: query
          required: false
          schema:
            type: string
            enum:
              - COLLECTION
              - PAYOUT
          description: Filter by type (COLLECTION, PAYOUT)
        - name: external_id
          in: query
          required: false
          schema:
            type: string
          description: Filter by external ID (partial match)
        - name: from_date
          in: query
          required: false
          schema:
            type: string
            format: date-time
          description: Start date (ISO 8601)
        - name: to_date
          in: query
          required: false
          schema:
            type: string
            format: date-time
          description: End date (ISO 8601)
        - name: page
          in: query
          required: false
          schema:
            type: integer
            example: 1
          description: Page number
        - name: limit
          in: query
          required: false
          schema:
            type: integer
            example: 20
          description: Items per page
      responses:
        '200':
          description: Transactions retrieved successfully
          content:
            application/json:
              schema:
                type: object
                properties:
                  success:
                    type: boolean
                    example: true
                  message:
                    type: string
                    example: Transactions retrieved successfully
                  data:
                    type: array
                    items:
                      $ref: '#/components/schemas/TransactionStatus'
                  pagination:
                    $ref: '#/components/schemas/Pagination'
components:
  schemas:
    TransactionStatus:
      type: object
      properties:
        transaction_id:
          type: string
          format: uuid
          example: 550e8400-e29b-41d4-a716-446655440000
        status:
          type: string
          enum:
            - PENDING
            - SUCCESS
            - FAILED
            - PROCESSING
          example: SUCCESS
        amount:
          type: number
          example: 1000
        currency:
          type: string
          example: XAF
        phone_number:
          type: string
          example: '237670000000'
        country:
          type: string
          example: CM
        operator:
          type: string
          example: mtn
        type:
          type: string
          enum:
            - COLLECTION
            - PAYOUT
          example: COLLECTION
        external_id:
          type: string
          example: ORD-2024-001
        reason:
          type: string
          example: Invoice payment
        description:
          type: string
          example: Payment collection transaction
        created_at:
          type: string
          format: date-time
          example: '2025-01-08T12:00:00.000Z'
        updated_at:
          type: string
          format: date-time
          example: '2025-01-08T12:05:00.000Z'
        error_message:
          type: string
          nullable: true
    Pagination:
      type: object
      properties:
        page:
          type: integer
          example: 1
        limit:
          type: integer
          example: 20
        total:
          type: integer
          example: 15
        totalPages:
          type: integer
          example: 1
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer

````