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

# Ledger

> How Push records money movement as transactions, settles them into transfers on a fixed schedule, and how to reconcile it all against your own books.

## Overview

Push maintains a ledger tracking all movement of money into and out of your product. Settlement begins when a payment is approved and posted to the payment network, and ends when the funds are deposited into your operational account. In between, Push records that movement as a **transaction** and settles it via a **transfer**.

This guide explains the model your payments and finance teams will use to reconcile payments made through Push against your own records: what a transaction is, the lifecycle it moves through, how transactions are composed into transfers, the schedule on which they settle, and how to tie it all back to the payments you submitted.

## The model

The ledger is built from three resources:

<CardGroup cols={3}>
  <Card title="Transactions" icon="receipt">
    A single record of money movement, one per approved intent, refund, or dispute.
  </Card>

  <Card title="Transfers" icon="arrow-right-arrow-left">
    A net movement of funds between Push and your operational account, composed from a set of transactions.
  </Card>

  <Card title="Accounts" icon="building-columns">
    The managed accounts that transactions settle against.
  </Card>
</CardGroup>

The relationship is straightforward: **each payment produces a transaction, and each transaction is settled by exactly one transfer.** A transfer's amount is the exact net of the transactions it contains. This one-to-one, sum-exact relationship is what makes the ledger reconcilable — you can always trace a transfer back to the precise set of payments that produced it.

## Transactions

A transaction is a stateful record of money moving through the platform. Push creates a transaction when it commits to a movement of funds (i.e. when a payment intent is approved and submitted for processing).

Every transaction has a **direction** and an **amount**:

* `direction` is `cash_in` (a deposit or purchase moving funds from the user's account to the platform) or `cash_out` (a withdrawal, refund, or payout moving funds from your platform back to the user's bank account).
* `amount` is an unsigned integer in the smallest currency unit (for USD, integer cents). The amount is always non-negative; the `direction` tells you which way the money moved.

<Note>
  The amount is always positive. To compute a signed effect on your balance, treat `cash_in` as positive and `cash_out` as negative.
</Note>

### The transaction fields

| Field        | Description                                                                                                                          |
| :----------- | :----------------------------------------------------------------------------------------------------------------------------------- |
| `id`         | Unique identifier, prefixed `txn_`.                                                                                                  |
| `amount`     | Unsigned amount in the smallest currency unit (USD: cents).                                                                          |
| `direction`  | `cash_in` or `cash_out`.                                                                                                             |
| `currency`   | Currency of the transaction (currently `USD`).                                                                                       |
| `status`     | The stage in the settlement lifecycle — see [below](#the-transaction-lifecycle).                                                     |
| `type`       | What created the transaction: `intent`, `refund`, or `dispute`.                                                                      |
| `source_id`  | The ID of the intent, refund, or dispute that created it. Combine with `type` to find the source object.                             |
| `account_id` | The account the transaction settles against.                                                                                         |
| `created_at` | When the transaction was recorded (ISO 8601 timestamp).                                                                              |
| `date`       | The settlement window (an Eastern-time day) in which the transaction was submitted. See [Settlement schedule](#settlement-schedule). |
| `transfer`   | The transfer that settles this transaction. Populated once the transaction is `in_transfer` or `settled`; `null` beforehand.         |

### The transaction lifecycle

A transaction advances through a series of statuses as its funds move toward settlement. The stages differ by direction, because `cash_in` funds must be confirmed by the financial network before they can be settled, whereas `cash_out` funds do not.

```mermaid theme={null}
stateDiagram-v2
    direction LR
    [*] --> pending
    pending --> available: cash_in — funds confirmed by network
    available --> settled: cash_in — settled in a transfer
    pending --> in_transfer: cash_out — batched into a transfer
    in_transfer --> settled: cash_out — network confirms funds received
    settled --> [*]
```

* **Cash-in:** `pending → available → settled`
* **Cash-out:** `pending → in_transfer → settled`

`available` applies only to `cash_in` (it marks funds confirmed by the network and ready to settle); `in_transfer` applies only to `cash_out` (it marks funds being collected via a transfer).

| Status        | Meaning                                                                                                                                                                                                                      |
| :------------ | :--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `pending`     | The transaction has been recorded but the funds have not yet been confirmed by the network. For `cash_in`, the funds have not yet arrived; for `cash_out`, the payment has been recorded but not yet included in a transfer. |
| `available`   | **`cash_in` only.** The funds have been confirmed by the network and are eligible for settlement, but have not yet been placed into a transfer.                                                                              |
| `in_transfer` | **`cash_out` only.** The transaction has been batched into a transfer and the funds are being collected from your operational account.                                                                                       |
| `settled`     | Final status. The transfer containing the transaction has settled with the network — for `cash_in` the funds have been transmitted, and for `cash_out` the network has confirmed the counterparty received the funds.        |

<Note>
  A transaction advances only forward through these stages. A transaction that does not advance as expected (for example, one whose settlement window has passed without being included in a transfer) falls out of the normal flow and is resolved by Push operations — it will not silently settle for the wrong amount.
</Note>

## Transfers

A transfer is the actual movement of funds between the Push settlement account and your operational account. At the close of each [settlement window](#settlement-schedule), Push gathers the transactions that are eligible to settle, nets them, and creates a transfer.

A transfer has a **direction** that reflects the net movement:

* `disbursement` — a net payout **to** your operational account. This happens when `cash_in` (deposits) exceeds `cash_out` (withdrawals) for the window.
* `collection` — a net withdrawal **from** your operational account. This happens when `cash_out` exceeds `cash_in`.

The transfer `amount` is unsigned and equals the **exact net** of its constituent transactions:

```
transfer.amount = | Σ(cash_in transactions) − Σ(cash_out transactions) |
```

Every settled transaction belongs to **exactly one** transfer, and a transfer's `transactions` array is the complete, exact set that produced its amount.

### The transfer fields

| Field          | Description                                                           |
| :------------- | :-------------------------------------------------------------------- |
| `id`           | Unique identifier, prefixed `transfer_`.                              |
| `amount`       | Unsigned net amount in the smallest currency unit (USD: cents).       |
| `currency`     | Currency of the transfer (currently `USD`).                           |
| `direction`    | `disbursement` (payout to you) or `collection` (withdrawal from you). |
| `date`         | The settlement date of the transfer.                                  |
| `created_at`   | When the transfer was created (ISO 8601 timestamp).                   |
| `transactions` | The exact set of transactions settled by this transfer.               |
| `account`      | The account the transfer settles against.                             |

When a transfer is embedded in the `transfer` field of a transaction object, it appears as a compact summary (`id`, `amount`, `currency`, `direction`, `date`, `created_at`) without its own nested `transactions` array. Fetch the [transfer endpoints](./apireference/ledger/list-transfers) to retrieve the full transfer with its constituents.

## Accounts

Transactions and transfers settle against a Push-managed **account** — this is where your settlement activity lands. List your accounts with [`list accounts`](./apireference/ledger/list-accounts).

Accounts identify *where* activity settles; your settled position for any period is derived from the transactions and transfers that reference the account, as described in [Reconciliation](#reconciliation) below.

## Settlement schedule

Which window a transaction settles in — and therefore when it reaches `settled` and appears in a transfer — is fixed by the settlement schedule.

Push Cash defines a 24-hour settlement window for payment intents submitted between the hours of 4PM Eastern the previous day and 4PM Eastern on each day of processing.

* For any `cash_in` payment intents, the funds will be settled 1 day later (`t+1`).
* For any `cash_out` payment intents, the funds will be settled the same day (`t`).

<Note>
  The network operator will settle transfers to your operational account same-day if a processing day falls outside of a weekend or bank holiday.
  Otherwise, the funds will be settled on the next banking day.

  Push Cash submits transfers to the payment network every day of the week, regardless of holidays or weekends.
</Note>

The following table and diagrams depict the settlement schedule for a payment intent submitted at different times of the day.

<Card>
  | Direction            | Submission Time (Eastern)        | Settlement Date    |
  | -------------------- | -------------------------------- | ------------------ |
  | `cash_in`            | `< 4PM` on 2024-10-01            | 2024-10-02 `(t+1)` |
  | `cash_in`            | `> 4PM` on 2024-10-01            | 2024-10-03 `(t+1)` |
  | `cash_out`           | `< 4PM` on 2024-10-01            | 2024-10-01 `(t)`   |
  | `cash_out`           | `> 4PM` on 2024-10-01            | 2024-10-02 `(t)`   |
</Card>

```mermaid theme={null}
gantt
    title Settlement Timeline for cash_out Payment Intents
    axisFormat  %b %d
    tickInterval 1day

    section Before 4PM
    Payment Submitted :done, submit-in-window, 2024-09-30T16:00:00, 1d
    Funds Settled :milestone, after submit-in-window, 0d

    section After 4PM
    Payment Submitted          :done, submit-after-window, 2024-10-01T16:00:00, 1d
    Funds Settled :milestone, after submit-after-window, 0d
```

```mermaid theme={null}
gantt
    title Settlement Timeline for cash_in Payment Intents
    axisFormat  %b %d
    tickInterval 1day

    section Before 4PM
    Payment Submitted :done, submit-in-window, 2024-09-30T16:00:00, 1d
    Funds Held :active, hold-in-window, after submit-in-window, 1d
    Funds Settled :milestone, after hold-in-window, 0d

    section After 4PM
    Payment Submitted :done, submit-after-window, 2024-10-01T16:00:00, 1d
    Funds Held :active, hold-after-window, after submit-after-window, 1d
    Funds Settled :milestone, after hold-after-window, 0d
```

## Reconciliation

Because a transfer is an exact composition of its transactions, you can reconcile Push against your own books deterministically. A typical monthly or per-window reconciliation looks like this:

<Steps>
  <Step title="Match each transfer to the funds movement on your bank statement">
    A `disbursement` is a deposit into your operational account; a `collection` is a debit from it. The `amount` and `date` on the transfer correspond to the movement you'll see at your bank.
  </Step>

  <Step title="Expand the transfer into its transactions">
    Fetch the transfer with [`get a transfer`](./apireference/ledger/retrieve-a-transfer) and read its `transactions` array. Confirm that the transactions net to the transfer amount:

    ```
    Σ(cash_in amounts) − Σ(cash_out amounts) = ± transfer.amount
    ```
  </Step>

  <Step title="Tie each transaction back to your own records">
    Each transaction carries a `type` and `source_id` pointing to the intent, refund, or dispute that created it. If you set a [`tag`](./api#idempotency) when you authorized the payment, you can retrieve the source object and match it to your internal identifier.
  </Step>
</Steps>

<Note>
  You do not need to poll for the moment a transaction settles. Use [webhooks](./enabling-webhooks) for real-time payment outcomes, and use the ledger endpoints (`list transactions`, `list transfers`) to reconcile settled activity for a window or date range.
</Note>

### Querying the ledger

| To find…                                           | Use                                                            | Notes                                                                                                   |
| :------------------------------------------------- | :------------------------------------------------------------- | :------------------------------------------------------------------------------------------------------ |
| All transactions in a date range                   | [`list transactions`](./apireference/ledger/list-transactions) | Filter by `date.after` / `date.before` (settlement window) or `created_at.after` / `created_at.before`. |
| Transactions for one account                       | [`list transactions`](./apireference/ledger/list-transactions) | Filter by `account_id`.                                                                                 |
| Transactions of one kind                           | [`list transactions`](./apireference/ledger/list-transactions) | Filter by `type` (`intent`, `refund`, `dispute`).                                                       |
| A single transaction, including its transfer       | [`get a transaction`](./apireference/ledger/get-a-transaction) | The `transfer` field is populated once the transaction is `in_transfer` or `settled`.                   |
| Transfers in a date range                          | [`list transfers`](./apireference/ledger/list-transfers)       | Filter by `date` or `created_at`.                                                                       |
| A single transfer and its constituent transactions | [`get a transfer`](./apireference/ledger/retrieve-a-transfer)  | Returns the full `transactions` array.                                                                  |

List endpoints are cursor-paginated: pass the `next_cursor` from a response as the `cursor` parameter of the next request until it is `null`.