> ## Documentation Index
> Fetch the complete documentation index at: https://docs.nova.net/llms.txt
> Use this file to discover all available pages before exploring further.

# Transaction

> An entry on a financial account

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`](#source).

## Status

| Status | Meaning | Final |
| - | - | - |
| `pending` | Not yet sent to the bank: awaiting review in Nova, or queued at the bank partner | No |
| `processing` | Sent to the bank, not yet settled | No |
| `completed` | The bank reports it settled. Can still become `returned` | No |
| `returned` | Reversed after settlement, for example the recipient's bank rejected it | Yes |
| `rejected` | A payment approver rejected it before it was sent to the bank | Yes |
| `cancelled` | Stopped before it settled | Yes |
| `failed` | Could not be completed, either before or after submission to the bank. For example, an invalid routing number | Yes |
| `unknown` | The bank reported a state Nova does not recognize yet. Rare and temporary | No |

> [!WARNING]
>
> `completed` is not final. ACH returns can arrive up to 60 business days after
> settlement.

> [!NOTE]
>
> 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`.

```mermaid theme={null}
stateDiagram-v2
  state New <<fork>>
  [*] --> New
  New --> Pending
  New --> Processing
  New --> Settled

  Pending: Not yet sent
  state Pending {
    pending_cancelled: cancelled
    pending_failed: failed

    [*] --> pending
    pending --> PendingFailed

    PendingFailed: Failed
    state PendingFailed {
      [*] --> rejected
      [*] --> pending_cancelled
      [*] --> pending_failed
    }

    PendingFailed --> [*]
  }

  Pending --> Processing

  Processing: Pending bank
  state Processing {
    processing_cancelled: cancelled
    processing_failed: failed

    [*] --> processing
    processing --> ProcessingFailed

    ProcessingFailed: Failed
    state ProcessingFailed {
      [*] --> processing_cancelled
      [*] --> processing_failed
    }

    ProcessingFailed --> [*]
  }

  Pending --> Settled
  Processing --> Settled

  state Settled {
    [*] --> completed
    completed --> returned
  }

  Settled --> [*]
```

## 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.

| `source.type` | Meaning |
| - | - |
| `wire` | A wire sent from or received into this account |
| `ach` | A bank payment other than a wire, sent from or received into this account. Today that is ACH |
| `transfer` | A movement between accounts on the Nova platform, such as a balance top-up or reassigning funds |
| `other` | Any other cause |

> [!WARNING]
>
> `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.

| `workflow.type` | Fields |
| - | - |
| `distribution` | `id` (distribution), `payment` (distribution payment), `entity` (the recipient) |

> [!WARNING]
>
> 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"`

| Transaction | `amount` | `status` | `source.id` |
| - | - | - | - |
| `tx_1` | `-50000` | `returned` | `txg_a` |
| `tx_2` | `50000` | `completed` | `txg_a` |

## Related

* [`UtcDateTime`](https://docs.nova.net/types/utc-date-time)


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.