How a marketplace payouts ledger differs from a plain payments setup
A marketplace collects money from buyers, holds it, deducts its fees and pays sellers later, so it must be able to state what each seller is owed at any moment. A payment processor cannot answer that question for the marketplace. Its records show what moved through its rails: authorizations, captures, refunds and settlements to the marketplace's bank account. They do not show which seller a given sum belongs to, how much of it is still pending, or which fee and split produced the amount. The marketplace needs its own balance ledger, kept per seller and per transaction, and that ledger has to be built and operated on its own terms.
The short answer is three self-hosted components working together: a double-entry ledger that holds seller balances and pending funds, a payment orchestration layer that talks to processors, and an accounting system of record that receives summarized postings for the general ledger. Hyperswitch fits the middle layer. It is an open source payments orchestration platform with routing, retries, vaulting and reconciliation modules, not a ledger, and it does not hold seller balances, fee splits or payout obligations. Confirm with any vendor or partner exactly which of these functions the chosen orchestration layer covers, and plan the ledger as a separate system that reads from it.
Decide early which system is the source of truth for a seller's balance and which events create or correct entries, such as a pending hold on capture, a fee deduction, a scheduled payout or a chargeback. Ask the implementation partner to document how each processor event maps to ledger postings, how a refund or chargeback is recorded as a correcting entry instead of an edit, and how the ledger total is compared with processor settlement files every day. Those mappings, not the software choice alone, determine whether the marketplace can explain any seller's balance during a dispute or an audit.
Requirements a marketplace payouts ledger must meet and what each means for the build
This table maps the regulatory and control requirements that most often reach a marketplace payouts ledger to what each one means for design and operations. Read each row as a question to answer with your counsel and assessor before the build is scoped. The main takeaway is that the strictest requirements usually land on access control, change management and evidence rather than on the ledger arithmetic itself.
| Requirement | Source | What it means for the build |
|---|---|---|
| Encryption of seller and customer data in transit and at rest | 16 CFR 314.4, FTC Safeguards Rule (applies if the marketplace is a covered financial institution) | Encrypt ledger database volumes, backups, replicas and API traffic between the ledger, payout scheduler and processor connectors. Confirm with counsel whether the marketplace is covered before treating this as mandatory. |
| Multi-factor authentication for anyone who can post or release payouts | 16 CFR 314.4, FTC Safeguards Rule | Enforce MFA on operator consoles, payout approval tools and admin access to the ledger and processor credentials. Separate the roles that create payouts from those that release them. |
| Change management for posting, fee and split logic | 16 CFR 314.4, FTC Safeguards Rule | Version fee schedules, split rules and payout hold logic as code or controlled configuration. Keep approval records for each change and test it before it touches live sellers' balances. |
| Logging of authorized user activity | 16 CFR 314.4, FTC Safeguards Rule | Log every manual adjustment, refund, chargeback entry, hold release and payout approval with user, time and reason. Ship logs to storage that operators cannot edit. |
| Penetration testing and vulnerability assessments at least every six months, absent continuous monitoring | 16 CFR 314.4(d)(2), FTC Safeguards Rule | Schedule annual penetration tests and vulnerability assessments at least every six months across the payout API, seller portal and ledger hosts. Keep reports and remediation tracking as evidence. |
| Record retention for broker-dealer records | 17 CFR 240.17a-4(b), SEC Rule 17a-4(b) | Applies only if the marketplace or an affiliate is a registered broker-dealer. If it does, plan for at least three years of retention, the first two in an easily accessible place, with storage and retrieval designed for that rule. |
| Card data scope if card details are stored | PCI DSS (control requirements referenced, not reproduced) | Keep card data out of the ledger database and out of payout records by tokenizing at the processor. Storing card data in-house expands the assessed environment substantially, so confirm the model with your QSA before design. |
| Seller tax and payout records | Confirm with marketplace counsel (tax reporting and payee record rules vary by jurisdiction) | Capture seller tax identity, payout jurisdiction and reporting thresholds as ledger metadata. Ask counsel which records must be kept, for how long and in what form before choosing retention settings. |
How held funds, fees, splits and refunds post to the ledger
Each order creates a chain of ledger entries, and the marketplace's finance team should confirm the exact pattern before anything is built. In a common model, the buyer's authorized payment is recorded as a pending transfer from the buyer's funds account into a holding account, so the money is reserved but not yet the seller's. When the order is delivered, the pending transfer is posted, which moves the amount out of holding. At that same point the marketplace fee and the seller's share are written as separate entries, so the seller's payable balance, the marketplace revenue account and any tax or processor fee accounts each show their own movement. Keeping the split as distinct entries lets finance trace each figure back to the order without reverse-engineering a single total.
A scheduled payout then moves value from the seller's payable balance into an outbound transfer to the seller's bank or payout provider. The payout should reference the seller balance it drew from, so a later reconciliation can match the bank debit to specific entries. Refunds and chargebacks follow the same rule: nothing is edited. A refund is a new entry linked to the original transfer, reversing part or all of the seller's share and the fee where policy requires it. A chargeback is a new entry that may be posted before the dispute is resolved, then adjusted again when the outcome is known. This is why every payment event needs an idempotency key, so a retried webhook or repeated API call cannot post the same movement twice.
The decisions to settle early are whether fees are taken at capture or at delivery, whether a refund claws back the seller's share from future payouts or from the current balance, and who approves a correcting entry. Ask the finance and operations leads to write these rules down and to walk through three sample orders (a clean sale, a partial refund and a disputed charge). Those walkthroughs become the test cases for the posting logic. Hyperswitch, an open source payments platform, can carry the processor events that trigger these entries, but the mapping from those events to ledger accounts is marketplace-specific and belongs to the design, not the product.
Which open-source platforms fit each part of the payout flow
A marketplace payout flow touches several systems: a ledger that holds balances, a payment layer that moves money, a billing layer for recurring fees, and an accounting system of record. No single open-source platform covers all of these, so the decision is which component owns which job and where the boundaries sit. The cards below map each component to its role and to the checks that matter before you commit.
Hyperswitch for payment routing
Hyperswitch is an Apache-2.0 composable payments platform that routes payments and payouts across multiple providers, and it includes a reconciliation module and documented self-hosted deployment on Kubernetes with Helm charts. It is not a ledger, so seller balances, holds and fee splits still need a system of record elsewhere. Check which processors and payout rails your marketplace uses, whether the connectors you need are supported in the release you deploy, and where card data is vaulted, since the vault model determines your PCI DSS scope. Hyperswitch does not hold your balances.
Apache Fineract for regulated balances
Apache Fineract is an Apache-2.0 core banking platform. It fits when the marketplace holds seller funds inside a regulated institution, such as a bank or licensed payment entity, and needs core banking features like customer accounts and product configuration. It is heavier than a ledger service and is built around lending and deposit products, so confirm that its account and transaction model matches your hold, release and payout states. Ask your institution whether its licence and regulator accept a platform of this kind as the balance system.
Kill Bill for platform fees
Kill Bill is an Apache-2.0 subscription billing and payments platform. It is relevant when sellers or the marketplace itself pay recurring platform fees, such as monthly subscriptions, plan tiers or usage-based charges, and those invoices need to post to the same books as payouts. Kill Bill handles the billing schedule and invoice lifecycle, not the marketplace split of each sale. Confirm how invoice items and payment events will be exported to your ledger, and whether tax handling meets your jurisdictions.
ERPNext or Odoo Community for accounting
ERPNext (GPL-3.0) and Odoo Community (LGPL-3.0) both provide a general ledger, accounts payable and receivable, and tax records that can serve as the accounting system of record for payouts. They are not built for high-volume balance holds, so use them for period-end journals, seller payable totals and tax reporting, with the dedicated ledger feeding them summarized entries. Confirm which edition, add-ons and multi-company setup you need, and how seller payables map to your chart of accounts before go-live.
A dedicated double-entry ledger
A purpose-built double-entry ledger such as TigerBeetle or Blnk is the component that tracks each seller balance, pending transfer, release and refund as correcting entries. Its features, client protocols, deployment topology and reconciliation tooling must be confirmed against the current release, not assumed from this page. Also confirm how it performs at your expected transaction volume and latency, how it handles idempotent retries from the payment layer, and what licence terms apply before you build around it.
Deployment constraints: data location, PCI scope, identity and operations
A marketplace ledger touches card data, seller money movement, finance systems and staff access, and each of these carries its own deployment constraint. The four cards below cover the constraints that most often shape the design, and each one names a decision or a check to settle before the architecture is fixed.
Payment layer scope and PCI
If the marketplace runs Hyperswitch, the core app server splits work between Router and Scheduler, both backed by PostgreSQL with a master and replica setup and by Redis for caching and the scheduler queue. The vault model decides how much of the stack falls under your PCI DSS obligations. Under the self-hosted, in-house PCI model, the merchant is fully responsible for PCI DSS certification and data handling. Confirm the vault model with your QSA before the ledger design assumes any card data path.
Ledger placement and backup
The ledger holds the authoritative record of what each seller is owed, so its placement is a financial control, not just an infrastructure choice. Decide which cloud account, region or data center hosts it, and where its replicas sit. Confirm in writing the replication topology, backup frequency, point-in-time recovery and restore testing the chosen ledger supports. Do not assume these features exist until the vendor documents them for your version.
ERP and general ledger interface
Settled seller balances, fee income and refund entries must reach the general ledger in a form finance can audit. Plan the export format, the posting batch cut-off and the mapping of ledger accounts to GL accounts. Require that each batch is reviewed and approved by a named finance owner before import, and that totals are compared against the ledger balance on the same date. Rejected or partially posted batches need a documented correction path.
Identity and access controls
The Hyperswitch Control Center supports single sign-on through OpenID Connect only, with no SAML support, no just-in-time or SCIM provisioning, and no mapping of roles from the identity provider. Users must be invited first, and roles are managed inside Hyperswitch. Plan joiner, mover and leaver steps as manual tasks with recorded approvals, and review dashboard roles on a fixed schedule. Confirm these limits against your Hyperswitch version before your identity team commits to a design.
How a marketplace payouts rollout runs in phases
The sequence moves from agreed money rules to a ledger that posts, reconciles and pays out under tested controls, with each phase closing on a written output that finance and security can review.
Scope the account model and money rules
DeployOpen works with your finance, product and compliance owners to map the account model for sellers, the marketplace, pending balances and processor clearing accounts. The team documents fee and split rules, refund and chargeback treatment, currencies, and the payout calendar that finance wants. Scope, deliverables and timelines are agreed in writing before work starts. The phase closes with a signed rules document and a chart of accounts that every later test case traces back to.
Select ledger and orchestration components
Against the written requirements, the team evaluates candidate components for the ledger, payment orchestration and payout rails, including whether a processor-side or self-hosted option fits your data location and PCI scope. Where a component is open source, the review covers license terms, release cadence, supported deployment models and the operational skills your team would need. The output is a short decision record listing what was chosen, what was rejected, and which capabilities you still need to confirm with each vendor.
Build posting logic and test against replayed events
Engineers implement posting rules for holds, fee and split entries, scheduled payouts and reversals. Every write path is idempotent, so a retried processor webhook cannot post twice. Refunds and chargebacks are recorded as correcting entries rather than edits to history. The team then replays recorded processor event streams, including duplicates, out-of-order deliveries and failures, and checks that resulting balances match expected values. The phase closes when the replay suite passes and the test evidence is archived.
Run reconciliation and month-end dry runs alongside traffic
Before any seller money moves on the new ledger, the team runs it in parallel with live processor traffic. Daily matching compares ledger balances with processor settlement files and bank statements, and unmatched items flow into an exception queue with named owners. Finance runs at least one month-end close as a dry run to confirm the reports, adjustments and general ledger interface produce the figures they need. The output is a reconciliation report showing differences explained or resolved.
Complete penetration testing and access review
Before payouts go live, DeployOpen tests the payout API, admin consoles, the orchestration layer and their integrations, and reviews who can post entries, approve payouts and change posting logic. Findings are ranked, fixed and retested. Multi-factor authentication, encryption in transit and at rest, and activity logging are verified against the controls your regulator or auditor expects. The phase closes with a signed test report, a remediation log and an access review record that your independent assessor can inspect.
Hand over runbooks, restore tests and change records
DeployOpen delivers operational runbooks for payout runs, failed transfers, processor outages, reconciliation exceptions and rollback. The team performs backup restore tests against the ledger and confirms recovery steps with your operations staff. Change management procedures are set up so that posting logic, configuration and infrastructure changes each produce a recorded approval. The phase closes when your team has run the runbooks with DeployOpen observing and the handover package is accepted in writing.
Build, self-host a ledger or use a managed ledger for seller balances
Building the balance ledger on PostgreSQL or another relational database gives the engineering team full control over the schema, posting logic and reporting. The marketplace owns every rule, including how pending funds are held, how fees and splits are posted, and how refunds and chargebacks are recorded as correcting entries rather than edits to history. The cost sits mostly in people and in the tests that prove the balances are right.
- Correctness testing: The marketplace's own team writes and maintains the invariant tests, such as entries balancing to zero per transfer and idempotent posting under retries. No vendor sets this baseline for you.
- Backup and recovery: Backup, point-in-time recovery and restore drills run on the database platform the marketplace already operates. Recovery targets must be written and tested by the same team.
- Upgrades: The team owns schema migrations and database version upgrades, and it must prove that old and new posting logic produce the same balances.
- Evidence: Change records, migration logs and reconciliation reports exist only if the team builds them. Auditors will ask for access controls and change management over the posting code.
- Recurring versus one-time: Design and the first correctness suite are largely one-time. Ongoing maintenance, incident response and rule changes recur for as long as the ledger runs.
Moving off this option later means exporting the schema and history into another ledger, which requires mapping every entry type and proving balances match at cutover.
Check who on the team will own the ledger after launch, and what evidence the marketplace's auditors expect before posting logic changes.
Running a dedicated open-source ledger such as TigerBeetle or Blnk in the marketplace's own cloud account or data center moves the double-entry engine, transfer primitives and idempotency handling into a purpose-built component. The marketplace still decides the account model, fee logic and payout rules, and it operates the infrastructure that holds the balances.
- Correctness testing: The marketplace tests its own posting rules and reconciliation logic on top of the engine. Engine-level behavior is tested by the project, but the marketplace should confirm which guarantees the chosen version documents.
- Backup and recovery: The operator defines replication, backup and restore for the ledger cluster. Recovery testing must cover the full cluster, not only one node.
- Upgrades: Version upgrades follow the project's release notes and the marketplace's change process. Confirm the license terms and the support model before committing to a version.
- Evidence: Access logs, deployment records and configuration history are produced by the marketplace's own tooling. Confirm what the engine itself logs and exports.
- Recurring versus one-time: Cluster build, integration and first recovery test are one-time. Infrastructure, patching, on-call coverage and upgrades recur.
Moving later is usually easier than leaving a hand-built schema because the engine's transfer model is explicit, but the balance history still has to be exported and reconciled.
Confirm the engine's deployment topology, the license terms and the team skills needed to operate it before choosing this option.
A managed ledger service runs the ledger for the marketplace under a contract, so the vendor operates the infrastructure, backups and upgrades. The marketplace keeps responsibility for how it uses the ledger, including payout logic, data it sends, and access control on its own side of the integration. This option shifts operating effort to the provider but moves some risk into a third-party relationship.
- Correctness testing: The marketplace still tests its integration and its reconciliation to processor settlements. Ask the provider for its own testing and change process, and whether it will share results.
- Backup and recovery: The provider defines recovery objectives in its contract. Confirm them in writing and ask how restores are tested and reported.
- Upgrades: The provider schedules upgrades. Ask how the marketplace is notified, whether it can test against new versions, and how breaking changes are handled.
- Evidence: Ask for audit reports, incident records and access logs the provider can supply. Treat third-party risk assessment as the marketplace's responsibility.
- Recurring versus one-time: Integration is one-time. Subscription or usage fees, support plans and contract reviews recur. Ask for the fee basis in writing; no estimate is given here.
Moving off a managed service later depends on the contract. Ask for data export formats, export timing, and a documented exit process before signing.
Check the exit terms, data export format and recovery commitments in the contract before the integration begins.
Evidence auditors and regulators ask for from a marketplace payouts ledger
This table maps each piece of evidence to who typically asks for it, and the component in a self-hosted payouts ledger that produces it. Use it to design logging, change control and reconciliation before an assessment rather than after. DeployOpen prepares these artifacts, but auditors and certification bodies issue any opinion on them.
| Evidence | Who asks | Which component produces it |
|---|---|---|
| Access logs for users who post, approve or release payouts | Internal audit, payment processor, SOC or compliance assessor | Identity provider and centralized logging covering the ledger API, admin console and payout release tooling |
| Change records for posting logic and fee or split rules | Internal audit, change advisory board, assessor | Version control history, reviewed merge requests and linked change tickets with approvals |
| Completeness evidence that every processor event has a ledger entry | Finance controller, external auditor, processor partner | Reconciliation reports comparing processor settlement files with ledger balances, plus exception queue history |
| Records of corrections linking original and correcting entries | External auditor, finance leadership, dispute teams | Ledger transaction history showing refund and chargeback entries that reference the original transfer ID |
| Penetration test and vulnerability assessment reports at the required cadence | Regulator, bank partner, assessor under 16 CFR 314.4 | Scheduled testing records and remediation tickets, produced by the security testing program covering the payouts stack |
| Retention evidence for payout and settlement records, if SEC Rule 17a-4 applies | Regulator, compliance lead for broker-dealer or affiliated entity | Write-once or archive storage configuration, retention policy and restore test records; confirm applicability with counsel |
| Segregation of duties for payout release | Internal audit, assessor | Role definitions and approval logs in the ledger or payout tooling showing separate maker and approver accounts |
Questions to ask an implementation partner about marketplace payouts
Start with how the partner proves the posting logic is correct. Ask them to show how they replay recorded processor events, including charges, transfers, payouts and reversals, against a test ledger and compare the resulting seller balances with the expected figures. Then ask how duplicate webhook deliveries and out-of-order events are handled, and which idempotency keys guard each posting. Ask for the test cases behind the fee and split rules, especially where a single order creates several entries. A partner who cannot show a replay run with recorded inputs and expected outputs has not yet tested the thing that moves money. Next, ask how a refund that arrives after a seller payout is posted. The answer should be a correcting entry that reduces the seller's available balance, possibly driving it negative, with a defined rule for recovering the amount from future payouts or holding the seller's account. Ask who approves that rule, how the negative balance is shown to finance, and whether chargebacks follow the same path. Ask which vault model they recommend for stored payment data and who carries PCI DSS scope under it. The Hyperswitch docs place full PCI DSS responsibility on the merchant under the in-house model, so get the scope decision and its owner in writing before design starts.
Ask how the partner demonstrates change management and access control to an auditor. Request the change records for posting logic, the approval path for configuration changes such as fee tables, and the list of roles that can post manual entries or reverse payouts. Ask how the Control Center's single sign-on is configured. The Hyperswitch docs say it supports OpenID Connect only, with no SAML, no SCIM and roles managed inside Hyperswitch, so ask how access reviews will be run on those roles. Ask what the reconciliation exception workflow looks like for finance: who sees unmatched processor items, how aging is tracked, and which entries can be made without a second approver. Finally, ask what the partner hands over at go-live: runbooks for payout runs and failed transfers, restore tests against the ledger database with recorded results, and documentation of every posting rule. Then ask what stays with the client after go-live. Typical items include processor account changes, key and secret rotation, upgrades of the Hyperswitch release, on-call ownership and decisions on fee and payout policy. Confirm in the written scope which of these the partner performs, which are retained, and whether any support is delivered as a retainer.
What a marketplace payouts ledger costs and what the work needs from us
What drives the cost of a marketplace payouts ledger?
The cost follows the complexity of the money movement, not the software license, because the core ledger platforms covered on this page are open source. The main drivers are the number of seller account types, how many fee and split rules apply to each transaction, how often and over which rails sellers are paid, how many payment processors settle into the ledger, how much card data touches your systems (PCI scope), and how deep reconciliation must go. Each driver adds design, integration and test work. Ask for a quote that lists each of these as a separate line item so you can see which choices move the price.
Which costs are one-time and which recur after launch?
One-time costs cover discovery, the ledger design and posting logic, processor and bank integrations, the reconciliation rules, and the correctness and failover testing that proves balances hold under load. Recurring costs cover hosting and storage, security patching, upgrades of the ledger and its dependencies, periodic recovery and reconciliation testing, and support for finance operations when a payout fails or a settlement file changes format. Ask the partner to separate build fees from a support retainer and to state what the retainer includes, such as response windows and upgrade handling, in writing.
Can our internal team run a payouts ledger without outside help?
A capable internal team can run one, but the work spans several skills at once: distributed systems or database engineering to operate the ledger, payments integration to handle processor events and webhooks, finance and accounting knowledge to design balances and reconciliation, and security engineering for key handling, access control and evidence. Teams that have run a production ledger before usually need less external help. Teams that have not should expect a learning curve in correctness testing and month-end reconciliation, which are the areas where errors surface late and cost the most.
What do we need to provide before the work starts?
The engagement depends on decisions and access that only your organization can supply. Expect to provide written finance rules for fees, splits, holds, refunds and chargebacks, plus the accounting treatment your controller expects. You will need processor sandbox and production read access for settlement and payout reports, the sample files your bank issues, and details of your identity provider if staff will sign in to the ledger or its admin tools. Environment access to your cloud account, data center or private network is also needed, along with named owners who can approve decisions within the agreed timeline.
How does a fixed-scope engagement and written quote work?
Most DeployOpen engagements are fixed-scope. Before work starts, the scope, deliverables, timeline and acceptance criteria are agreed in writing, and the quote follows from that written scope. DeployOpen does not publish a price list, so the quote reflects the drivers listed above. Ask that the scope name the seller account types, processors, payout rails and reconciliation reports in scope, and list what is excluded. Changes to scope should go through a written change request so budget and timeline stay traceable. Ongoing support, upgrades and continuous testing are available as separate retainers.
What determines how long a payouts ledger project takes?
The timeline depends mostly on how settled the finance rules are, how many processors and payout rails are connected, and how quickly your team can grant access to sandboxes, bank files and environments. Late changes to fee or split logic, or a new processor added mid-project, usually extend the schedule more than the platform setup does. Testing time also depends on how many transaction types need replay and reconciliation before finance signs off. No duration is promised here; the written scope will set the timeline once these inputs are known.
Which security and compliance evidence does the payouts work produce?
Payouts touch customer and seller money, so the work should produce evidence that access is controlled and activity is logged. Under the FTC Safeguards Rule, covered financial institutions must encrypt customer information in transit and at rest, use multi-factor authentication for system access, follow change management procedures, and log authorized user activity. Penetration testing and vulnerability assessments are also required at set intervals unless continuous monitoring is in place. DeployOpen prepares these controls and records for your assessment, but independent auditors issue the actual findings. Ask the partner which evidence it will hand over and in what format.
Does card data handling change the cost and scope?
Yes. If your marketplace stores or passes card data through its own systems, PCI DSS scope grows and the cost rises with it. Keeping card capture and tokenization with a processor or external vault keeps your ledger out of most card data scope, while in-house vaulting makes you fully responsible for PCI DSS certification and data handling. Hyperswitch documents three self-hosted vault models, including one where the merchant owns the PCI obligations, so ask your team to confirm which model applies before the quote is written.
How DeployOpen scopes, builds and supports a marketplace payouts ledger
DeployOpen plans, implements, integrates, hardens, documents and supports self-hosted open-source platforms inside your own cloud accounts, data centers or air-gapped networks. For a marketplace payouts ledger, we start from written requirements for pending funds, fees, payouts, refunds and reconciliation, then build and test the ledger in your environment.
How we scope
- Map every money movement a seller balance can take, from order capture through payout and chargeback.
- Agree in writing which ledger platform, processor connections and reconciliation outputs are in scope.
- Confirm hosting location, access roles and retention rules before any build work starts, since the scope is fixed.
How we build
- Configure the ledger with double-entry accounts for pending, available, fee and payout balances.
- Test idempotent posting, duplicate webhook handling and refunds posted as correcting entries, not edits to history.
- Connect payment processor exports and bank records so the team can check ledger balances against settlements.
How we hand over
- Document account structure, posting rules, payout schedules and the reconciliation procedure for your finance team.
- Deliver test evidence showing how the ledger handles timing differences, unmatched items and failed payouts.
- Walk operators through access controls, change management for posting logic and the audit trail they will rely on.
How we support
- Offer ongoing support, upgrades and continuous testing as a retainer after handover, scoped in writing.
- Maintain backups and platform updates for the ledger components running in your infrastructure.
- Re-test posting logic and reconciliation rules whenever processor terms, payout rules or the platform version change.
