Payments are where marketplace ambitions meet accounting reality. A checkout that works is easy. A system that correctly splits a transaction between four parties, handles a partial refund three weeks later, survives a chargeback, reconciles to the cent against a processor statement, and produces figures an auditor accepts is considerably harder. This article covers the architectural decisions that determine which of those two systems a team ends up with.
The Central Question: Does the Platform Touch the Money?
Everything else follows from this. Three broad models:
Facilitated, non-custodial. The processor moves funds directly between buyer and seller sub-accounts; the platform never holds a balance. Lowest regulatory burden, fastest to launch, least flexibility. Refund and dispute logic is largely constrained by what the processor supports.
Custodial via a regulated partner. Funds land in segregated accounts held by a licensed partner, with the platform directing movements through an API. Considerably more control over timing, holds, and multi-party splits, at the cost of a heavier integration and partner due diligence.
Directly licensed. The platform obtains its own licensing and holds funds itself. Maximum control and margin, substantial cost and ongoing compliance obligation. Rarely the right choice before significant scale.
The decision should be made against the product's actual requirements — hold periods, milestone releases, multi-currency payouts, complex fee structures — rather than against a general preference for control. Many teams discover a year in that their chosen model cannot express a fee structure the business now needs, and migrating a live payment system is among the most disruptive projects a platform can undertake.
Model the Ledger Before the Integration
The most common architectural mistake is treating the payment processor as the source of truth. Processors record their view of movements, not the platform's view of obligations. The two diverge immediately: fees accrued but not yet charged, payouts owed but not yet sent, refunds authorized but not settled, revenue recognized across a period rather than at a moment.
The platform needs its own double-entry ledger. Practical requirements:
- Append-only entries. Never update a balance in place. Balances are computed from entries; entries are never edited, only offset by new ones.
- Every entry balances. Debits equal credits within a transaction, including fee, tax, and rounding lines.
- Explicit accounts per party and purpose. Seller payable, platform revenue, tax payable, escrow held, reserve held, processor receivable. Vague catch-all accounts make reconciliation impossible.
- Idempotency keys on everything. Payment webhooks arrive out of order and more than once. A ledger that double-posts a retried webhook is worse than no ledger.
- Currency stored as minor units in integers. Floating point in money code is a defect waiting for a large enough transaction.
Splitting a Transaction Correctly
A single order may need to divide between seller payout, platform commission, payment processing cost, affiliate or referral share, sales tax or VAT, insurance or protection fee, and promotional discount absorbed by one party or another. Two principles keep this tractable.
First, compute the split from an explicit fee schedule stored as data, not as code. Fee logic changes constantly — promotions, tiered rates, category-specific commission, negotiated enterprise terms. When it lives in code, every change is a deployment and historical transactions become impossible to explain.
Second, decide and record who bears each cost. When a discount is applied, does the platform absorb it or the seller? When a refund is issued, is the commission returned? When a chargeback occurs, is it recovered from the seller's future payouts? These are business decisions, and they must be encoded explicitly, because the default behaviour of most processors is not what the business intends.
Payouts: The Part That Generates Support Tickets
Payout systems fail in mundane ways that nonetheless erode supplier trust quickly. A short checklist of what to design for:
- Schedule and visibility. Suppliers should be able to see what they will be paid, for which transactions, and on what date, before the payout runs.
- Holds and reserves. New or high-risk suppliers may have funds held longer. This must be explained in the interface, not discovered.
- Failure handling. Bank details change, accounts close, names mismatch. Failed payouts need automatic retry, clear notification, and a self-service correction path.
- Negative balances. A refund after payout leaves the supplier owing the platform. The system needs a defined recovery policy rather than an exception.
- Statements. Suppliers need downloadable records for their own accounting. This is not a nice-to-have in B2B contexts.
Reconciliation: Prove the Numbers Every Day
Reconciliation is the process of confirming that the platform's ledger, the processor's records, and the bank's statements agree. It should run automatically and daily, producing a short report of unmatched items rather than a large report of everything.
Typical sources of discrepancy include processor fees deducted at settlement rather than at capture, currency conversion applied at a different rate than expected, refunds that cross a settlement boundary, and disputes reversed after the fact. None are unusual; all are painful to untangle months later. A team that reconciles from day one deals with one day of discrepancy at a time. Studios that specialize in transactional platforms, such as u1core.com, generally treat automated reconciliation as part of the initial payment build rather than a later finance request, because the cost of adding it retroactively includes reconstructing history.
Testing Money Code
Payment logic deserves a different testing standard than the rest of the application. Worth covering explicitly: partial refunds, refunds after payout, multi-item orders with mixed tax treatment, currency rounding at the boundary, duplicate webhook delivery, out-of-order webhook delivery, chargeback and representment, and the full lifecycle of a disputed transaction. Property-based tests that assert the ledger always balances across randomly generated sequences of events catch a surprising number of real defects.
A Sensible Build Order
- Define the fee schedule and money flow as a written specification, reviewed by whoever will own finance.
- Build the internal ledger with idempotent posting.
- Integrate the processor against that ledger, never as a replacement for it.
- Ship reconciliation before ship-to-production, even in a crude form.
- Add payout visibility and self-service correction early — it removes more support load than any other feature.
- Layer tax, multi-currency, and complex fee tiers once the core is stable.
Payment architecture rewards conservatism. The interesting product work in a marketplace happens elsewhere; the payment layer's job is to be dull, correct, and explainable — for years, across every edge case the business eventually encounters.