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

# List Transactions

> Retrieve card transactions for your business. GET /transactions. Requires transactions:read scope.

## Overview

Returns a paginated list of card transactions for your business, scoped to the API key's environment. Includes authorizations, clearings, declines, reversals, and fees.

By default, results span the last 30 days. The maximum date range is **92 days** — use multiple requests with different date windows for longer histories.

## Query Parameters

| Parameter      | Type    | Default     | Description                                                         |
| -------------- | ------- | ----------- | ------------------------------------------------------------------- |
| `limit`        | integer | 20          | Results per page (max 100)                                          |
| `offset`       | integer | 0           | Number of records to skip                                           |
| `from`         | string  | 30 days ago | Start date/time (`YYYY-MM-DD` or ISO 8601)                          |
| `to`           | string  | now         | End date/time (`YYYY-MM-DD` or ISO 8601)                            |
| `cardId`       | string  | —           | Filter to a specific card                                           |
| `cardholderId` | string  | —           | Filter to a specific cardholder                                     |
| `programId`    | string  | —           | Filter to a specific program                                        |
| `type`         | string  | —           | `AUTHORIZATION`, `CLEARING`, `REVERSAL`, `REFUND`, `DECLINE`, `FEE` |
| `status`       | string  | —           | `PENDING`, `CLEARED`, `REVERSED`, `DECLINED`                        |
| `search`       | string  | —           | Search by merchant name                                             |

## Example

<CodeGroup>
  ```bash cURL theme={null}
  curl -G https://api.fyatu.com/api/v3.20/transactions \
    -H "Authorization: Bearer $FYATU_API_KEY" \
    -d cardId=crd_01HXYZ5555ABCDEF1111 \
    -d from=2026-05-01 \
    -d to=2026-05-31 \
    -d limit=50
  ```

  ```javascript Node.js theme={null}
  const params = new URLSearchParams({
    cardId: 'crd_01HXYZ5555ABCDEF1111',
    from: '2026-05-01',
    to: '2026-05-31',
    limit: '50'
  });
  const resp = await fetch(
    `https://api.fyatu.com/api/v3.20/transactions?${params}`,
    { headers: { 'Authorization': `Bearer ${process.env.FYATU_API_KEY}` } }
  );
  const body = await resp.json();
  console.log(`${body.pagination.total} transactions`);
  for (const tx of body.data) {
    console.log(tx.transactionId, tx.type, tx.amount.displayValue);
  }
  ```

  ```python Python theme={null}
  import os, requests

  resp = requests.get(
      'https://api.fyatu.com/api/v3.20/transactions',
      headers={'Authorization': f'Bearer {os.environ["FYATU_API_KEY"]}'},
      params={
          'cardId': 'crd_01HXYZ5555ABCDEF1111',
          'from': '2026-05-01',
          'to': '2026-05-31',
          'limit': 50
      }
  )
  body = resp.json()
  for tx in body['data']:
      print(tx['transactionId'], tx['type'], tx['amount']['displayValue'])
  ```
</CodeGroup>

## Success Response (200)

```json theme={null}
{
  "success": true,
  "status": 200,
  "message": "Transactions retrieved",
  "data": [
    {
      "transactionId": "txn_01HXYZ8888ABCDEF9999",
      "type":          "AUTHORIZATION",
      "status":        "PENDING",
      "amount": {
        "value":        2999,
        "currency":     "USD",
        "displayValue": "29.99"
      },
      "merchant": {
        "name":           "Amazon",
        "city":           "Seattle",
        "country":        "US",
        "mcc":            "5999",
        "mccDescription": "Miscellaneous General Merchandise"
      },
      "cardId":               "crd_01HXYZ5555ABCDEF1111",
      "cardholderId":         "chl_01HXYZ1234ABCDEF5678",
      "programId":            "prg_01HXYZ9876ABCDEF0000",
      "relatedTransactionId": null,
      "environment":          "LIVE",
      "declineReason":        null,
      "processedAt":          null,
      "createdAt":            "2026-05-22T14:30:00Z"
    }
  ],
  "pagination": {
    "total":   47,
    "limit":   50,
    "offset":  0,
    "hasMore": false
  },
  "meta": {
    "requestId": "req_01HXY123456ABCDEF",
    "platform": "Fyatu CaaS",
    "timestamp": "2026-05-22T15:00:00Z"
  }
}
```

## Transaction Types

| Type            | Description                                        |
| --------------- | -------------------------------------------------- |
| `AUTHORIZATION` | Purchase hold — funds reserved but not yet settled |
| `CLEARING`      | Settled purchase — authorization confirmed         |
| `REVERSAL`      | Authorization reversed before settlement           |
| `REFUND`        | Merchant-initiated refund after clearing           |
| `DECLINE`       | Declined authorization attempt                     |
| `FEE`           | Fee charge (e.g. cross-border fee, decline fee)    |

## Error Codes

| Code                  | HTTP | Cause                                 |
| --------------------- | ---- | ------------------------------------- |
| `DATE_RANGE_TOO_WIDE` | 422  | Date range exceeds the 92-day maximum |
| `VALIDATION_ERROR`    | 422  | Invalid date format or parameters     |
| `INSUFFICIENT_SCOPE`  | 403  | Key lacks `transactions:read` scope   |


## OpenAPI

````yaml v3.20/openapi.json GET /transactions
openapi: 3.1.0
info:
  title: FYATU CaaS API v3.20
  description: >-
    FYATU Cards-as-a-Service API — API key authentication, Cardholder
    lifecycle, Card issuance, Transactions, Webhooks, and Programs.
  version: 3.20.0
  contact:
    name: FYATU Support
    url: https://fyatu.com
    email: support@fyatu.com
servers:
  - url: https://api.fyatu.com/api/v3.20
    description: >-
      FYATU CaaS API — the environment (LIVE or SANDBOX) is determined by the
      API key, not the URL
security:
  - BearerAuth: []
tags:
  - name: Meta
    description: Liveness, account info, and supported event types
  - name: Account
    description: Account-level balance and funding status
  - name: Programs
    description: Read card program configuration
  - name: Cardholders
    description: Create and manage cardholder profiles
  - name: Cards
    description: Issue, fund, freeze, and terminate virtual cards
  - name: Transactions
    description: Read-only card transaction history
  - name: Webhooks
    description: Manage webhook endpoints for real-time event delivery
  - name: Products
    description: Read card product configurations
paths:
  /transactions:
    get:
      tags:
        - Account
      summary: List transactions
      description: >-
        Returns a paginated list of program-balance movements for the
        authenticated business. Includes deposits, card fundings, issuances,
        invoice payments, and reversals. Default date range is 30 days; maximum
        is 92 days.
      operationId: listTransactions
      parameters:
        - name: limit
          in: query
          schema:
            type: integer
            minimum: 1
            maximum: 100
            default: 20
        - name: offset
          in: query
          schema:
            type: integer
            minimum: 0
            default: 0
        - name: from
          in: query
          schema:
            type: string
          description: Start date (YYYY-MM-DD or ISO 8601). Defaults to 30 days ago.
          example: '2026-05-01'
        - name: to
          in: query
          schema:
            type: string
          description: End date (YYYY-MM-DD or ISO 8601). Defaults to now.
          example: '2026-05-31'
        - name: type
          in: query
          schema:
            type: string
            enum:
              - DEPOSIT
              - WITHDRAWAL
              - CARD_FUNDING
              - CARD_WITHDRAWAL
              - CARD_ISSUANCE
              - CARD_TERMINATION_REFUND
              - INVOICE_PAYMENT
              - REVERSAL
        - name: status
          in: query
          schema:
            type: string
            enum:
              - PENDING
              - SETTLED
              - FAILED
              - REVERSED
        - name: direction
          in: query
          schema:
            type: string
            enum:
              - CREDIT
              - DEBIT
        - name: cardId
          in: query
          schema:
            type: string
          description: Filter to movements related to a specific card
        - name: search
          in: query
          schema:
            type: string
          description: Search by memo or reference
      responses:
        '200':
          description: Transactions retrieved
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/TransactionListResponse'
              example:
                success: true
                status: 200
                message: Transactions retrieved
                data:
                  - transactionId: txn_01HXYZ8888ABCDEF9999
                    type: CARD_FUNDING
                    direction: DEBIT
                    status: SETTLED
                    amount: 500
                    currency: USD
                    fee: 0
                    reference: fund_01HXYZ5555ABCDEF1111
                    account: prg_01HXYZ9876ABCDEF0000
                    memo: Card funding — crd_01HXYZ5555ABCDEF1111
                    balanceBefore: 10000
                    balanceAfter: 9500
                    relatedTransactionId: null
                    completedAt: '2026-05-22T14:32:00Z'
                    createdAt: '2026-05-22T14:30:00Z'
                    cardId: crd_01HXYZ5555ABCDEF1111
                pagination:
                  total: 47
                  limit: 20
                  offset: 0
                  hasMore: true
                meta:
                  requestId: req_a1b2c3d4e5f6a7b8c9d0e1f2
                  platform: Fyatu CaaS
                  timestamp: '2026-05-22T15:00:00Z'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '422':
          description: Date range exceeds 92 days
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
              example:
                success: false
                status: 422
                message: Date range exceeds 92-day maximum
                error:
                  code: DATE_RANGE_TOO_WIDE
                  detail: Date range must not exceed 92 days
                meta:
                  requestId: req_a1b2c3d4e5f6a7b8c9d0e1f2
                  platform: Fyatu CaaS
                  timestamp: '2026-05-22T15:00:00Z'
        '429':
          $ref: '#/components/responses/RateLimitExceeded'
        '500':
          $ref: '#/components/responses/InternalError'
components:
  schemas:
    TransactionListResponse:
      type: object
      properties:
        success:
          type: boolean
          example: true
        status:
          type: integer
          example: 200
        message:
          type: string
          example: Transactions retrieved
        data:
          type: array
          items:
            $ref: '#/components/schemas/Transaction'
        pagination:
          $ref: '#/components/schemas/Pagination'
        meta:
          $ref: '#/components/schemas/Meta'
    Error:
      type: object
      properties:
        success:
          type: boolean
          example: false
        status:
          type: integer
          example: 422
        message:
          type: string
          example: Human readable message
        error:
          $ref: '#/components/schemas/ErrorBody'
        meta:
          $ref: '#/components/schemas/Meta'
    Transaction:
      type: object
      properties:
        transactionId:
          type: string
          example: txn_01HXYZ8888ABCDEF9999
        type:
          type: string
          enum:
            - AUTHORIZATION
            - CLEARING
            - REVERSAL
            - FEE
          example: AUTHORIZATION
        status:
          type: string
          enum:
            - APPROVED
            - DECLINED
            - REVERSED
          example: PENDING
        amount:
          $ref: '#/components/schemas/TransactionAmount'
        merchant:
          $ref: '#/components/schemas/TransactionMerchant'
        cardId:
          type: string
          example: crd_01HXYZ5555ABCDEF1111
        cardholderId:
          type: string
          example: chl_01HXYZ1234ABCDEF5678
        programId:
          type: string
          example: prg_01HXYZ9876ABCDEF0000
        relatedTransactionId:
          type: string
          nullable: true
          description: Set for reversals and refunds
          example: null
        environment:
          type: string
          enum:
            - LIVE
            - SANDBOX
          example: LIVE
        declineReason:
          type: string
          nullable: true
          example: null
        processedAt:
          type: string
          format: date-time
          nullable: true
          example: null
        createdAt:
          type: string
          format: date-time
          example: '2026-05-22T14:30:00Z'
    Pagination:
      type: object
      properties:
        total:
          type: integer
          example: 47
        limit:
          type: integer
          example: 20
        offset:
          type: integer
          example: 0
        hasMore:
          type: boolean
          example: true
    Meta:
      type: object
      properties:
        requestId:
          type: string
          example: req_a1b2c3d4e5f6a7b8c9d0e1f2
        platform:
          type: string
          example: Fyatu CaaS
        timestamp:
          type: string
          format: date-time
          example: '2026-05-22T15:00:00Z'
    ErrorBody:
      type: object
      properties:
        code:
          type: string
          example: VALIDATION_ERROR
        detail:
          type: string
          example: dateOfBirth must be in YYYY-MM-DD format
    TransactionAmount:
      type: object
      properties:
        value:
          type: integer
          format: int64
          description: Amount in cents
          example: 2999
        currency:
          type: string
          example: USD
        displayValue:
          type: string
          description: Human-readable amount without currency symbol
          example: '29.99'
    TransactionMerchant:
      type: object
      properties:
        name:
          type: string
          nullable: true
          example: Amazon
        city:
          type: string
          nullable: true
          example: Seattle
        country:
          type: string
          nullable: true
          example: US
        mcc:
          type: string
          nullable: true
          description: ISO 18245 Merchant Category Code
          example: '5999'
        mccDescription:
          type: string
          nullable: true
          example: Miscellaneous General Merchandise
  responses:
    Unauthorized:
      description: Missing or invalid API key
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
          examples:
            missing:
              summary: API key missing
              value:
                success: false
                status: 401
                message: API key is required
                error:
                  code: AUTH_TOKEN_MISSING
                  detail: API key is required
                meta:
                  requestId: req_a1b2c3d4e5f6a7b8c9d0e1f2
                  platform: Fyatu CaaS
                  timestamp: '2026-05-22T15:00:00Z'
            invalid:
              summary: API key invalid
              value:
                success: false
                status: 401
                message: Invalid API key
                error:
                  code: AUTH_TOKEN_INVALID
                  detail: Invalid API key
                meta:
                  requestId: req_a1b2c3d4e5f6a7b8c9d0e1f2
                  platform: Fyatu CaaS
                  timestamp: '2026-05-22T15:00:00Z'
    Forbidden:
      description: Scope denied or business suspended
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
          example:
            success: false
            status: 403
            message: Scope denied
            error:
              code: INSUFFICIENT_SCOPE
              detail: This endpoint requires the cards:write scope
            meta:
              requestId: req_a1b2c3d4e5f6a7b8c9d0e1f2
              platform: Fyatu CaaS
              timestamp: '2026-05-22T15:00:00Z'
    RateLimitExceeded:
      description: Rate limit exceeded
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
          example:
            success: false
            status: 429
            message: Rate limit exceeded
            error:
              code: RATE_LIMIT_EXCEEDED
              detail: Too many requests
            meta:
              requestId: req_a1b2c3d4e5f6a7b8c9d0e1f2
              platform: Fyatu CaaS
              timestamp: '2026-05-22T15:00:00Z'
    InternalError:
      description: Unexpected server error
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
          example:
            success: false
            status: 500
            message: Internal error
            error:
              code: INTERNAL_ERROR
              detail: An unexpected error occurred
            meta:
              requestId: req_a1b2c3d4e5f6a7b8c9d0e1f2
              platform: Fyatu CaaS
              timestamp: '2026-05-22T15:00:00Z'
  securitySchemes:
    BearerAuth:
      type: http
      scheme: bearer
      description: >-
        API key from the FYATU CaaS portal. Pass as `Authorization: Bearer
        <key>`.

````