> For clean Markdown of any page, append .md to the page URL.
> For a complete documentation index, see https://docs.modernfi.com/llms.txt.
> For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://docs.modernfi.com/_mcp/server.

# Transactions

# Transaction Records and Sweeps

Transaction records represent internal money movements at the source institution between the program omnibus account and a linked depositor account (savings, checking, etc.). By sharing these records with ModernFi, ModernFi is able to determine the balance of funds available to sweep into the deposit network at the depositor account level. Deposits (credits) flow into the network; withdrawals (debits) reverse the flow. ModernFi's custodian handles allocation to receiving institutions.

Before creating transactions, a depositor and an associated account must exist. All API operations execute in real time, transactions are recorded and reflected immediately, with no batch processing window.

## Transaction Lifecycle

|               |                       |                                                                                                                                                 |
| ------------- | --------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------- |
| **Status**    | **Can Transition To** | **Notes**                                                                                                                                       |
| **PENDING**   | POSTED or CANCELLED   | Initial state for all transactions. Credits can be manually moved to POSTED. Debits can only be CANCELLED (not manually posted).                |
| **POSTED**    | Terminal              | Credits move here after the institution confirms settlement. Debits are posted automatically by ModernFi after allocation. Cannot be cancelled. |
| **CANCELLED** | Terminal              | Only available for PENDING transactions. Cannot cancel a debit locked in allocation. Cannot cancel any POSTED transaction.                      |

## Credits vs. Debits

The sign of the transaction amount determines its type. ModernFi provides more flexibility on credits than debits due to allocation constraints on the debit side.

|                    |                                               |                                                 |
| ------------------ | --------------------------------------------- | ----------------------------------------------- |
|                    | **CREDIT (Deposit)**                          | **DEBIT (Withdrawal)**                          |
| **Amount**         | Positive value                                | Negative value                                  |
| **Effect**         | Sweeps funds INTO the network                 | Pulls funds OUT of the network                  |
| **Initial Status** | PENDING                                       | PENDING                                         |
| **Move to POSTED** | Institution updates via API when funds settle | ModernFi posts automatically after allocation   |
| **Cancel**         | Yes - while PENDING                           | Yes - unless locked in allocation               |
| **Flexibility**    | More flexibility available                    | More restrictive - allocation constraints apply |

## **Transaction Timestamps**

Two timestamp fields give you control and visibility over transaction timing:

* `Transacted_at`:  the effective date of the transaction. Backdating and future-dating are both supported, allowing you to reflect when a transaction economically occurred regardless of when it was submitted to the API.
* `posted_at`: set automatically when a PATCH request is made to post a credit. Reflects when the update request was received, not the downstream settlement time

## **Note:**

* An optional `institution_transaction_id` field can be passed on transaction creation for internal reconciliation tracking.
* The `description` field is optional by default but can be configured as required at the institution level.
* When filtering transactions by date range, `start_date` is inclusive and `end_date` is exclusive. Results are based on the `transacted_at` timestamp in ET.
* Credits should not be posted until funds have settled in the program account, timing is critical for accurate interest accruals.
* Transactions that would result in an account overdraft will be rejected.
* Once any transaction reaches POSTED status, it is final and cannot be cancelled or reversed.
* A debit cannot be cancelled once its funds are locked in allocation. Confirm withdrawal intent before creating debit transactions.