Skip to main content
A transaction is one entry on a financial account, returned by GET /v1/financial_accounts/{fa_id}/transactions and GET /v1/financial_accounts/{fa_id}/transactions/{tx_id}. Most money movements produce one transaction. Wire fees, reversals and returns add more, grouped by source.id.

​
Status

completed is not final. ACH returns can arrive up to 60 business days after settlement.
Treat unknown as indeterminate and poll again later. It resolves once Nova classifies the state.

​
Lifecycle

Your application should assume that a transaction can first appear in any state. In practice, transactions start as either pending or processing, a return first appears as completed.

​
Source

source describes what caused the entry. It is null while the transaction exists only in Nova, before it is handed to the bank partner.
ach covers every bank payment other than wire, including rails added later. New source.type values may be added, so handle values you don’t recognize.
source.id is shared by every entry of one money movement. Use it to group a transfer with its fees, reversal or return. Entries in one group can have different source.type values: a wire entry’s fee is other. memo is only present on wire sources.

​
Workflow

workflow links the transaction to the Nova record that caused it. It is null for bank activity that did not start in Nova.
More workflow types will be added. Treat types you do not recognize as opaque.

​
Amounts and balances

amount follows the bank statement convention. Debits are negative and credits are positive. Use the sign for direction, not source.type. balance is the account’s running balance after the entry. A null balance is not zero: the bank holds no entry for the transaction yet, or it was rejected or cancelled before reaching the bank.

​
Dates

Post ledger entries on settled_at. It is set once the bank settles the transaction, and it is the default sort. created_at is when the entry was created, not when the money moved. A return’s entry is created days or weeks after the original transaction.

​
Reversals and returns

A reversal is two transactions: the original and an offsetting entry with the opposite sign and the same source.id. Group on source.id to show them as one line. A return does not change the original transaction’s amount. The original moves to returned, and the money coming back arrives as a new transaction that first appears as completed. For a wire that is sent, then returned:
  1. The wire tx_1 settles: status: "completed"
  2. Days later, the recipient’s bank rejects it: tx_1 becomes status: "returned"
  3. The return tx_2 is created and settles: status: "completed"
Last modified on October 27, 2026