Marketplace Payout Spec: Reconciliation and Disputes

I have watched marketplace platforms quietly bleed money through their payout systems, and the root cause is always the same: the spec treated payouts as a reporting problem instead of an accounting problem. If your written spec does not require a double-entry ledger on page one, the rest of the document is decoration.

Published on 2026-03-09 · Updated 2026-05-06 · 7 min read · Author: Spec Coding Editorial Team · Review policy: Editorial Policy

The Ledger Is the Spec, Not the Payouts Table

The first thing I argue for in any payout review is deleting the payouts table from the initial design and starting over with a double-entry ledger. A payouts table with seller_id, amount, and status is where engineers end up when they model what they see on the screen instead of what happens in money movement. Every dollar entering the platform has to land in one account and leave another, and the spec must say so in writing.

My rule: the spec forbids any code path that changes a balance without a paired debit and credit in the same transaction. Orders receivable, seller payable, platform revenue, processor fees, sales tax liability, reserve, and chargeback loss are separate accounts. When the payouts report disagrees with the ledger, the ledger wins.

Hold Periods, Thresholds, and Payout Cadence

New sellers do not get paid immediately. That sentence belongs in the spec with a specific number. Hold periods of seven to fourteen days on a new seller's first cycle exist because chargebacks cluster in the first week after purchase. If the spec does not name the hold, someone will helpfully delete it during a sprint to fix a support ticket.

Cadence rules I treat as non-negotiable:

• Default weekly payouts on a fixed weekday so finance can predict cash movement.
• On-demand payouts gated by a minimum balance ($10 floor) and a daily cap per seller.
• A reserve percentage held from new sellers, released on a schedule visible in the dashboard.
• Explicit definition of "available balance" versus "pending balance" — the spec names which statuses qualify.

Daily Reconciliation Against the Processor

Every day, a job compares the platform ledger against Stripe or Adyen or whoever sits between us and the card networks. The spec says what happens when they disagree, not if. Penny-level rounding differences under a configurable tolerance get logged and auto-closed; anything larger opens a reconciliation ticket and blocks the next payout run for the affected seller.

"Blocks the next payout run" is the part product managers argue about. Hold the line. A single $0.43 unexplained delta today is how you discover a $40,000 fee-calculation bug six months from now.

The $100 Order That Gets Chargebacked After Payout

Here is the scenario every marketplace spec has to answer, and most do not. A buyer places a $100 order. The platform fee is $10, the processor fee is $3, and the seller's payable balance increases by $87. Seven days later, the seller's weekly payout runs and that $87 leaves the platform. Twenty-one days after the order, the buyer's bank files a chargeback for the full $100.

The spec must name who eats the loss and in what order. My default:

• First, attempt to claw back from the seller's available balance. Create a negative ledger entry against seller payable.
• If available balance is insufficient, freeze the seller account and create a seller debt ledger entry that future sales pay down before any new payout.
• If the seller is inactive or disputes the debt, escalate to manual review with a defined SLA (five business days in my last spec).
• If collection fails after the SLA, move the balance to a chargeback loss account owned by the platform. That is the cost of doing business and finance needs to see it as a line item, not a mystery.

The processor fee on the original $100 does not come back — the platform ate $3 the moment the buyer paid. The spec has to show that fee as a separate debit so your margin reports are not quietly lying to you.

Fees, Taxes, and Refunds as First-Class Ledger Lines

Every economic component of an order gets its own ledger line at the moment of capture: gross sale, platform commission, processor fee, sales tax collected, shipping, tip, promotional credit. No netting at the source. When a partial refund happens, each component gets reversed proportionally and independently.

Refunds are where naive specs fall apart. Three flavors the spec must handle distinctly: refund before payout (reverse the pending balance), refund after payout with positive balance (claw back from available), and refund after payout with insufficient balance (the chargeback flow above, minus the dispute process). Pretending "refund is just a negative order" has cost me whole weekends.

1099 Data Captured at Payout Time

In the US, sellers over the annual threshold get a 1099-K. The worst time to figure out who they were and what they earned is January of the following year. The spec requires every payout event to capture an immutable snapshot: legal name, TIN, address, payout amount, currency, tax year, and jurisdiction. If the seller updates their legal name in March, historical payouts keep the February name. Finance and the IRS both care about this distinction, and the spec has to enforce it at the schema level.

Acceptance Criteria in Given/When/Then

- Given a seller with an available balance of $87
  When a chargeback for $100 on a previously paid-out order is received
  Then the seller payable account is debited $87
  And a seller debt entry of $13 is created
  And the seller's payout status is set to "frozen"
  And the next successful sale credits the debt account before payable

- Given a daily reconciliation run
  When the processor balance and ledger balance differ by more than $1.00
  Then payout jobs for the affected currency are paused
  And a P1 reconciliation ticket is opened with both balances attached
  And the pause persists until an operator resolves the ticket with a written reason

- Given a new seller within their 14-day hold period
  When the seller requests an on-demand payout
  Then the request is rejected with reason "hold_period_active"
  And the response includes the release date and current held amount

Multi-Currency and Immutable Audit Trail

If the platform sells across borders, the spec names the FX snapshot time. I use capture time, not payout time, because the seller's expected payout should not move while funds sit in pending. That choice has a cost: the platform absorbs FX slippage between capture and payout. The spec must say so explicitly and finance must price it into the platform fee.

Every ledger entry is append-only. Corrections are new entries that reverse old ones, never updates in place. Every operator action touching money — unfreezing a seller, writing off a debt, manually triggering a payout — produces an audit record with the operator's identity, reason, before and after state, and a second approver above a threshold. When the auditor shows up, "who approved this $4,200 manual payout on March 3rd" should be answerable in one query. If the spec does not require that trail, you are shipping a compliance problem and calling it a feature.

Controls Before the First Payout

The first payout should be treated like a launch review, not a background job. I want these controls attached to the spec before money leaves the platform.

• Dry-run payout file: seller ID, currency, gross amount, fees, holds, debt offsets, and net payout for at least ten representative sellers.
• Pause switch: one owner can stop payouts by currency without disabling checkout.
• Exception queue: mismatches, negative balances, chargebacks over available balance, and missing tax identity route to named operators.
• Audit sample: one manual adjustment is traced from operator action to ledger entry to payout file.

The launch question is not "can the job run?" The launch question is "can we explain every dollar after it runs?" If the answer is no, the payout spec is still unfinished.