> ## 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 All Wallet Transactions

> Query wallet transactions across every wallet your company owns, with optional filters by transaction ID, wallet, customer, or status.

## Overview

`GET /wallet/transactions` returns wallet transactions across **every wallet your company owns**, with optional filtering. For a per-wallet view, use [`GET /wallet/transactions/wallet/{walletId}`](/api-reference/endpoint/get-wallet-transactions) instead.

## When to use it

* Render a global activity feed in your dashboard.
* Find a transaction by its ID without knowing which wallet it belongs to.
* Reconcile total wallet activity over a date range.

## Prerequisites

* Authenticated as a company user.

## Request

### Headers

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

### Query parameters

| Name            | Type    | Default | Description                                                                                               |
| --------------- | ------- | ------- | --------------------------------------------------------------------------------------------------------- |
| `transactionId` | string  | —       | Filter to a single transaction by its UUID. Useful for support lookups.                                   |
| `walletId`      | string  | —       | Filter to one wallet's transactions.                                                                      |
| `customerId`    | string  | —       | Filter to transactions tied to a specific customer (where applicable).                                    |
| `status`        | string  | —       | One of `PENDING`, `PROCESSING`, `SUCCESS`, `FAILED`.                                                      |
| `limit`         | integer | `50`    | Items per page.                                                                                           |
| `offset`        | integer | `0`     | **0-indexed** offset (number of items to skip). This endpoint uses `offset`-based pagination, not `page`. |

> **Pagination quirk:** unlike most other list endpoints, this one uses `limit` / `offset` (not `page` / `limit`). We are aligning this in a future release; meanwhile, compute `offset = (page - 1) * limit` to translate.

## Response

### 200 — Success

```json theme={null}
{
  "success": true,
  "statusCode": 200,
  "message": "50 items retrieved successfully",
  "data": [
    {
      "id": "txn_5b7c9d2e4f6a8b1c3d5e7f9a",
      "wallet_id": "w1a2b3c4-d5e6-7890-abcd-ef1234567890",
      "amount": 5000,
      "currency": "XAF",
      "category": "WALLET",
      "type": "FUND",
      "status": "SUCCESS",
      "operator": "mtn",
      "phone_number": "237670000000",
      "wallet_balance_before": 120000,
      "wallet_balance_after": 125000,
      "created_at": "2026-05-09T10:15:00.000Z",
      "completed_at": "2026-05-09T10:15:42.000Z"
    }
  ],
  "meta": {
    "limit": 50,
    "offset": 0,
    "total": 1247
  }
}
```

The per-transaction shape matches [`GET /wallet/transactions/wallet/{walletId}`](/api-reference/endpoint/get-wallet-transactions) — see that page for the full field reference.

### Error responses

| Status | Trigger                                 |
| ------ | --------------------------------------- |
| `400`  | Invalid `status` or `customerId` value. |

## Code examples

```bash cURL theme={null}
# Page 2 with limit 50: offset = (2 - 1) * 50 = 50
curl -G https://api.cartevo.co/api/v1/wallet/transactions \
  -H "Authorization: Bearer $TOKEN" \
  --data-urlencode "limit=50" \
  --data-urlencode "offset=50" \
  --data-urlencode "status=SUCCESS"
```

## Related

* [`GET /wallet/transactions/wallet/{walletId}`](/api-reference/endpoint/get-wallet-transactions) — per-wallet view.
* [`GET /wallet/transactions/{id}`](/api-reference/endpoint/get-transaction) — single transaction detail.


## OpenAPI

````yaml GET /wallet/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:
  /wallet/transactions:
    get:
      summary: List wallet transactions
      description: >-
        Lists wallet transactions for the authenticated company, with optional
        filters. Returns transactions scoped to your company.
      parameters:
        - name: transactionId
          in: query
          required: false
          schema:
            type: string
          description: Filter by a specific transaction ID.
        - name: walletId
          in: query
          required: false
          schema:
            type: string
            format: uuid
          description: Filter by wallet ID.
        - name: customerId
          in: query
          required: false
          schema:
            type: string
            format: uuid
          description: Filter by customer ID.
        - name: status
          in: query
          required: false
          schema:
            type: string
          description: Filter by transaction status (e.g. SUCCESS, PENDING, FAILED).
        - name: limit
          in: query
          required: false
          schema:
            type: integer
          description: Maximum number of records to return.
        - name: offset
          in: query
          required: false
          schema:
            type: integer
          description: Number of records to skip.
      responses:
        '200':
          description: A list of wallet transactions for the company.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ListWalletTransactionsResponse'
components:
  schemas:
    ListWalletTransactionsResponse:
      allOf:
        - $ref: '#/components/schemas/StandardResponse'
        - type: object
          properties:
            data:
              type: array
              items:
                $ref: '#/components/schemas/WalletTransaction'
            pagination:
              $ref: '#/components/schemas/Pagination'
    StandardResponse:
      type: object
      properties:
        success:
          type: boolean
          example: true
        statusCode:
          type: integer
          example: 200
        message:
          type: string
          example: Data retrieved successfully
    WalletTransaction:
      type: object
      properties:
        id:
          type: string
          format: uuid
          example: 7d1cdfa3-9904-4a17-bce5-092554170c0e
        amount:
          type: number
          example: 5000
        amount_with_fee:
          type: number
          example: 5100
        fee_amount:
          type: number
          example: 100
        net_amount:
          type: number
          example: 5000
        currency:
          type: string
          example: XAF
        status:
          type: string
          example: PENDING
        type:
          type: string
          example: FUND
        category:
          type: string
          example: WALLET
        operator:
          type: string
          example: mtn
        phone_number:
          type: string
          example: '650695112'
        reference:
          type: string
          nullable: true
        order_id:
          type: string
          nullable: true
        wallet_balance_before:
          type: number
          example: 10000
        wallet_balance_after:
          type: number
          example: 15000
        created_at:
          type: string
          format: date-time
        completed_at:
          type: string
          format: date-time
          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

````