Ledger and Balances
Ledger and Balances enables platforms to maintain an accurate, real-time record of funds held on behalf of participants within the platform ecosystem. Every financial event — including credits, debits, refunds, transfers, payouts, and fee assessments — is captured and reflected in participant balances. This gives platforms and their participants a consistent, auditable view of where funds are at every point in the transaction lifecycle.
The capability supports both acquiring and non-acquiring fund flows. Acquiring funds — those generated through payment acceptance — and non-acquiring funds — such as wallet balances, refunds, and top-ups — are tracked separately, giving platforms clean visibility into each type of fund position without mixing the two.
Platforms can use this capability to support a range of financial products including stored-value wallets, marketplace fund distribution, reserve and escrow management, and settlement funding — while maintaining alignment between participant balances and the underlying bank accounts that hold those funds.
Ledger and Balances serves as the financial record layer of Commerce Hub for Platforms. It sits between transaction processing and settlement, ensuring that every money movement is reflected in participant balances before funds are released, distributed, or settled.
Common Use Cases and Outcomes
| Common Use Case | Description | Outcome |
|---|---|---|
| Wallet and Stored-Value Balance Management | Platforms can credit buyer or participant wallets with refunds, promotional credits, or ACH-loaded funds. Balances are updated in real time and are immediately available for spend or withdrawal, depending on the platform's configuration. | Participants see accurate, up-to-date balances without delay. Platforms can offer instant-credit financial products backed by a reliable ledger. |
| Acquiring vs Non-Acquiring Fund Separation | Funds earned through acquiring transactions (payment acceptance) are tracked separately from non-acquiring funds (wallet balances, refunds, top-ups). This separation ensures platforms can reconcile and distribute each fund type independently. | Platforms maintain clean accounting between marketplace earnings and wallet balances. Each fund type can be settled or paid out on its own schedule without cross-contamination. |
| Reserve and Escrow Management | Platforms can hold a portion of participant funds in a reserved or restricted state to support chargeback exposure, compliance holds, dispute resolution, or contractual escrow requirements. Reserved funds are not available for payout until the hold condition is released. | Platforms can meet risk management and compliance obligations without removing funds from the ecosystem entirely. Reserve releases are reflected immediately in available participant balances. |
| Refund and Credit Processing | Merchants and platforms can credit participant accounts directly without requiring an external ACH or wire. Credits are reflected immediately in the participant's available balance and are available for spend or withdrawal based on platform rules. | Participants receive instant access to refund funds. Platforms avoid the cost and delay of external ACH refund processing. |
| Payout and Disbursement Funding | When a participant requests a withdrawal or the platform initiates a disbursement, funds are debited from the participant's balance and routed through the configured payout rail. The balance reflects the change immediately, and the platform receives confirmation once the payout settles at the participant's bank. | Participants have visibility into their available balance before and after requesting a payout. Platforms can track payout status from initiation through bank confirmation. |
Ledger Representation
Key categories include:
| Ledger | Description | Instruction Category |
|---|---|---|
| Party Pending | Represents funds that have been authorized or captured but are not yet finalized for allocation, settlement, or payout. Funds remain in a pending state until the funding scheduled time. | "category":"FUNDING" |
| Party Earning | Represents funds allocated to a participant as their earning of a transaction. These funds belong to the participant and become available for settlement or payout. | |
| Party Escrow | Represents funds that are temporarily held and restricted from payout until predefined business conditions, hold periods, reserve requirements, or release criteria have been satisfied. | "category":"ESCROW" |
Balance Views Available
Depending on the use case and platform configuration, a participant's funds may exist in one or more balance states at any point in time. Platforms have visibility into each balance type through reporting and data elements described below.
| Balance/Reporting View | Description |
|---|---|
| Available Balance | Funds that are immediately available to the participant for spending, transfer, or withdrawal. This is the primary balance shown to participants and used at checkout or payout initiation. |
| Pending Balance | Funds that have been initiated or allocated but are not yet fully settled. Pending balances typically arise from ACH loads in transit or payouts awaiting bank confirmation. Once the underlying transaction settles, the pending balance converts to available. |
| Reserved/Escrow Balance | Funds that are temporarily restricted from spending or withdrawal. Platforms configure reserve holds to support chargeback exposure, compliance requirements, dispute resolution, or contractual obligations. Reserved funds are released back to the available balance when the hold condition is satisfied. |
| Settlement Activity | Funds currently moving through settlement |
| Transaction History | Detailed ledger activity and movements |
| Negative Balance | In some platform models — such as those involving ACH loads that may be returned after funds have been partially spent — the participant's balance may temporarily go negative. Commerce Hub for Platforms Ledger supports configurable negative balance limits for platforms whose business model requires recovery or chargeback support. The platform retains responsibility for collections on negative balances. |
| Payout Reporting | Status of payout requests and settlements |
Reporting and Data Elements Available to Clients
Commerce Hub for Platforms surfaces balance and transaction information to platforms through reporting outputs and data feeds. The following data elements are available to clients for reconciliation, participant-facing display, and operational reporting.
Participant Balance Data
| Data Element | Description | How It Is Delivered |
|---|---|---|
| Available Balance | The participant's current spendable balance, updated in real time after each transaction. | Real-time API response; daily balance report |
| Pending Balance | Funds in transit — initiated but not yet settled at the bank level. | Real-time API response; daily balance report |
| Reserved / Escrow Balance | Funds currently under a platform-configured hold. | Real-time API response; daily balance report |
| Total Balance | Combined view of all fund states for the participant. | Daily balance report |
| Balance as of Date/Time | Point-in-time balance snapshot for reconciliation purposes. | Daily balance report; on-demand query |
Transaction-Level Data
Each transaction that affects a participant's balance generates a corresponding record. The following data elements are available per transaction:
| Data Element | Description |
|---|---|
| Transaction ID | Unique identifier for the transaction. Used to cross-reference across reporting files and API responses. |
| Transaction Date / Time | Timestamp of when the transaction was processed (UTC). |
| Transaction Type | The type of event: refund, ACH credit, wallet spend, payout initiation, fee assessment, reversal, etc. |
| Transaction Status | Current lifecycle state: initiated, pending, settled, failed, reversed. |
| Amount | The transaction amount in USD (Phase 1: USD only). |
| Balance Before / After | The participant's available balance immediately before and after the transaction. |
| Participant ID | The platform-assigned or system-generated identifier for the participant. |
| Settlement Date | The date the transaction settled at the bank level (where applicable — ACH loads, payouts). |
| Fund Type | Indicates whether the transaction relates to acquiring funds or non-acquiring funds (wallet/stored-value). |
| Return / Reversal Code | If a transaction was reversed or returned (e.g., ACH return), the return reason code is included. |
Fund Type Distinction — Acquiring vs Non-Acquiring
Clients receive separate balance and transaction reporting for acquiring funds and non-acquiring funds. This distinction is surfaced in all data feeds and reports, allowing platforms to reconcile each independently.
| Fund Type | What It Represents | Reported Separately? |
|---|---|---|
| Acquiring Funds | Funds generated through payment acceptance transactions (e.g., buyer checkout payments). These accumulate in the platform's acquiring position and are settled to the platform on a configured schedule. | YES — separate line items in all balance and transaction reports |
| Non-Acquiring Funds | Wallet balances, refunds, ACH loads, and other non-payment-acceptance credits. These are participant-level balances available for spend, withdrawal, or transfer. | YES — separate line items in all balance and transaction reports |
SFTP/Batch Reporting
For platforms requiring batch-based reconciliation, Commerce Hub for Platforms delivers daily SFTP files containing:
- Daily wallet transaction file — all balance-affecting events for the reporting period, one row per transaction
- Daily balance snapshot file — closing available, pending, and reserved balances per participant
- Collections file — participants with negative balances requiring platform action
All files are encrypted in transit (SFTP + PGP). No raw personally identifiable information is included in transaction or balance files — participant identifiers are tokenized.
Transaction History and Traceability
Every transaction recorded in Commerce Hub for Platforms Ledger produces a permanent audit trail.
Transactions are stored with:
- Unique transaction identifiers
- Debit and credit entries
- Associated participants
- Related account movements
- Status and lifecycle details
This enables platforms to trace the complete history of a transaction from initiation through settlement, reversal, or reconciliation.
Commerce Hub for Platforms Ledger maintains detailed transaction records to support operational reporting, investigations, compliance reviews, customer servicing, and financial reconciliation activities.