Skip to main content

​
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:

Transactions

A single record of money movement, one per approved intent, refund, or dispute.

Transfers

A net movement of funds between Push and your operational account, composed from a set of transactions.

Accounts

The managed accounts that transactions settle against.
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.
The amount is always positive. To compute a signed effect on your balance, treat cash_in as positive and cash_out as negative.

​
The transaction fields

​
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.
  • 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).
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.

​
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, 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:
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

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 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. 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 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).
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.
The following table and diagrams depict the settlement schedule for a payment intent submitted at different times of the day.

​
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:
1

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

Expand the transfer into its transactions

Fetch the transfer with get a transfer and read its transactions array. Confirm that the transactions net to the transfer amount:
3

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 when you authorized the payment, you can retrieve the source object and match it to your internal identifier.
You do not need to poll for the moment a transaction settles. Use 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.

​
Querying the ledger

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