# Pathrule Pattern: Marketplace Payments and Payouts (1.0.0) # ::pathrule:package:marketplace-payouts ### [RULE] Record every marketplace movement as balanced entries (path: /src/ledger) Charges, fees, seller obligations, transfers, refunds, disputes, reserves, and payouts post to an internal double-entry ledger. Provider objects report external movement but cannot explain the platform's contractual allocation, pending obligations, or corrections across several parties. Enforce this boundary in /src/ledger so invalid work stops before it reaches another subsystem or creates an externally visible side effect. - Post immutable debit and credit entries with currency, party, order, provider reference, effective time, and idempotency key. - Separate pending, available, reserved, in-transit, paid, and negative balances instead of overwriting one seller total. - Create compensating entries for corrections; never edit or delete posted financial history. - Reject a posting set unless debits equal credits per currency and every external movement maps to an internal account. Verification: Replay the complete lifecycle from charge through split, fee, refund, dispute, reversal, and payout; confirm each posting balances and reproduces every party balance. --- ### [RULE] Do not transfer funds before the obligation is earned (path: /src/payments) Transfer eligibility depends on fulfillment, refund risk, dispute exposure, reserves, and connected-account capability, not payment success alone. Immediate transfer can leave the platform liable when service is canceled, a charge is disputed, or the seller cannot accept payouts. Enforce this boundary in /src/payments so invalid work stops before it reaches another subsystem or creates an externally visible side effect. - Model the event that earns seller funds and keep unearned amounts pending until that evidence arrives. - Check account onboarding, capability, sanctions or compliance status supplied by the provider before scheduling movement. - Apply reserve and delay policy consistently, with a documented reason and release event. - Pause transfers and payouts when the seller balance is negative or an unresolved risk hold exists. Verification: Exercise delayed fulfillment, cancellation, partial fulfillment, account restriction, refund, and dispute scenarios; confirm no ineligible amount becomes available. --- ### [RULE] Make every external money mutation idempotent (path: /src/payments) Charges, transfers, reversals, refunds, and payouts use stable operation keys tied to one internal ledger intent. Network timeouts and webhook retries make it unsafe to decide whether money moved from the presence or absence of a response. Enforce this boundary in /src/payments so invalid work stops before it reaches another subsystem or creates an externally visible side effect. - Create the ledger intent first with a unique operation key, expected amount, currency, source, destination, and business reference. - Send the same idempotency key on provider retries and reconcile ambiguous responses by provider lookup. - Allow one worker to claim an intent and make concurrent workers observe its state rather than issuing another mutation. - Treat provider success as external evidence to post, not permission to invent a second internal transaction. Verification: Inject timeouts before and after the provider accepts each mutation, then retry concurrently; confirm one external object and one balanced posting set exist. --- ### [MEMORY] Charge type determines marketplace liability (path: /src/payments) Direct, destination, and separate charge-and-transfer models place fees, refunds, disputes, negative balances, statements, and regional constraints on different parties. Choose the provider charge model from the marketplace's legal and operational money flow before implementing endpoints. Write who is merchant of record, who appears to the customer, who carries negative balances, and how multi-party splits work. Keep provider charge type behind an adapter while preserving its liability implications in ledger accounts and runbooks. Require finance and legal review before changing the flow for an existing region or seller cohort. Keep the decision explicit at /src/payments; moving it into an incidental caller makes behavior depend on which route happened to execute first. See /src/ledger for internal obligations and /src/webhooks for provider evidence. That related boundary consumes this decision and carries the evidence that proves it still holds. --- ### [MEMORY] Refunds and disputes reverse allocations, not history (path: /src/ledger) A customer refund or dispute changes several liabilities and may require transfer reversal or reserve use, but it does not erase the original sale. Post a new allocation that links to the original charge and identifies the customer, seller, platform fee, tax, reserve, and provider components affected. Define partial allocation order and rounding per currency before taking money from a seller. Represent uncollectible seller amounts as an explicit receivable or platform loss according to policy. Keep dispute provisional and final outcomes distinct so won disputes restore the intended balances exactly once. Keep the decision explicit at /src/ledger; moving it into an incidental caller makes behavior depend on which route happened to execute first. See /src/payments for provider mutations and the reconciliation skill for external matching. That related boundary consumes this decision and carries the evidence that proves it still holds. --- ### [SKILL] reconcile-marketplace-funds (path: /) --- name: reconcile-marketplace-funds description: Reconcile marketplace ledger balances with provider charges, transfers, refunds, disputes, reserves, and payouts. --- # Reconcile Marketplace Funds Run this procedure whenever the governed surface changes or its operational evidence becomes stale. 1. Freeze a time window and export internal postings plus provider balance transactions using stable charge, transfer, reversal, refund, dispute, and payout identifiers. 2. Match external movements to balanced posting sets by identifier, currency, amount, party, and effective time; isolate unmatched and many-to-one relationships. 3. Recompute seller pending, available, reserved, in-transit, paid, and negative balances from entries and compare them with operational views. 4. Classify and resolve timing, duplicate, missing-event, rounding, manual-provider, and configuration differences; rerun until the same inputs produce zero unexplained variance. Record the decision, failed checks, and follow-up owner with the change. A successful run leaves reproducible evidence that another reviewer can inspect without repeating the investigation from memory.