Get Card Transactions

curl --request GET \
  --url https://api.example.com/v1/card/transactions \
  --header 'Authorization: <authorization>' \
  --header 'x-client-key: <x-client-key>'

import requests

url = "https://api.example.com/v1/card/transactions"

headers = {
    "x-client-key": "<x-client-key>",
    "Authorization": "<authorization>"
}

response = requests.get(url, headers=headers)

print(response.text)

const options = {
  method: 'GET',
  headers: {'x-client-key': '<x-client-key>', Authorization: '<authorization>'}
};

fetch('https://api.example.com/v1/card/transactions', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://api.example.com/v1/card/transactions",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "GET",
  CURLOPT_HTTPHEADER => [
    "Authorization: <authorization>",
    "x-client-key: <x-client-key>"
  ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

package main

import (
	"fmt"
	"net/http"
	"io"
)

func main() {

	url := "https://api.example.com/v1/card/transactions"

	req, _ := http.NewRequest("GET", url, nil)

	req.Header.Add("x-client-key", "<x-client-key>")
	req.Header.Add("Authorization", "<authorization>")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

require 'uri'
require 'net/http'

url = URI("https://api.example.com/v1/card/transactions")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Get.new(url)
request["x-client-key"] = '<x-client-key>'
request["Authorization"] = '<authorization>'

response = http.request(request)
puts response.read_body

[
  {
    "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"
      }
    ]
  }
]

GET

card

transactions

Get Card Transactions

curl --request GET \
  --url https://api.example.com/v1/card/transactions \
  --header 'Authorization: <authorization>' \
  --header 'x-client-key: <x-client-key>'

import requests

url = "https://api.example.com/v1/card/transactions"

headers = {
    "x-client-key": "<x-client-key>",
    "Authorization": "<authorization>"
}

response = requests.get(url, headers=headers)

print(response.text)

const options = {
  method: 'GET',
  headers: {'x-client-key': '<x-client-key>', Authorization: '<authorization>'}
};

fetch('https://api.example.com/v1/card/transactions', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://api.example.com/v1/card/transactions",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "GET",
  CURLOPT_HTTPHEADER => [
    "Authorization: <authorization>",
    "x-client-key: <x-client-key>"
  ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

package main

import (
	"fmt"
	"net/http"
	"io"
)

func main() {

	url := "https://api.example.com/v1/card/transactions"

	req, _ := http.NewRequest("GET", url, nil)

	req.Header.Add("x-client-key", "<x-client-key>")
	req.Header.Add("Authorization", "<authorization>")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

require 'uri'
require 'net/http'

url = URI("https://api.example.com/v1/card/transactions")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Get.new(url)
request["x-client-key"] = '<x-client-key>'
request["Authorization"] = '<authorization>'

response = http.request(request)
puts response.read_body

[
  {
    "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"
      }
    ]
  }
]

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.

Real-Time DataTransactions appear in this endpoint within seconds of authorization. Pending transactions are included alongside confirmed ones with appropriate status indicators.

Authentication

This endpoint requires authentication via Bearer token:

Authorization: Bearer YOUR_ACCESS_TOKEN

Request

Headers

string

required

Your public API client key

boolean

default:false

Set to true to route requests to the US backend environment

string

required

Bearer token for authentication

Query Parameters

string

Start date for filtering transactions in ISO 8601 format (YYYY-MM-DD)Required: Only if dateTo is providedExample: 2024-10-24

string

End date for filtering transactions in ISO 8601 format (YYYY-MM-DD)Required: Only if dateFrom is providedExample: 2024-10-25Note: Both dateFrom and dateTo must be provided together

string

Search term to filter transactions by merchant name or locationExample: PayPal, Starbucks, AmazonBehavior: Case-insensitive partial matching

string

Comma-separated list of merchant category codes (MCC) to filter transactionsAccepted 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

number

default:0

Page number for pagination (0-indexed)Example: 0, 1, 5Note: If page doesn’t exist, returns page 0

Request Examples

curl -X GET "https://dev.api.baanx.com/v1/card/transactions" \
  -H "x-client-key: YOUR_CLIENT_KEY" \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN"

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"

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"

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"

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"

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);

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())

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();
};

Response

Success Response

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

string

Unique transaction identifier (UUID)

string

Unique card identifier

string

Last 4 digits of the card used

string

External transaction ID from payment processor

string

Transaction timestamp in ISO 8601 format

string

Transaction directionValues:

DEBIT - Money leaving the card (purchase, withdrawal)
CREDIT - Money entering the card (refund, reversal)

string

Merchant name and location information

string

Type of merchant or transaction contextExample: OutOfWalletOnline, InStore, ATM

number

Merchant Category Code (4-digit industry code)

string

Human-readable category derived from MCCValues: SUBSCRIPTIONS, FOOD, TRAVEL, ENTERTAINMENT, HEALTH, ATM, UTILITIES, MISC

string

Currency used for the card transaction (typically card’s base currency)Example: EUR, USD, GBP

string

Transaction amount in the card’s currency

string

Fees charged in the card’s currency

string

Currency used at the merchant (may differ from card currency)Example: USD, EUR, GBP

string

Transaction amount in the merchant’s original currency

string

Fees in the merchant’s original currency

string

Conversion rate used for billing between original and transaction currency

string

European Central Bank reference exchange rate at transaction time

string

Current transaction statusValues:

CONFIRMED - Transaction completed successfully
PENDING - Transaction authorized but not yet settled
DECLINED - Transaction authorization failed
REVERTED - Transaction was reversed/refunded

string

Explanation for declined transactions (only present when status=DECLINED)

array

Array of funding sources used to pay for this transaction

Show Funding Source Object

string

Unique funding source identifier

string

Wallet or account address used for funding

string

Blockchain network usedValues: linea, solana, ethereum

string

Blockchain transaction hash (for crypto funding sources)

string

Cryptocurrency or token usedExample: usdc, usdt

string

Amount deducted from this funding source

string

Network/transaction fees

string

Currency swap fee (if applicable)

string

Direction for this funding sourceValues: DEBIT, CREDIT

string

Status of this funding transactionValues: CONFIRMED, PENDING, DECLINED

string

Timestamp of the funding transaction

[
  {
    "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"
      }
    ]
  }
]

Error Responses

{
  "message": "Not authenticated"
}

{
  "message": "Not authorized"
}

{
  "message": "Invalid client key"
}

{
  "message": "Missing client key"
}

{
  "message": "Internal server error"
}

Pagination

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

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

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

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

async function searchTransactions(query: string) {
  return await getTransactions({
    searchKey: query
  });
}

Monthly Statement Data

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

CONFIRMED

Meaning: Transaction completed successfully and has been settledActions: Funds have been deducted/added, blockchain transactions confirmedDisplay: Show as final transaction in transaction history

PENDING

Meaning: Transaction authorized but not yet settledActions: Funds are held/reserved but not yet transferredDisplay: Show with pending indicator, may take 1-3 business days to confirmNote: Pending transactions can still be reversed

DECLINED

Meaning: Transaction authorization failedActions: No funds were transferredCommon Reasons:

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

Display: Show with declined indicator and reason if available

REVERTED

Meaning: Previously confirmed transaction was reversed/refundedActions: Funds returned to original funding sourceCommon Causes:

Merchant refund
Dispute resolution
Chargeback
Transaction cancellation

Display: Show as refund/reversal in transaction history

Edge Cases and Important Notes

Date Range ValidationBoth dateFrom and dateTo must be provided together. Providing only one will result in both being ignored.

Pagination BehaviorIf 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.

Currency ConversionTransactions 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.

Funding SourcesEach transaction may have multiple funding sources. The sum of all funding source amounts equals the total transaction amount plus fees.

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

Overview

Authentication

User

Card

Orders

Wallet

Delegation

Consent

Referral

Webhooks

Get Card Transactions

Overview

Authentication

Request

Headers

Query Parameters

Request Examples

Response

Success Response

Error Responses

Common Use Cases

Recent Transactions

Spending by Category

Transaction Search

Monthly Statement Data

Transaction Status Explained

Edge Cases and Important Notes

​Overview

​Authentication

​Request

​Headers

​Query Parameters

​Request Examples

​Response

​Success Response

​Error Responses

​Pagination

​Common Use Cases

​Recent Transactions

​Spending by Category

​Transaction Search

​Monthly Statement Data

​Transaction Status Explained

​Edge Cases and Important Notes

​Related Endpoints

Overview

Authentication

Request

Headers

Query Parameters

Request Examples

Response

Success Response

Error Responses

Pagination

Common Use Cases

Recent Transactions

Spending by Category

Transaction Search

Monthly Statement Data

Transaction Status Explained

Edge Cases and Important Notes

Related Endpoints