# Club settlement strategy

## Decision
- Use scheduled settlements and manual bookkeeping for now.
- Do not force Mercado Pago split payments into the current vending QR flow.
- Treat Mercado Pago native split as a future option, not the default operating model.

## Why this is the default
- Current Ballbox payments flow is QR/order-based at `/v1/orders`.
- Mercado Pago split docs point to marketplace / checkout flows, OAuth, and seller onboarding.
- That is a poor fit for a small pilot set of clubs and adds operational drag before the machine flow is stable.
- For the current stage, speed and correctness matter more than perfect payout automation.

## Current operating model
- Each vending machine belongs to one club/venue or tenant contract.
- Current TCN machine payment truth is documented in `docs/tcn-machine-reality-2026-05-26.html`.
- Today the real machine payment path is external-device based, such as EasyCoin, rather than Ballbox-controlled machine-native Mercado Pago.
- Settlement strategy still matters whenever Ballbox is the economic collector, even if the physical machine payment rail is mediated by third parties.
- Ballbox records gross sales as it already does where Ballbox has the data and commercial responsibility to do so.
- Club share is tracked off-platform for now.
- Payouts are settled on a fixed cadence:
  - weekly if volume is active
  - monthly if volume is low
- Manual bookkeeping is acceptable for the current early machine stage.

## Minimal bookkeeping fields
Keep one settlement record per club per period.

Recommended fields:
- clubId
- venueId
- vendingMachineId
- periodStart
- periodEnd
- grossSalesMinor
- refundsMinor
- adjustmentsMinor
- clubShareBps
- clubShareMinor
- payoutMethod
- payoutReference
- paidAt
- notes
- approvedBy

Recommended rules:
- store percentages as basis points, not floats
- round once, at settlement time
- keep refunds and adjustments explicit
- never let manual edits overwrite raw sales totals

## Future option if we later automate

### Mercado Pago native split
Best if Ballbox later changes the buyer flow to a supported Mercado Pago checkout path.

Pros:
- native platform split
- less manual payout work
- one provider for collection and distribution

Cons:
- current QR vending flow does not map cleanly
- likely needs OAuth / seller onboarding
- adds commercial-team dependency
- more support burden around account linking, disputes, and credential rotation

Fit:
- only if we replatform the buyer payment flow to something MP split supports

## Decision triggers to revisit automation
Re-open automation when one or more is true:
- more than 5 clubs need payouts
- manual settlement becomes error-prone
- payout timing becomes a sales blocker
- club trust requires automated reconciliation
- a future buyer flow changes to a checkout model MP split actually supports

## Recommendation
- Keep manual scheduled settlements whenever Ballbox is the collector.
- Do not build settlement automation for machine setups where Ballbox is not the collector.
- Build a clean settlement ledger and export path first.
- Revisit automated payout tooling only after machine operations are stable and the club count justifies it.