Marketplace Payments and Payouts

Pathrule3 Rules • 2 Memories • 1 Skill

Marketplace payments and payouts create several financial obligations from one customer charge, while refunds, disputes, reserves, delayed fulfillment, and negative balances can change who is owed later. This bundle defines an internal double-entry ledger, connected-account onboarding, transfer timing, idempotent money movement, and reconciliation. Unlike Stripe Billing, it covers multi-party liability rather than a single merchant charging customers.

Suggested path map

Pathrule places each piece on the matching path, so your assistant only sees it where it belongs. This is the scoping you get on import; you can adjust it in your workspace.

/ workspace root

reconcile-marketplace-funds

src/

ledger/

Record every marketplace movement as balanced entries

Refunds and disputes reverse allocations, not history

payments/

Do not transfer funds before the obligation is earned

Make every external money mutation idempotent

Charge type determines marketplace liability

Rules

Record every marketplace movement as balanced entries/src/ledgerhighstrictCharges, fees, seller obligations, transfers, refunds, disputes, reserves, and payouts post to an internal double-entry ledger.

1	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.
2
3	- Post immutable debit and credit entries with currency, party, order, provider reference, effective time, and idempotency key.
4	- Separate pending, available, reserved, in-transit, paid, and negative balances instead of overwriting one seller total.
5	- Create compensating entries for corrections; never edit or delete posted financial history.
6	- Reject a posting set unless debits equal credits per currency and every external movement maps to an internal account.
7
8	Verification: Replay the complete lifecycle from charge through split, fee, refund, dispute, reversal, and payout; confirm each posting balances and reproduces every party balance.

Do not transfer funds before the obligation is earned/src/paymentshighstrictTransfer eligibility depends on fulfillment, refund risk, dispute exposure, reserves, and connected-account capability, not payment success alone.

1	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.
2
3	- Model the event that earns seller funds and keep unearned amounts pending until that evidence arrives.
4	- Check account onboarding, capability, sanctions or compliance status supplied by the provider before scheduling movement.
5	- Apply reserve and delay policy consistently, with a documented reason and release event.
6	- Pause transfers and payouts when the seller balance is negative or an unresolved risk hold exists.
7
8	Verification: Exercise delayed fulfillment, cancellation, partial fulfillment, account restriction, refund, and dispute scenarios; confirm no ineligible amount becomes available.

Make every external money mutation idempotent/src/paymentshighstrictCharges, transfers, reversals, refunds, and payouts use stable operation keys tied to one internal ledger intent.

1	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.
2
3	- Create the ledger intent first with a unique operation key, expected amount, currency, source, destination, and business reference.
4	- Send the same idempotency key on provider retries and reconcile ambiguous responses by provider lookup.
5	- Allow one worker to claim an intent and make concurrent workers observe its state rather than issuing another mutation.
6	- Treat provider success as external evidence to post, not permission to invent a second internal transaction.
7
8	Verification: Inject timeouts before and after the provider accepts each mutation, then retry concurrently; confirm one external object and one balanced posting set exist.

Memories

Charge type determines marketplace liability/src/paymentsDirect, destination, and separate charge-and-transfer models place fees, refunds, disputes, negative balances, statements, and regional constraints on different parties.

1	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.
2
3	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.
4
5	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.

Refunds and disputes reverse allocations, not history/src/ledgerA customer refund or dispute changes several liabilities and may require transfer reversal or reserve use, but it does not erase the original sale.

1	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.
2
3	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.
4
5	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.

Skills

reconcile-marketplace-funds/rootReconcile marketplace ledger balances with provider charges, transfers, refunds, disputes, reserves, and payouts.

1	---
2	name: reconcile-marketplace-funds
3	description: Reconcile marketplace ledger balances with provider charges, transfers, refunds, disputes, reserves, and payouts.
4	---
5
6	# Reconcile Marketplace Funds
7
8	Run this procedure whenever the governed surface changes or its operational evidence becomes stale.
9
10	1. Freeze a time window and export internal postings plus provider balance transactions using stable charge, transfer, reversal, refund, dispute, and payout identifiers.
11	2. Match external movements to balanced posting sets by identifier, currency, amount, party, and effective time; isolate unmatched and many-to-one relationships.
12	3. Recompute seller pending, available, reserved, in-transit, paid, and negative balances from entries and compare them with operational views.
13	4. Classify and resolve timing, duplicate, missing-event, rounding, manual-provider, and configuration differences; rerun until the same inputs produce zero unexplained variance.
14
15	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.

Why this pattern

Agents treat a payment provider balance as the marketplace ledger, transfer too early, and discover during refunds or disputes that seller and platform liabilities were never modeled.

Built for Platforms collecting customer payments and distributing funds to sellers, contractors, or service providers.

Keeps your assistant from:

Paying sellers from mutable order totals with no ledger
Refunds and disputes debiting the wrong party or balance
Duplicate transfers or payouts after request and event retries

View as markdown

License: Apache-2.0
Version: 1.0.0
Updated: 2026-08-25