{"templateId":"markdown","sharedDataIds":{"sidebar":"sidebar-sidebars.yaml"},"props":{"metadata":{"markdoc":{"tagList":["admonition"]},"type":"markdown"},"seo":{"title":"How settlement works","siteUrl":"https://docs.peachfinance.com","description":"API and product documentation for Peach Finance, a lending-as-a-service platform."},"dynamicMarkdocComponents":[],"compilationErrors":[],"ast":{"$$mdtype":"Tag","name":"article","attributes":{},"children":[{"$$mdtype":"Tag","name":"Heading","attributes":{"level":1,"id":"how-settlement-works","__idx":0},"children":["How settlement works"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Peach keeps two things separate on purpose: the ",{"$$mdtype":"Tag","name":"em","attributes":{},"children":["ledger"]}," that records what every loan owes, and the ",{"$$mdtype":"Tag","name":"em","attributes":{},"children":["movement of money"]}," between bank accounts. How a lender configures payment processing decides whether Peach also moves money, and how far. Settlement is the last leg of that money movement: paying the funds Peach collects from borrowers to the investors who own the loans."]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["This page explains how settlement works across all three processing models. To set up settlement for your own program under Bring Your Own Bank (BYOB) processing, see ",{"$$mdtype":"Tag","name":"MarkdownLink","attributes":{"href":"/payments/byob-processing"},"children":["Set up Bring Your Own Bank (BYOB) processing"]},"."]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"what-youll-learn","__idx":1},"children":["What you'll learn"]},{"$$mdtype":"Tag","name":"ul","attributes":{},"children":[{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Why settlement exists, and how it is separate from the balances Peach keeps on its ledger"]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Who collects, who moves the money, and who is responsible in each of the three processing models"]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["How individual collected payments become transfers, and how transfers are aggregated into a settlement"]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["How to trace a settlement back to the payments it contains"]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["The known limitations to plan around"]}]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"concept-overview","__idx":2},"children":["Concept overview"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Every loan on Peach is owned by one or more ",{"$$mdtype":"Tag","name":"em","attributes":{},"children":["investors"]},", the parties whose capital funds the loan. Ownership is set as percentages that sum to 100% when the loan is created, and it can change over time. Most lenders do not hold all of their loans on their own balance sheet, so when Peach collects a payment from a borrower, some or all of that money is owed onward to the loan's investors."]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Settlement is that onward transfer. In every processing model, Peach records the borrower's payment on the loan; that is the ledger side. Settlement is a separate, later step: paying the collected funds out to the investors' bank accounts."]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["What differs between lenders is the money-movement side: who collects the borrower's payment, whose bank executes the transfers, and whether Peach generates the files that move investor funds at all."]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"key-concepts","__idx":3},"children":["Key concepts"]},{"$$mdtype":"Tag","name":"ul","attributes":{},"children":[{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Investor"]}," — A party that owns a percentage of a loan. Ownership is established when the loan is created and can be updated afterward with an effective date; at any given time a loan's investor shares sum to 100%. Settlement pays collected funds to these owners. "]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Settlement"]}," — An aggregated payout to a single investor, covering many collected payments at once. Public id prefix ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["SM"]},". "]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Transfer"]}," — The record of a single unit of money movement tied to one borrower transaction. Public id prefix ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["TR"]},". Transfers are aggregated into settlements. "]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Settlement instrument"]}," — An investor-owned bank account that Peach pays settlement proceeds to by ACH credit. Managed in the Admin Portal or through the API. "]}]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":3,"id":"the-three-processing-models","__idx":4},"children":["The three processing models"]},{"$$mdtype":"Tag","name":"ul","attributes":{},"children":[{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Peach-managed payment processing"]}," — Peach collects from borrowers through its banking partner, and settles proceeds to investors when Peach's own processor is set up to settle to investors and has an active funding instrument."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["BYOB"]}," — The lender's own bank moves the money, across two distinct legs. In ",{"$$mdtype":"Tag","name":"em","attributes":{},"children":["collection"]},", Peach generates the ACH files and the lender's bank moves money between the lender and its borrowers. In ",{"$$mdtype":"Tag","name":"em","attributes":{},"children":["settlement"]},", Peach generates the files that move collected funds from the lender's account onward to investors. These are separate capabilities — BYOB collection runs whether or not settlement is enabled — and settlement, the lender-to-investor leg, is what this page is about."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["External payment processing"]}," — the lender processes payments independently and reports status to Peach; Peach maintains the ledger and moves no money."]}]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"how-it-works","__idx":5},"children":["How it works"]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":3,"id":"settlement-across-the-three-processing-models","__idx":6},"children":["Settlement across the three processing models"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["The three models differ in who moves the money. In all three, Peach records each borrower payment as a transaction on the loan."]},{"$$mdtype":"Tag","name":"div","attributes":{"className":"md-table-wrapper"},"children":[{"$$mdtype":"Tag","name":"table","attributes":{"className":"md"},"children":[{"$$mdtype":"Tag","name":"thead","attributes":{},"children":[{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"th","attributes":{"data-label":""},"children":[]},{"$$mdtype":"Tag","name":"th","attributes":{"data-label":"Peach-managed"},"children":["Peach-managed"]},{"$$mdtype":"Tag","name":"th","attributes":{"data-label":"BYOB"},"children":["BYOB"]},{"$$mdtype":"Tag","name":"th","attributes":{"data-label":"External"},"children":["External"]}]}]},{"$$mdtype":"Tag","name":"tbody","attributes":{},"children":[{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Who collects from the borrower"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Peach, through its banking partner"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Peach generates the ACH files; the lender's own bank executes them"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["The lender's own payment processor"]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Who moves the money"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Peach's banking partner"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["The lender's own bank"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["The lender's processor"]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Does Peach generate collection files?"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Yes"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Yes"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["No"]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Does Peach generate settlement files?"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Only when Peach's processor is configured for settlement"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Only when the processor is configured for settlement"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["No"]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["What the lender is responsible for"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Configuring the loan and instruments"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Operating the bank connection (SFTP) and providing ACH file-header details"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Running collection ",{"$$mdtype":"Tag","name":"em","attributes":{},"children":["and"]}," settlement independently, then reporting transaction status to Peach"]}]}]}]}]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Under ",{"$$mdtype":"Tag","name":"MarkdownLink","attributes":{"href":"/payments/peach-processing"},"children":["Peach-managed processing"]},", Peach collects from borrowers, and settles to investors when its own processor is set up to settle to investors and has an active funding instrument. Under ",{"$$mdtype":"Tag","name":"MarkdownLink","attributes":{"href":"/payments/external-processing"},"children":["external processing"]},", Peach participates in neither leg of money movement; it maintains balances from the status updates the lender sends. BYOB sits between them: the lender's bank executes the ACH, and Peach can also generate the files that move collected funds from the lender's account out to investors when settlement is enabled."]},{"$$mdtype":"Tag","name":"Admonition","attributes":{"type":"info","name":"Settlements fund only once Peach has set up a funding instrument"},"children":[{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Once a settlement-required processor is collecting payments, Peach assembles settlements automatically — but they do not fund until an active ",{"$$mdtype":"Tag","name":"em","attributes":{},"children":["funding instrument"]}," exists for your program: the account settlement money is drawn from. Only Peach can create it; there is no self-service step. Until it exists, assembled settlements accumulate in ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["readyForFunding"]}," and wait, with no error raised and nothing to flag the delay. A missing funding instrument is one reason a payout has not landed; ",{"$$mdtype":"Tag","name":"MarkdownLink","attributes":{"href":"#why-a-settlement-stays-in-readyforfunding"},"children":["Why a settlement stays in readyForFunding"]}," lists the others."]}]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":3,"id":"stage-1-a-payment-is-collected","__idx":7},"children":["Stage 1: A payment is collected"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["When a borrower payment succeeds, Peach records a transfer capturing the money owed onward to the loan's investors — one per successful collection. If that same payment later fails or is reversed, Peach records a second transfer in the opposite direction — a clawback — rather than modifying the first. "]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":3,"id":"stage-2-transfers-are-aggregated-into-a-settlement","__idx":8},"children":["Stage 2: Transfers are aggregated into a settlement"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Rather than wiring an investor once per payment, Peach groups unsettled transfers by investor (and by the processor that will move the money) and rolls them into a single settlement per investor. Successful collections add to the settlement total; clawbacks subtract from it. "]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":3,"id":"stage-3-the-settlement-is-funded","__idx":9},"children":["Stage 3: The settlement is funded"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["The settlement moves through a series of statuses as Peach generates the file, the money moves, and funding is confirmed. "]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["A per-investor minimum applies before settlements are funded. In a given funding run, Peach funds an investor's settlements only when that investor's total across every settlement waiting to be funded reaches $100.00; smaller totals are held and roll into a later run once they accumulate to the minimum. The minimum does not apply on a processor that Peach has marked external. A lender can create a processor with ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["isExternal: true"]}," only if the processor is not settlement-required: the API rejects a processor created with both settings, and no update changes ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["isExternal"]},". So a lender cannot mark its own settlement-required processor external, and such a processor is subject to the minimum until Peach marks it; see ",{"$$mdtype":"Tag","name":"MarkdownLink","attributes":{"href":"/payments/byob-processing#step-2-create-the-payment-processor"},"children":["Step 2 of the BYOB guide"]},". In every model, Peach funds an investor's settlements only when they net to more than $0.00."]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":3,"id":"settlement-statuses","__idx":10},"children":["Settlement statuses"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["A settlement and the transfers rolled into it track status in two different vocabularies, and chasing a payout that has not funded means reading the right one. Neither is part of the client-facing API reference. Peach stores them as described below; ask Peach how they appear in your ",{"$$mdtype":"Tag","name":"MarkdownLink","attributes":{"href":"/data-reporting/replica-database"},"children":["data replica"]},"."]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["The settlement (",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["SM"]},") record carries a ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["status"]},", a ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["TransferSettlementStatus"]},": ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["readyForFunding"]},", ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["processing"]},", ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["funded"]},", ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["failedFunding"]},", or ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["failedFundingReadyForRetry"]},". Peach stores it in the ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["status"]}," column of the ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["transfer_settlements"]}," table. The individual transfer (",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["TR"]},") records rolled into the settlement carry their own ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["status"]},", a coarser ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["TransferStatus"]}," (",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["InTransfer"]},", ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["Processing"]},", ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["Funded"]},", ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["FailedFunding"]},") that Peach derives from the settlement's status; transfer records have no API representation at all, and Peach stores their status in the ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["transfers"]}," table. ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["InTransfer"]}," in particular belongs to the transfer records — it is never a settlement's status."]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["When an investor is waiting on a payout that has not arrived, check the settlement's ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["status"]}," first. A settlement that has been assembled but not yet funded reads ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["readyForFunding"]}," — that is the value to check first."]},{"$$mdtype":"Tag","name":"div","attributes":{"className":"md-table-wrapper"},"children":[{"$$mdtype":"Tag","name":"table","attributes":{"className":"md"},"children":[{"$$mdtype":"Tag","name":"thead","attributes":{},"children":[{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"th","attributes":{"data-label":"Settlement status ( TransferSettlementStatus , on the transfer_settlements record)"},"children":["Settlement status (",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["TransferSettlementStatus"]},", on the ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["transfer_settlements"]}," record)"]},{"$$mdtype":"Tag","name":"th","attributes":{"data-label":"Meaning"},"children":["Meaning"]},{"$$mdtype":"Tag","name":"th","attributes":{"data-label":"Status on the constituent transfer records ( TransferStatus )"},"children":["Status on the constituent transfer records (",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["TransferStatus"]},")"]}]}]},{"$$mdtype":"Tag","name":"tbody","attributes":{},"children":[{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["readyForFunding"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Assembled and awaiting funding — the state to check first when a payout has not landed."]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["InTransfer"]}]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["processing"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Funding is in progress."]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["Processing"]}]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["funded"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["The settlement has been funded."]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["Funded"]}]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["failedFunding"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["The payout to the investor failed or was returned. Peach does not retry it automatically."]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["FailedFunding"]}]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["failedFundingReadyForRetry"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["The upload of the settlement file to the processor's SFTP server failed. Peach retries the upload automatically, the first time about 15 minutes later, and moves the settlement to ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["processing"]}," when an upload succeeds. Nothing else picks a settlement up again from this status. The transfer records collapse it into ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["FailedFunding"]},"."]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["FailedFunding"]}]}]}]}]}]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":3,"id":"why-a-settlement-stays-in-readyforfunding","__idx":11},"children":["Why a settlement stays in readyForFunding"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["A settlement stays in ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["readyForFunding"]},", with no error raised, when any of these holds at the funding run:"]},{"$$mdtype":"Tag","name":"ul","attributes":{},"children":[{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Peach has not set up an active funding instrument on the processor."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["The investor's total waiting to be funded is under $100.00, and the processor is not exempt from the minimum."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["The investor's settlements net to $0.00 or less."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["The investor has no active settlement instrument. Peach logs the failure and tries again on the next run."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["The funding instrument neither skips the bank-balance check nor has balance data, or the reported available balance does not cover the payout."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["The day is not a US business day; Peach funds settlements only on business days."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["A payout was created and then canceled before it was sent, which returns its settlements to ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["readyForFunding"]},"."]}]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":3,"id":"when-a-collected-payment-clears","__idx":12},"children":["When a collected payment clears"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Settlement can only act on a payment that has already cleared. Clearing is a separate, upstream step: the borrower's payment — a transaction, tracked in its own status vocabulary — must advance to ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["succeeded"]}," before the transfer it generates is eligible to be rolled into a settlement. This section covers when that clearing happens, not how long the investor payout then takes. "]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["There is no single \"clears in N business days\" rule, and writing clearing timing as a fixed promise will mislead. A collected ACH payment becomes eligible to advance to succeeded only when both of these are true: "]},{"$$mdtype":"Tag","name":"ul","attributes":{},"children":[{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Its clearing window has elapsed. The window sets the ",{"$$mdtype":"Tag","name":"em","attributes":{},"children":["earliest"]}," time a payment can advance: 3 business days after submission, unless Peach applies per-processor windows, in which case the processor's configured window applies. The window represents how long to wait after an ACH payment is submitted before the collected funds are treated as cleared and safe to pass onward to investors; because a payment that is passed on and then returns becomes a clawback, set the window conservatively. It governs when the payment is treated as cleared, not the investor payout timing directly. "]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Its confirmation requirement is met — either the processor has no confirmation-file requirement, or a matching confirmation file has been received and processed. "]}]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["The window is a floor, not a ceiling. If a processor is configured to expect a confirmation file, a payment does not advance until that file arrives — the clearing window does not force it through. If the confirmation file never arrives, the payment waits indefinitely. Only a processor with no confirmation-file requirement advances purely on the window."]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"in-practice","__idx":13},"children":["In practice"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Because a settlement rolls up many payments, a common reconciliation question is: ",{"$$mdtype":"Tag","name":"em","attributes":{},"children":["\"My investor received a payout — which borrower payments does it cover?\""]}," The data model answers this by joining from the settlement back to its transfers and then to the originating transactions."]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Suppose an investor sees a single settlement — say, a payout you want to break down. In Peach's database, the trace runs through four links:"]},{"$$mdtype":"Tag","name":"ol","attributes":{},"children":[{"$$mdtype":"Tag","name":"li","attributes":{},"children":["The trace starts from the payout's transaction, by its internal integer id. Its public id (",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["TX-…"]},") is an encoding of that id, not the id itself. "]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["The settlement is the ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["transfer_settlements"]}," row whose ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["reconciliation_transaction_id"]}," matches that internal id: the settlement (",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["SM-…"]},") for one investor. "]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["The settlement's transfers are the ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["transfers"]}," rows whose ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["settlement_id"]}," equals that settlement's id — one per incoming transfer for that investor, covering clawbacks as well as collections, each carrying only that investor's share of the amount. "]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Each transfer's ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["transaction_id"]}," points back to the originating borrower transaction. "]}]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Two details matter when reading these rows:"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["A transfer's ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["direction"]}," tells you which way money moved, but the meaning depends on which kind of transfer you are reading. Per-payment transfers — the ones tied directly to a borrower transaction — are only ever ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["FromBorrower"]}," or ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["ToBorrower"]},". The ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["ToInvestor"]}," and ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["FromInvestor"]}," values appear only on settlement transfers. On a settlement, ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["FromInvestor"]}," covers every clawback — a failed payment, a reversal, a reimbursement, or an opened chargeback — not just a failed payment. Reading ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["FromInvestor"]}," as \"a payment failed\" will misclassify every other kind of clawback. "]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Peach stores transfer and settlement amounts as integer cents. Divide by 100 for dollars: a settlement of 481250 cents is $4,812.50. "]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"why-it-works-this-way","__idx":14},"children":["Why it works this way"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Two design choices explain the shape of settlement."]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Ledger and money movement are separated on purpose. Keeping \"what the loan owes\" independent of \"who moved the cash\" is what lets the same servicing platform support a lender who has Peach move all the money, a lender whose own bank moves it, and a lender who moves it entirely outside Peach — without changing how balances are kept. The ledger is constant; only the money-movement configuration varies. "]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Payments are aggregated into settlements so investors are not handed thousands of lines. An investor who owns a slice of many loans could otherwise receive one wire per collected payment. Aggregation rolls a day's collections for an investor into a single settlement, so the investor receives one payout — and reconciliation walks back down to the individual payments through the join above, rather than up from thousands of separate wires. "]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"known-limitations","__idx":15},"children":["Known limitations"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Plan around these current constraints."]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":3,"id":"settlements-that-net-to-000-or-less-are-held","__idx":16},"children":["Settlements that net to $0.00 or less are held"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["This is by design: Peach never sends a payout of $0.00 or less. Clawbacks — failed payments, reversals, reimbursements, and opened chargebacks — subtract from an investor's settlements. If they exceed the investor's collections, the total nets to $0.00 or less. Peach does not fund it: the settlement stays in ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["readyForFunding"]}," and nets against the investor's later settlements until the total turns positive. This applies in every processing model, including BYOB settlements that are exempt from the $100.00 minimum."]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":3,"id":"settlement-files-use-the-processors-existing-sftp-location","__idx":17},"children":["Settlement files use the processor's existing SFTP location"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["This is a known limitation. Peach uploads settlement files to the same SFTP outbox configured on the payment processor for collection files; a separate settlement location is not currently configurable."]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":3,"id":"a-payment-with-no-ownership-record-stops-a-lenders-settlements","__idx":18},"children":["A payment with no ownership record stops a lender's settlements"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["This is a known limitation. When Peach builds a lender's daily settlements, it needs an investor ownership record on each payment's loan dated on or before the payment's effective date. If any payment has none — for example, a payment dated before the loan's first ownership record — the whole build for that lender fails. Peach creates no settlements for any of the lender's investors until an ownership record dated on or before that payment exists."]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"see-also","__idx":19},"children":["See also"]},{"$$mdtype":"Tag","name":"ul","attributes":{},"children":[{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"MarkdownLink","attributes":{"href":"/payments/byob-processing"},"children":["Set up Bring Your Own Bank (BYOB) processing"]}," — The BYOB implementation guide: configure a payment processor and ACH file transfer with your own bank."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"MarkdownLink","attributes":{"href":"/servicing-operations/admin-portal/admin-portal-settlement-instruments"},"children":["Manage settlement instruments"]}," — Register the investor bank accounts settlement proceeds are paid to."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"MarkdownLink","attributes":{"href":"/data-reporting/replica-database"},"children":["About Peach Data Replica"]}," — The file-based data replica, where financial reconciliation is a supported use case."]}]}]},"headings":[{"value":"How settlement works","id":"how-settlement-works","depth":1},{"value":"What you'll learn","id":"what-youll-learn","depth":2},{"value":"Concept overview","id":"concept-overview","depth":2},{"value":"Key concepts","id":"key-concepts","depth":2},{"value":"The three processing models","id":"the-three-processing-models","depth":3},{"value":"How it works","id":"how-it-works","depth":2},{"value":"Settlement across the three processing models","id":"settlement-across-the-three-processing-models","depth":3},{"value":"Stage 1: A payment is collected","id":"stage-1-a-payment-is-collected","depth":3},{"value":"Stage 2: Transfers are aggregated into a settlement","id":"stage-2-transfers-are-aggregated-into-a-settlement","depth":3},{"value":"Stage 3: The settlement is funded","id":"stage-3-the-settlement-is-funded","depth":3},{"value":"Settlement statuses","id":"settlement-statuses","depth":3},{"value":"Why a settlement stays in readyForFunding","id":"why-a-settlement-stays-in-readyforfunding","depth":3},{"value":"When a collected payment clears","id":"when-a-collected-payment-clears","depth":3},{"value":"In practice","id":"in-practice","depth":2},{"value":"Why it works this way","id":"why-it-works-this-way","depth":2},{"value":"Known limitations","id":"known-limitations","depth":2},{"value":"Settlements that net to $0.00 or less are held","id":"settlements-that-net-to-000-or-less-are-held","depth":3},{"value":"Settlement files use the processor's existing SFTP location","id":"settlement-files-use-the-processors-existing-sftp-location","depth":3},{"value":"A payment with no ownership record stops a lender's settlements","id":"a-payment-with-no-ownership-record-stops-a-lenders-settlements","depth":3},{"value":"See also","id":"see-also","depth":2}],"frontmatter":{"title":"How settlement works","description":"How Peach pays collected borrower payments to the investors who own each loan, under Peach-managed and Bring Your Own Bank (BYOB) payment processing.","verifiedDate":"2026-10-12T00:00:00.000Z","verifiedSources":[{"repo":"peach","spec":["openapi/redocly.yaml","openapi/settlement.yml","peach/app_setup/utils.py","peach/asyncio/processors/ach.py","peach/asyncio/processors/reconciliation_worker.py","peach/asyncio/processors/settlement.py","peach/models/base.py","peach/models/company.py","peach/payment_instruments/handlers.py","peach/payment_processors/handlers.py","peach/payment_processors/models.py","peach/payment_processors/serializers.py","peach/people/loans/business_logic/create_loan.py","peach/people/loans/handlers.py","peach/reconciliation/handlers.py","peach/reconciliation/models.py","peach/roles/permission_super_admin.py","peach/transactions/ach/handlers.py","peach/transactions/models.py","peach/utils/sqlalchemytypes.py","peach/utils/utils.py"],"ref":"c42dab04c868198c84657046583cb70c42caa92a","branch":"main"},{"repo":"peach-front","spec":["src/admin/AdminRoutes.tsx"],"ref":"41dfe6fd6a817c6b77b4010236afe3afa16894bf","branch":"develop"}],"seo":{"title":"How settlement works"}},"lastModified":"2026-11-03T23:31:11.226Z","pagePropGetterError":{"message":"","name":""}},"slug":"/payments/how-settlement-works","userData":{"isAuthenticated":false,"teams":["anonymous"]},"isPublic":true}