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

# Get Card Transactions

> Retrieve paginated card transaction history with optional filtering

## Overview

Retrieves detailed card transaction history with support for pagination and multiple filtering options. Returns comprehensive transaction information including merchant details, amounts, fees, currency conversions, and funding source breakdown.

<Info>
  **Real-Time Data**

  Transactions appear in this endpoint within seconds of authorization. Pending transactions are included alongside confirmed ones with appropriate status indicators.
</Info>

## Authentication

This endpoint requires authentication via Bearer token:

```bash theme={null}
Authorization: Bearer YOUR_ACCESS_TOKEN
```

## Request

### Headers

<ParamField header="x-client-key" type="string" required>
  Your public API client key
</ParamField>

<ParamField header="x-us-env" type="boolean" default={false}>
  Set to `true` to route requests to the US backend environment
</ParamField>

<ParamField header="Authorization" type="string" required>
  Bearer token for authentication
</ParamField>

### Query Parameters

<ParamField query="dateFrom" type="string">
  Start date for filtering transactions in ISO 8601 format (`YYYY-MM-DD`)

  **Required:** Only if `dateTo` is provided

  **Example:** `2024-10-24`
</ParamField>

<ParamField query="dateTo" type="string">
  End date for filtering transactions in ISO 8601 format (`YYYY-MM-DD`)

  **Required:** Only if `dateFrom` is provided

  **Example:** `2024-10-25`

  **Note:** Both `dateFrom` and `dateTo` must be provided together
</ParamField>

<ParamField query="searchKey" type="string">
  Search term to filter transactions by merchant name or location

  **Example:** `PayPal`, `Starbucks`, `Amazon`

  **Behavior:** Case-insensitive partial matching
</ParamField>

<ParamField query="mccCategories" type="string">
  Comma-separated list of merchant category codes (MCC) to filter transactions

  **Accepted Values:**

  * `SUBSCRIPTIONS` - Recurring subscription services
  * `FOOD` - Restaurants, grocery stores, food delivery
  * `TRAVEL` - Airlines, hotels, car rentals, transportation
  * `ENTERTAINMENT` - Movies, concerts, streaming services
  * `HEALTH` - Pharmacies, medical services, fitness
  * `ATM` - ATM withdrawals and fees
  * `UTILITIES` - Bills, utilities, telecommunications
  * `MISC` - Miscellaneous purchases

  **Example:** `FOOD,ENTERTAINMENT` or `SUBSCRIPTIONS`
</ParamField>

<ParamField query="page" type="number" default={0}>
  Page number for pagination (0-indexed)

  **Example:** `0`, `1`, `5`

  **Note:** If page doesn't exist, returns page 0
</ParamField>

### Request Examples

<CodeGroup>
  ```bash All Transactions theme={null}
  curl -X GET "https://dev.api.baanx.com/v1/card/transactions" \
    -H "x-client-key: YOUR_CLIENT_KEY" \
    -H "Authorization: Bearer YOUR_ACCESS_TOKEN"
  ```

  ```bash Date Range Filter theme={null}
  curl -X GET "https://dev.api.baanx.com/v1/card/transactions?dateFrom=2024-10-24&dateTo=2024-10-25" \
    -H "x-client-key: YOUR_CLIENT_KEY" \
    -H "Authorization: Bearer YOUR_ACCESS_TOKEN"
  ```

  ```bash Search by Merchant theme={null}
  curl -X GET "https://dev.api.baanx.com/v1/card/transactions?searchKey=PayPal" \
    -H "x-client-key: YOUR_CLIENT_KEY" \
    -H "Authorization: Bearer YOUR_ACCESS_TOKEN"
  ```

  ```bash Category Filter theme={null}
  curl -X GET "https://dev.api.baanx.com/v1/card/transactions?mccCategories=FOOD,ENTERTAINMENT" \
    -H "x-client-key: YOUR_CLIENT_KEY" \
    -H "Authorization: Bearer YOUR_ACCESS_TOKEN"
  ```

  ```bash Combined Filters with Pagination theme={null}
  curl -X GET "https://dev.api.baanx.com/v1/card/transactions?dateFrom=2024-10-01&dateTo=2024-10-31&mccCategories=FOOD&page=1" \
    -H "x-client-key: YOUR_CLIENT_KEY" \
    -H "Authorization: Bearer YOUR_ACCESS_TOKEN"
  ```

  ```javascript JavaScript theme={null}
  const params = new URLSearchParams({
    dateFrom: '2024-10-24',
    dateTo: '2024-10-25',
    searchKey: 'PayPal',
    mccCategories: 'SUBSCRIPTIONS',
    page: '0'
  });

  const response = await fetch(
    `https://dev.api.baanx.com/v1/card/transactions?${params}`,
    {
      headers: {
        'x-client-key': 'YOUR_CLIENT_KEY',
        'Authorization': 'Bearer YOUR_ACCESS_TOKEN'
      }
    }
  );

  const transactions = await response.json();
  console.log(transactions);
  ```

  ```python Python theme={null}
  import requests
  from datetime import date, timedelta

  url = "https://dev.api.baanx.com/v1/card/transactions"
  headers = {
      "x-client-key": "YOUR_CLIENT_KEY",
      "Authorization": "Bearer YOUR_ACCESS_TOKEN"
  }

  today = date.today()
  week_ago = today - timedelta(days=7)

  params = {
      "dateFrom": week_ago.isoformat(),
      "dateTo": today.isoformat(),
      "mccCategories": "FOOD,ENTERTAINMENT",
      "page": 0
  }

  response = requests.get(url, headers=headers, params=params)
  print(response.json())
  ```

  ```typescript TypeScript theme={null}
  interface TransactionFilters {
    dateFrom?: string;
    dateTo?: string;
    searchKey?: string;
    mccCategories?: string;
    page?: number;
  }

  interface Transaction {
    id: string;
    cardId: string;
    panLast4: string;
    transactionId: string;
    dateTime: string;
    sign: 'DEBIT' | 'CREDIT';
    merchantNameLocation: string;
    merchantType: string;
    mcc: number;
    mccCategory: string;
    transactionCurrency: string;
    amountInTransactionCurrency: string;
    feesInTransactionCurrency: string;
    originalCurrency: string;
    amountInOriginalCurrency: string;
    feesInOriginalCurrency: string;
    billingConversionRate: string;
    ecbRate: string;
    status: 'CONFIRMED' | 'PENDING' | 'DECLINED' | 'REVERTED';
    declineReason?: string;
    fundingSources: FundingSource[];
  }

  interface FundingSource {
    id: string;
    address: string;
    network: 'linea' | 'solana' | 'ethereum';
    txHash: string;
    currency: string;
    amount: string;
    fees: string;
    swapFee: string;
    sign: 'DEBIT' | 'CREDIT';
    status: 'CONFIRMED' | 'PENDING' | 'DECLINED';
    dateTime: string;
  }

  const getTransactions = async (
    filters: TransactionFilters = {}
  ): Promise<Transaction[]> => {
    const params = new URLSearchParams(
      Object.entries(filters)
        .filter(([_, v]) => v !== undefined)
        .map(([k, v]) => [k, String(v)])
    );

    const response = await fetch(
      `https://dev.api.baanx.com/v1/card/transactions?${params}`,
      {
        headers: {
          'x-client-key': 'YOUR_CLIENT_KEY',
          'Authorization': 'Bearer YOUR_ACCESS_TOKEN'
        }
      }
    );

    if (!response.ok) {
      throw new Error(`HTTP error! status: ${response.status}`);
    }

    return await response.json();
  };
  ```
</CodeGroup>

## Response

### Success Response

Returns an array of transaction objects, ordered by most recent first.

<ResponseField name="id" type="string">
  Unique transaction identifier (UUID)
</ResponseField>

<ResponseField name="cardId" type="string">
  Unique card identifier
</ResponseField>

<ResponseField name="panLast4" type="string">
  Last 4 digits of the card used
</ResponseField>

<ResponseField name="transactionId" type="string">
  External transaction ID from payment processor
</ResponseField>

<ResponseField name="dateTime" type="string">
  Transaction timestamp in ISO 8601 format
</ResponseField>

<ResponseField name="sign" type="string">
  Transaction direction

  **Values:**

  * `DEBIT` - Money leaving the card (purchase, withdrawal)
  * `CREDIT` - Money entering the card (refund, reversal)
</ResponseField>

<ResponseField name="merchantNameLocation" type="string">
  Merchant name and location information
</ResponseField>

<ResponseField name="merchantType" type="string">
  Type of merchant or transaction context

  **Example:** `OutOfWalletOnline`, `InStore`, `ATM`
</ResponseField>

<ResponseField name="mcc" type="number">
  Merchant Category Code (4-digit industry code)
</ResponseField>

<ResponseField name="mccCategory" type="string">
  Human-readable category derived from MCC

  **Values:** `SUBSCRIPTIONS`, `FOOD`, `TRAVEL`, `ENTERTAINMENT`, `HEALTH`, `ATM`, `UTILITIES`, `MISC`
</ResponseField>

<ResponseField name="transactionCurrency" type="string">
  Currency used for the card transaction (typically card's base currency)

  **Example:** `EUR`, `USD`, `GBP`
</ResponseField>

<ResponseField name="amountInTransactionCurrency" type="string">
  Transaction amount in the card's currency
</ResponseField>

<ResponseField name="feesInTransactionCurrency" type="string">
  Fees charged in the card's currency
</ResponseField>

<ResponseField name="originalCurrency" type="string">
  Currency used at the merchant (may differ from card currency)

  **Example:** `USD`, `EUR`, `GBP`
</ResponseField>

<ResponseField name="amountInOriginalCurrency" type="string">
  Transaction amount in the merchant's original currency
</ResponseField>

<ResponseField name="feesInOriginalCurrency" type="string">
  Fees in the merchant's original currency
</ResponseField>

<ResponseField name="billingConversionRate" type="string">
  Conversion rate used for billing between original and transaction currency
</ResponseField>

<ResponseField name="ecbRate" type="string">
  European Central Bank reference exchange rate at transaction time
</ResponseField>

<ResponseField name="status" type="string">
  Current transaction status

  **Values:**

  * `CONFIRMED` - Transaction completed successfully
  * `PENDING` - Transaction authorized but not yet settled
  * `DECLINED` - Transaction authorization failed
  * `REVERTED` - Transaction was reversed/refunded
</ResponseField>

<ResponseField name="declineReason" type="string">
  Explanation for declined transactions (only present when `status=DECLINED`)
</ResponseField>

<ResponseField name="fundingSources" type="array">
  Array of funding sources used to pay for this transaction

  <Expandable title="Funding Source Object">
    <ResponseField name="id" type="string">
      Unique funding source identifier
    </ResponseField>

    <ResponseField name="address" type="string">
      Wallet or account address used for funding
    </ResponseField>

    <ResponseField name="network" type="string">
      Blockchain network used

      **Values:** `linea`, `solana`, `ethereum`
    </ResponseField>

    <ResponseField name="txHash" type="string">
      Blockchain transaction hash (for crypto funding sources)
    </ResponseField>

    <ResponseField name="currency" type="string">
      Cryptocurrency or token used

      **Example:** `usdc`, `usdt`
    </ResponseField>

    <ResponseField name="amount" type="string">
      Amount deducted from this funding source
    </ResponseField>

    <ResponseField name="fees" type="string">
      Network/transaction fees
    </ResponseField>

    <ResponseField name="swapFee" type="string">
      Currency swap fee (if applicable)
    </ResponseField>

    <ResponseField name="sign" type="string">
      Direction for this funding source

      **Values:** `DEBIT`, `CREDIT`
    </ResponseField>

    <ResponseField name="status" type="string">
      Status of this funding transaction

      **Values:** `CONFIRMED`, `PENDING`, `DECLINED`
    </ResponseField>

    <ResponseField name="dateTime" type="string">
      Timestamp of the funding transaction
    </ResponseField>
  </Expandable>
</ResponseField>

<ResponseExample>
  ```json 200 - Success theme={null}
  [
    {
      "id": "100a99cf-f4d3-4fa1-9be9-2e9828b20ebb",
      "cardId": "1234537292209260487",
      "panLast4": "9189",
      "transactionId": "1122334477422",
      "dateTime": "2024-10-14T10:44:36.276Z",
      "sign": "DEBIT",
      "merchantNameLocation": "WWW.ALIEXPRESS.COM, LONDON",
      "merchantType": "OutOfWalletOnline",
      "mcc": 5964,
      "mccCategory": "MISC",
      "transactionCurrency": "EUR",
      "amountInTransactionCurrency": "0.79",
      "feesInTransactionCurrency": "0",
      "originalCurrency": "USD",
      "amountInOriginalCurrency": "0.85",
      "feesInOriginalCurrency": "0",
      "billingConversionRate": "0.9294117647058824",
      "ecbRate": "0.9161704076958315",
      "status": "CONFIRMED",
      "declineReason": "",
      "fundingSources": [
        {
          "id": "3181a37a-07fa-41dc-b423-6c2db07a7ba1",
          "address": "0x3a11a86cf218c448be519728cd3ac5c741fb3424",
          "network": "linea",
          "txHash": "0xb92de09d893e8162b0861c0f7321f68df02212efbc58f208839ae3f176d89638",
          "currency": "usdc",
          "amount": "0.104201",
          "fees": "0",
          "swapFee": "0.00208",
          "sign": "DEBIT",
          "status": "CONFIRMED",
          "dateTime": "2024-10-14T10:44:36.288Z"
        }
      ]
    }
  ]
  ```
</ResponseExample>

## Error Responses

<ResponseExample>
  ```json 401 - Unauthorized theme={null}
  {
    "message": "Not authenticated"
  }
  ```

  ```json 403 - Forbidden theme={null}
  {
    "message": "Not authorized"
  }
  ```

  ```json 498 - Invalid Client Key theme={null}
  {
    "message": "Invalid client key"
  }
  ```

  ```json 499 - Missing Client Key theme={null}
  {
    "message": "Missing client key"
  }
  ```

  ```json 500 - Internal Server Error theme={null}
  {
    "message": "Internal server error"
  }
  ```
</ResponseExample>

## Pagination

Transactions are returned in pages. The default page size is determined by the backend configuration (typically 20-50 transactions per page).

```typescript theme={null}
async function getAllTransactionsForMonth(year: number, month: number) {
  const transactions: Transaction[] = [];
  let page = 0;
  let hasMore = true;

  const dateFrom = `${year}-${String(month).padStart(2, '0')}-01`;
  const dateTo = new Date(year, month, 0).toISOString().split('T')[0];

  while (hasMore) {
    const pageData = await getTransactions({
      dateFrom,
      dateTo,
      page
    });

    transactions.push(...pageData);

    hasMore = pageData.length > 0;
    page++;
  }

  return transactions;
}
```

## Common Use Cases

### Recent Transactions

```typescript theme={null}
async function getRecentTransactions(days: number = 7) {
  const dateTo = new Date().toISOString().split('T')[0];
  const dateFrom = new Date(Date.now() - days * 24 * 60 * 60 * 1000)
    .toISOString()
    .split('T')[0];

  return await getTransactions({ dateFrom, dateTo });
}
```

### Spending by Category

```typescript theme={null}
async function getSpendingByCategory(category: string) {
  const transactions = await getTransactions({
    mccCategories: category
  });

  const total = transactions.reduce((sum, tx) => {
    if (tx.sign === 'DEBIT' && tx.status === 'CONFIRMED') {
      return sum + parseFloat(tx.amountInTransactionCurrency);
    }
    return sum;
  }, 0);

  return { category, total, count: transactions.length };
}
```

### Transaction Search

```typescript theme={null}
async function searchTransactions(query: string) {
  return await getTransactions({
    searchKey: query
  });
}
```

### Monthly Statement Data

```typescript theme={null}
async function getMonthlyStatement(year: number, month: number) {
  const dateFrom = `${year}-${String(month).padStart(2, '0')}-01`;
  const lastDay = new Date(year, month, 0).getDate();
  const dateTo = `${year}-${String(month).padStart(2, '0')}-${lastDay}`;

  const transactions = await getTransactions({ dateFrom, dateTo });

  const summary = {
    totalSpent: 0,
    totalRefunds: 0,
    transactionCount: transactions.length,
    byCategory: {} as Record<string, number>
  };

  transactions.forEach(tx => {
    if (tx.status === 'CONFIRMED') {
      const amount = parseFloat(tx.amountInTransactionCurrency);

      if (tx.sign === 'DEBIT') {
        summary.totalSpent += amount;
      } else if (tx.sign === 'CREDIT') {
        summary.totalRefunds += amount;
      }

      if (!summary.byCategory[tx.mccCategory]) {
        summary.byCategory[tx.mccCategory] = 0;
      }
      summary.byCategory[tx.mccCategory] += amount;
    }
  });

  return summary;
}
```

## Transaction Status Explained

<AccordionGroup>
  <Accordion title="CONFIRMED">
    **Meaning:** Transaction completed successfully and has been settled

    **Actions:** Funds have been deducted/added, blockchain transactions confirmed

    **Display:** Show as final transaction in transaction history
  </Accordion>

  <Accordion title="PENDING">
    **Meaning:** Transaction authorized but not yet settled

    **Actions:** Funds are held/reserved but not yet transferred

    **Display:** Show with pending indicator, may take 1-3 business days to confirm

    **Note:** Pending transactions can still be reversed
  </Accordion>

  <Accordion title="DECLINED">
    **Meaning:** Transaction authorization failed

    **Actions:** No funds were transferred

    **Common Reasons:**

    * Insufficient balance
    * Card frozen or blocked
    * Security concerns
    * Merchant restrictions
    * Network issues

    **Display:** Show with declined indicator and reason if available
  </Accordion>

  <Accordion title="REVERTED">
    **Meaning:** Previously confirmed transaction was reversed/refunded

    **Actions:** Funds returned to original funding source

    **Common Causes:**

    * Merchant refund
    * Dispute resolution
    * Chargeback
    * Transaction cancellation

    **Display:** Show as refund/reversal in transaction history
  </Accordion>
</AccordionGroup>

## Edge Cases and Important Notes

<Warning>
  **Date Range Validation**

  Both `dateFrom` and `dateTo` must be provided together. Providing only one will result in both being ignored.
</Warning>

<Note>
  **Pagination Behavior**

  If you request a page that doesn't exist (e.g., page 100 when only 10 pages exist), the API returns page 0 instead of an error.
</Note>

<Info>
  **Currency Conversion**

  Transactions show both the original merchant currency and the card's transaction currency, along with the conversion rate used. This transparency helps users understand exchange rate costs.
</Info>

<Note>
  **Funding Sources**

  Each transaction may have multiple funding sources. The sum of all funding source amounts equals the total transaction amount plus fees.
</Note>

## Related Endpoints

* `GET /v1/card/transactions/statement` - Generate downloadable transaction statement (CSV/PDF)
* `GET /v1/card/status` - Get card information
* `POST /v1/card/freeze` - Freeze card to prevent future transactions