Skip to main content
Retrieve transaction history for any card issued through your partner account.

​
List card transactions

Fetch transactions for a specific card using cursor-based pagination: 
curl "https://api.contro.me/v1/partner/cards/{cardId}/transactions?limit=20" \
  -H "x-contro-api-key: $CONTRO_API_KEY"

​
Query parameters

ParameterTypeDefaultDescription
cursorstring—Pagination cursor from previous response
limitinteger20Items per page (1–100)

​
Response

{
  "data": [
    {
      "id": "tx_abc123",
      "type": "purchase",
      "amount": 42.50,
      "currency": "USD",
      "status": "completed",
      "merchant": "Coffee Shop",
      "timestamp": "2026-03-20T14:30:00Z"
    }
  ],
  "hasMore": true,
  "nextCursor": "cursor_def456"
}

​
Transaction fields

FieldTypeDescription
idstringTransaction ID. Example: "tx_abc123"
typestringTransaction type. One of purchase, refund, withdrawal, fee
amountnumber | nullTransaction amount in the card’s currency unit. Example: 42.50
currencystring | nullISO 4217 currency code. Example: "USD"
statusstringTransaction status. One of pending, completed, declined, reversed
merchantstring | nullMerchant name. Example: "Coffee Shop"
timestampstringISO 8601 transaction timestamp. Example: "2026-03-20T14:30:00Z"

​
Pagination

To paginate through all transactions, pass the nextCursor from each response: 
let cursor: string | undefined;
const allTransactions = [];

do {
  const url = new URL(`${BASE_URL}/partner/cards/${cardId}/transactions`);
  url.searchParams.set("limit", "100");
  if (cursor) url.searchParams.set("cursor", cursor);

  const page = await fetch(url, { headers }).then((r) => r.json());
  allTransactions.push(...page.data);
  cursor = page.hasMore ? page.nextCursor : undefined;
} while (cursor);

​
Real-time notifications

For real-time transaction updates, configure webhooks to receive events as transactions occur, rather than polling.