Transaction Object

A Transaction represents a single financial movement in an account, such as a purchase, transfer, payment, or deposit. Transactions include amount, description, category, and settlement status.

Attributes

Field	Type	Description
id	string	Unique identifier for the transaction. Format: `txn_ULID`
accountId	string	ID of the parent account
amount	number	Transaction amount in the smallest currency unit. Negative for debits (purchases, payments, withdrawals), positive for credits (deposits, refunds, incoming transfers)
currency	string	ISO 4217 currency code (e.g., `CLP`, `USD`)
description	string	Transaction description as provided by the bank. May include merchant name, reference numbers, or transfer details
category	string \| null	Transaction category. Possible values: `groceries`, `utilities`, `transport`, `entertainment`, `health`, `transfer`, `payment`, `income`, `other`
details	object \| null	The extra detail the institution itself reports for this movement — typically what it shows on the transaction receipt. See Transaction details below
transactionDate	string	Date when the transaction occurred, in ISO 8601 format. Time component is typically `00:00:00.000Z` as banks usually provide date-only precision
status	string	Settlement status: `pending` (not yet settled, may change or be reversed) or `posted` (settled and finalized)
createdAt	string	ISO 8601 timestamp when the transaction was first synced to Araucaria
previousTransactionId	string \| undefined	Id of the transaction this one replaced. Present only when a pending transaction on a Plaid-linked connection posted — see Plaid Pending → Posted Transactions

Amount Sign Convention

Transaction amounts follow standard accounting conventions:

Negative amounts (-) represent money leaving the account: purchases, bill payments, outgoing transfers, fees
Positive amounts (+) represent money entering the account: deposits, refunds, incoming transfers, interest

Transaction Status

pending - Transaction is authorized but not yet settled. Amount may change (e.g., tip added) or transaction may be reversed
posted - Transaction has been settled and is final. Will not change unless a separate reversal transaction occurs

💡 Plaid: Pending → Posted

On Plaid-linked connections, a pending transaction posting is a delete + new row, not an update — the old id is gone and previousTransactionId on the new row is your only link back to it. See Plaid Pending → Posted Transactions for the recommended way to handle this.

Example

json

              {
  "id": "txn_01HQ3K5J7X8Y9Z0A1B2C3D4E5F",
  "accountId": "acc_01HQ3K5J7X8Y9Z0A1B2C3D4E5F",
  "amount": -137900,
  "currency": "CLP",
  "description": "Enel",
  "category": "utilities",
  "transactionDate": "2024-01-15T00:00:00.000Z",
  "status": "posted",
  "createdAt": "2024-01-15T10:30:00Z"
}
            

Example: Plaid Pending → Posted

A posted transaction that promoted a Plaid pending transaction carries previousTransactionId:

json

              {
  "id": "txn_01HQ3K5J7X8Y9Z0A1B2C3D4E7H",
  "accountId": "acc_01HQ3K5J7X8Y9Z0A1B2C3D4E5F",
  "amount": -450,
  "currency": "USD",
  "description": "Coffee Shop",
  "transactionDate": "2024-01-16",
  "status": "posted",
  "createdAt": "2024-01-16T09:15:00Z",
  "previousTransactionId": "txn_01HQ3K5J7X8Y9Z0A1B2C3D4E5G"
}
            

Transaction details

Institutions report more about a movement than an amount and a description. details carries that extra reporting through unchanged — for many institutions it is the same set of fields shown on the transaction receipt, such as who the counterparty was, which institution and account the funds came from, and the time of day the movement was made.

{
  "id": "txn_01HQ3K5J7X8Y9Z0A1B2C3D4E5F",
  "amount": 250000,
  "description": "Transferencia recibida de Comercial Ejemplo SpA",
  "transactionDate": "2024-01-15",
  "details": {
    "v": 1,
    "source": "cl_banco_bci_pyme",
    "fields": [
      { "key": "fecha_de_transferencia", "label": "Fecha de transferencia", "value": "14/01/2024" },
      { "key": "hora_de_transferencia", "label": "Hora de transferencia", "value": "18:42" },
      { "key": "fecha_contable", "label": "Fecha contable", "value": "15/01/2024" },
      { "key": "rut_origen", "label": "Rut Origen", "value": "76123456-7" },
      { "key": "razon_social", "label": "Razon Social", "value": "COMERCIAL EJEMPLO SPA" },
      { "key": "banco_origen", "label": "Banco Origen", "value": "Banco de Chile" }
    ]
  }
}

The envelope

Field	Type	Description
v	number	Envelope version. Incremented only for a breaking change to this shape
source	string	The institution whose vocabulary `fields` uses. Lets you branch on the institution without looking up the connection
fields	array	The detail fields, ordered as the institution returned them — so rendering them in order mirrors how the institution presents the receipt
fields[].key	string	Stable key to match on, derived from the institution's own label
fields[].label	string	The institution's own label, suitable for display
fields[].value	string \| number \| boolean	The value exactly as the institution reported it

Four things to code for

Every field is optional, and details itself may be null. What appears depends on the movement, not just the institution: a transfer carries counterparty fields that a fee or interest row does not. Never assume a key is present.
Values are passed through verbatim. We do not reformat them, so formats follow whatever the institution reports and can differ between two keys on the same transaction. Check each key's documented format in the per-institution reference before parsing.
Keys derive from the institution's own labels. They are stable in practice but best-effort by contract — if an institution renames a label, its key changes with it. Some institutions use different labels for the same idea depending on the movement type, so you may need to check more than one key.
There is no backfill. Transactions synced before this field existed have details: null permanently. A connection starts populating it on its next sync.