GET /api/v2/transactions/list returns has a status. It tells you how final the bank’s record of the transaction is, and its values depend on the source of the account’s bank.
FDE rows carry the status FDE reports.
A transaction’s status can change from one refresh to the next: each time LedgerSync refreshes a connection, it writes the status the bank reports now. Read recent transactions again on every sync and update the rows you stored, keyed on
transactionId.
FINICITY
Active
A transaction the bank has posted. LedgerSync does not delete an active row because a later refresh leaves it out, so it stays in the list.Pending
A transaction the bank has authorized but not posted yet. Its amount and description are provisional: either can change, or the charge can disappear, before it settles.- Pending rows have no posted date (
postedDate: null). A request withfromortoleaves them out. Omit both dates to include them. - Pending transactions are short-lived. Each refresh brings in the pending transactions the bank reports at that moment. When a later refresh no longer returns one, LedgerSync deletes it, so it drops out of the list.
- A pending row that someone already worked on in LedgerSync, for example edited, excluded or synced to an accounting platform, is kept even after the bank stops reporting it.
Which one happens depends on the bank’s reporting.
Shadow
A transaction LedgerSync stored earlier that FINICITY now reports as retracted. LedgerSync never adds a new row asshadow: it marks the row it already has. When the bank replaced the transaction with a corrected one, the corrected transaction arrives as a separate active row, so the shadow row can look like a duplicate of it.
Partners handle shadow rows in a few ways:
- Do not display them.
- Remove them from your data store.
- Show them to the customer with a way to confirm the removal.
- Ignore the status, which keeps the retracted row next to its replacement.
active FINICITY rows, and the v3 API never returns shadow rows.
MX
POSTED
A transaction the bank has posted.PENDING
A transaction the bank has not posted yet. MX has no posted date for it, so itspostedDate holds its transaction date. For MX, from and to filter on the transaction date, so pending rows stay in range.
MX settles a pending transaction one of two ways:
When MX stops returning a pending transaction, LedgerSync deletes the row: right away when its posted copy, for the same amount, arrives in the same refresh, and otherwise once MX’s record of it is more than 16 days old. At that point a pending row that the account’s bank statement shows as posted is marked
POSTED instead of deleted. As with FINICITY, a pending row that someone already worked on in LedgerSync is kept.
LedgerSync’s own rules wait for an MX pending row to settle before they categorize it.
Which rows to keep
To keep pending rows in step:
1
Read the account again on every sync
MX pending rows come back in any
from and to window that covers their transaction date. FINICITY pending rows come back only when you send neither from nor to.2
Upsert every row by transactionId
A row that changed status, amount or description overwrites the copy you stored.
3
Drop pending rows that are gone
A pending row you stored that a read covering its date no longer returns was deleted in LedgerSync. If the transaction settled as a new record, the settled version is a separate row with its own
transactionId.Book
active and POSTED rows, hold pending and PENDING rows until they settle, and leave out shadow rows. That way a pending charge and its settled copy, or a shadow row and its replacement, never both land in your books.