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

> Retrieve transaction history for a single card with optional filtering by date range, type, and status.

## Overview

`GET /cards/{id}/transactions` returns the full transaction history for one card — fundings, withdrawals, merchant authorizations, settlements, refunds, and any cross-border charges. The response is paginated.

## When to use it

* Render a per-card transaction view to the cardholder.
* Reconcile a card's activity with merchant statements.
* Investigate a disputed charge.

## Prerequisites

* The card must belong to your company.

## Request

### Headers

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

### Path parameters

| Name | Type   | Description     |
| ---- | ------ | --------------- |
| `id` | string | Card ID (UUID). |

### Query parameters

| Name         | Type    | Default | Description                                                                                                       |
| ------------ | ------- | ------- | ----------------------------------------------------------------------------------------------------------------- |
| `page`       | integer | `0`     | **0-indexed** page number. (Note: this differs from the rest of the API, which uses 1-indexed pagination.)        |
| `limit`      | integer | `50`    | Items per page. Max recommended: `100`.                                                                           |
| `fromDate`   | string  | —       | ISO 8601 date or datetime. Includes transactions on/after this instant.                                           |
| `toDate`     | string  | —       | ISO 8601 date or datetime. Includes transactions strictly before this instant.                                    |
| `type`       | string  | —       | Filter by transaction type. See [Glossary → Transaction](/getting-started/glossary#transaction) for values.       |
| `status`     | string  | —       | Filter by status. One of `PENDING`, `PROCESSING`, `SUCCESS`, `FAILED`.                                            |
| `includeRaw` | boolean | `false` | If `true`, attach the raw upstream-issuer payload to each transaction. For debugging.                             |
| `sync`       | boolean | `true`  | If `true` (default), force-refresh from the upstream issuer. Set `false` to read from Cartevo's local cache only. |

## Response

### 200 — Success

```json theme={null}
{
  "success": true,
  "statusCode": 200,
  "message": "12 items retrieved successfully",
  "data": [
    {
      "id": "txn_3f8a9b2c4d6e7f8a9b0c1d2e",
      "category": "CARD",
      "type": "AUTHORIZATION",
      "status": "SUCCESS",
      "amount": 12.5,
      "currency": "USD",
      "description": "Amazon.com - Seattle, US",
      "created_at": "2026-05-09T09:42:11.123Z",
      "card": {
        "id": "550e8400-e29b-41d4-a716-446655440000",
        "masked_pan": "**** **** **** 1111",
        "brand": "VISA"
      },
      "customer": {
        "id": "8d4f2a1b-5c3e-4d7f-9a6b-2e1c8f9d0a3b",
        "first_name": "John",
        "last_name": "Doe"
      }
    }
  ],
  "meta": {
    "page": 0,
    "limit": 50,
    "total": 12,
    "totalPages": 1
  }
}
```

| Field                | Type   | Description                                                                                                                    |
| -------------------- | ------ | ------------------------------------------------------------------------------------------------------------------------------ |
| `data[].id`          | string | Transaction ID. Use to fetch full detail or in support tickets.                                                                |
| `data[].category`    | string | Always `"CARD"` for this endpoint.                                                                                             |
| `data[].type`        | string | One of `AUTHORIZATION`, `SETTLEMENT`, `FUNDING`, `WITHDRAWAL`, `TERMINATION`, `DECLINE`, `REVERSAL`, `REFUND`, `CROSS-BORDER`. |
| `data[].status`      | string | One of `PENDING`, `PROCESSING`, `SUCCESS`, `FAILED`.                                                                           |
| `data[].amount`      | number | Transaction amount in `currency`.                                                                                              |
| `data[].description` | string | Human-readable description (often merchant + city for `AUTHORIZATION` / `SETTLEMENT`).                                         |
| `meta`               | object | Standard pagination metadata. See [API Conventions → Pagination](/getting-started/conventions#pagination).                     |

> **Pagination quirk:** This endpoint uses `page=0` for the first page (0-indexed), unlike the rest of the API. We are aligning this in a future release.

### Error responses

| Status | Trigger                                                                   |
| ------ | ------------------------------------------------------------------------- |
| `404`  | Card does not exist or belongs to another company.                        |
| `400`  | Invalid `fromDate` / `toDate` format, or invalid `type` / `status` value. |

## Code examples

```bash cURL theme={null}
curl -G https://api.cartevo.co/api/v1/cards/550e8400-e29b-41d4-a716-446655440000/transactions \
  -H "Authorization: Bearer $TOKEN" \
  --data-urlencode "fromDate=2026-04-01" \
  --data-urlencode "toDate=2026-05-01" \
  --data-urlencode "type=AUTHORIZATION" \
  --data-urlencode "limit=100"
```

```js Node.js (axios) theme={null}
const { data } = await axios.get(
  `https://api.cartevo.co/api/v1/cards/${cardId}/transactions`,
  {
    headers: { Authorization: `Bearer ${token}` },
    params: {
      fromDate: "2026-04-01",
      toDate: "2026-05-01",
      type: "AUTHORIZATION",
      limit: 100,
      page: 0,
    },
  }
);
```

## Related

* [Cards Overview → Supported transaction types](/api-reference/endpoint/Virtual-Card-Overview#supported-cards-transactions-types)
* [`GET /cards/{id}`](/api-reference/endpoint/get-card-by-id) — current card balance and status.
* [Webhooks → Transaction events](/api-reference/endpoint/webhook#transaction-events) — receive these events in real time instead of polling.


## OpenAPI

````yaml GET /cards/{id}/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:
  /cards/{id}/transactions:
    get:
      summary: Card transactions
      description: Retrieves a list of transactions for a specific card.
      parameters:
        - name: id
          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 card.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ListCardTransactionsResponse'
        '404':
          description: Card not found.
components:
  schemas:
    ListCardTransactionsResponse:
      allOf:
        - $ref: '#/components/schemas/StandardResponse'
        - type: object
          properties:
            data:
              type: array
              items:
                $ref: '#/components/schemas/CardTransaction'
            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
    CardTransaction:
      type: object
      properties:
        id:
          type: string
          format: uuid
          example: 7d1cdfa3-9904-4a17-bce5-092554170c0e
        category:
          type: string
          example: CARD
        type:
          type: string
          example: FUND
        amount:
          type: number
          example: 50
        status:
          type: string
          example: SUCCESS
        description:
          type: string
          example: 'Card funding: **** **** **** 5407'
        created_at:
          type: string
          format: date-time
        card:
          $ref: '#/components/schemas/CardDetails'
        customer:
          $ref: '#/components/schemas/CustomerSummary'
    Pagination:
      type: object
      properties:
        page:
          type: integer
          example: 1
        limit:
          type: integer
          example: 20
        total:
          type: integer
          example: 15
        totalPages:
          type: integer
          example: 1
    CardDetails:
      type: object
      properties:
        id:
          type: string
          format: uuid
          example: 91b3c6d6-111b-44da-9f81-16f019bebe8c
        status:
          type: string
          example: ACTIVE
        balance:
          type: number
          example: 0.45
        currency:
          type: string
          example: USD
        number:
          type: string
          description: Encrypted card number
          example: >-
            tkAlsp_eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJ2YWx1ZSI6IjUzNjAyNTI0ODM0NjU0MDciLCJpYXQiOjE3NjExNDg5NzR9.7sNid1b1pxmkpseiCR45E8Xj9hdmenZDovBcjVatBF0
        masked_pan:
          type: string
          example: '**** **** **** 5407'
        cvv:
          type: string
          description: Encrypted CVV
          example: >-
            tkAlsp_eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJ2YWx1ZSI6Ijg1NyIsImlhdCI6MTc2MTE0ODk3NH0.K7YHl0nzZTsScjUma_G5fyxYZFNnK-2SczstVtdMK1A
        expiry_month:
          type: integer
          example: 10
        expiry_year:
          type: integer
          example: 28
        is_virtual:
          type: boolean
          example: true
        is_physical:
          type: boolean
          example: false
        created_at:
          type: string
          format: date-time
    CustomerSummary:
      type: object
      properties:
        id:
          type: string
          format: uuid
          example: 4d4dad81-7899-4612-a9f6-133ce56a4507
        email:
          type: string
          format: email
          example: customer@example.com
        first_name:
          type: string
          example: John
        last_name:
          type: string
          example: Doe
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer

````