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

> Retrieve all transactions affecting a specific wallet (fundings, deposits, payouts, internal transfers, fees).

## Overview

`GET /wallet/transactions/wallet/{walletId}` returns the full transaction history for one wallet — fundings, deposits, payouts, internal transfers, and any fees deducted. The response is paginated.

## When to use it

* Render a per-wallet activity feed in your dashboard.
* Reconcile a wallet's balance against its transaction history.
* Investigate a missing or unexpected balance change.

## Prerequisites

* The wallet must belong to your company.

## Request

### Headers

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

### Path parameters

| Name       | Type   | Description       |
| ---------- | ------ | ----------------- |
| `walletId` | string | Wallet ID (UUID). |

### Query parameters

| Name    | Type    | Default | Description                 |
| ------- | ------- | ------- | --------------------------- |
| `page`  | integer | `1`     | 1-indexed page number.      |
| `limit` | integer | `10`    | Items per page (max \~100). |

## Response

### 200 — Success

```json theme={null}
{
  "success": true,
  "statusCode": 200,
  "message": "20 items retrieved successfully",
  "data": [
    {
      "id": "txn_5b7c9d2e4f6a8b1c3d5e7f9a",
      "amount": 5000,
      "amount_with_fee": 5050,
      "fee_amount": 50,
      "net_amount": 5000,
      "currency": "XAF",
      "status": "SUCCESS",
      "type": "FUND",
      "category": "WALLET",
      "operator": "mtn",
      "phone_number": "237670000000",
      "reference": "FUND-2026-001",
      "order_id": "AFB-202605091015-XYZ",
      "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": {
    "page": 1,
    "limit": 10,
    "total": 47,
    "totalPages": 5
  }
}
```

### Field reference

| Field                                            | Type   | Description                                                                               |
| ------------------------------------------------ | ------ | ----------------------------------------------------------------------------------------- |
| `id`                                             | string | Transaction ID.                                                                           |
| `amount`                                         | number | Transaction amount in `currency`.                                                         |
| `amount_with_fee`                                | number | `amount + fee_amount`. The total movement against the wallet.                             |
| `fee_amount`                                     | number | Fee deducted (`0` if no fee applies).                                                     |
| `net_amount`                                     | number | Net amount credited or debited after fees.                                                |
| `type`                                           | string | One of `FUND`, `WITHDRAW`, `DEPOSIT`, `TRANSFER`, `FEE`, `REFUND`.                        |
| `category`                                       | string | Always `"WALLET"` for this endpoint.                                                      |
| `status`                                         | string | One of `PENDING`, `PROCESSING`, `SUCCESS`, `FAILED`.                                      |
| `wallet_balance_before` / `wallet_balance_after` | number | Wallet balance immediately before / after this transaction settled. `null` for `PENDING`. |
| `reference`                                      | string | The `trxId` you supplied (or auto-generated).                                             |
| `order_id`                                       | string | Reference at the upstream payment provider.                                               |
| `completed_at`                                   | string | When the transaction reached a terminal state. `null` for non-terminal.                   |

### Error responses

| Status | Trigger                                              |
| ------ | ---------------------------------------------------- |
| `404`  | Wallet does not exist or belongs to another company. |

## Code examples

```bash cURL theme={null}
curl -G https://api.cartevo.co/api/v1/wallet/transactions/wallet/w1a2b3c4-d5e6-7890-abcd-ef1234567890 \
  -H "Authorization: Bearer $TOKEN" \
  --data-urlencode "page=1" \
  --data-urlencode "limit=50"
```

## Related

* [`GET /wallet/transactions/{id}`](/api-reference/endpoint/get-transaction) — single transaction detail by transaction ID.
* [`GET /wallet/transactions`](/api-reference/endpoint/get-wallet-transactions-global) — global list across all wallets.
* [Webhooks → Transaction events](/api-reference/endpoint/webhook#transaction-events) — receive these events in real time.


## OpenAPI

````yaml GET /wallet/transactions/wallet/{walletId}
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/wallet/{walletId}:
    get:
      summary: Transactions by wallet
      description: Retrieves a list of transactions for a specific wallet.
      parameters:
        - name: walletId
          in: path
          required: true
          schema:
            type: string
            format: uuid
        - name: page
          in: query
          schema:
            type: integer
            example: 1
        - name: limit
          in: query
          schema:
            type: integer
            example: 20
      responses:
        '200':
          description: A list of transactions for the specified wallet.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ListWalletTransactionsResponse'
        '404':
          description: Wallet not found.
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

````