Skip to main content

Transactions

A transaction is money that has moved. Every debit and credit on an account appears as one, and it is the record to reconcile against.

What you can read​

curl "$ALETA_BASE_URL/v1/transactions?account_id=acct_01HX8ZQ2K4M7P9RSTVWXYZAB" \
  -H "Authorization: Bearer $ALETA_ACCESS_TOKEN"
One transaction
{
  "id": "txn_01HX8ZQ2K4M7P9RSTVWXYZAB",
  "object": "transaction",
  "account_id": "acct_01HX8ZQ2K4M7P9RSTVWXYZAB",
  "card_id": "card_01HX8ZQ2K4M7P9RSTVWXYZAB",
  "type": "purchase",
  "direction": "debit",
  "amount": { "amount": 4600, "currency": "SGD" },
  "merchant": { "name": "Kopi Roastery", "mcc": "5814", "country": "SGP" },
  "settled_at": "2026-07-30T09:12:00Z",
  "created_at": "2026-07-30T09:12:00Z"
}

type says what the movement was for: purchase, withdrawal, transfer, load, fee, refund or adjustment. direction says which way it went, and amount is always positive.

What to build on​

Reconcile against transactions. They are the settled record, and in phase 1 they are the only record you receive. A ledger built from anything else will disagree with ours.

A purchase appears when it settles. That can be hours or days after the cardholder paid, because clearing runs on the merchant's schedule rather than yours. Treat "no transaction yet" as "not settled yet", never as "no purchase", and keep your reconciliation window open long enough to catch the slow ones.

The settled amount can differ from what the cardholder saw at the till. A restaurant tip is the everyday case. amount is what actually moved, so post that figure and not the one the terminal displayed.

Expect authorization_id to be absent. Nothing populates it while the authorization stage is unexposed, so read it as optional and left join on it if you join at all. Code that inner joins on it today returns nothing.

Balances live on the account rather than the card. See balances: ledger vs available.

Last updated on