# Payments + machine rollout RFC

## Status
- Proposed operating plan for the first vending rollout.
- Use this as the master document for payment ownership modes, TCN integration, onboarding, and rollout sequencing.

## Decision summary
- Use one Ballbox-controlled technical flow for all vending machines.
- Support two payment-owner modes in that flow:
  - `BALLBOX`: Ballbox owns the Mercado Pago account that collects funds.
  - `TENANT`: the client/tenant owns the Mercado Pago account that collects funds.
- Default first rollout:
  - 3 club machines use `BALLBOX` collection.
  - 2 Adidas rental machines use `TENANT` collection.
- For `BALLBOX` collection, club revenue share is handled by informal/manual settlement at first.
- Do not block rollout on Mercado Pago native split or marketplace approval.
- Keep future split automation as an optional later track, not a prerequisite.

## Why this is the right first plan
- The immediate risk is not payout automation. The immediate risk is getting the machine payment path working end to end.
- TCN machine integration and Mercado Pago webhook persistence are still the highest-risk technical pieces.
- The first wave is small: 5 machines total.
- Manual settlement is acceptable for the 3 Ballbox-collected club machines.
- Adidas-style rental machines need easy setup more than Ballbox ownership of the funds.
- Running all machines through Ballbox keeps one integration surface, one webhook surface, and one observability path.

## Scope
### In scope
- TCN machine payment adapter
- Mercado Pago provider integration through Ballbox
- machine-level payment-owner mode selection
- Ballbox-collected club machines
- tenant-collected Adidas/client machines
- webhook handling through Ballbox
- manual settlement guidance for Ballbox-collected club machines
- onboarding steps that include non-code work

### Out of scope for this phase
- Mercado Pago marketplace/split as a requirement for launch
- fully automated club settlements
- self-serve onboarding for tenants/clubs
- long-term tenant MP support beyond guided setup

## Operating modes

### Mode A: `BALLBOX`
Use for the first 3 club machines.

Flow:
1. machine belongs to a club/venue
2. Ballbox creates the Mercado Pago order with Ballbox credentials
3. buyer pays by scanning the QR shown by the machine
4. Mercado Pago notifies Ballbox webhook
5. Ballbox fetches order details, verifies approval, persists payment
6. Ballbox later settles the club share manually

Properties:
- simplest first rollout
- Ballbox controls setup and debugging
- informal manual settlement is enough at this stage

### Mode B: `TENANT`
Use for the first 2 Adidas rental machines.

Flow:
1. machine belongs to a client/tenant contract
2. Ballbox creates the Mercado Pago order using tenant credentials/config
3. buyer pays by scanning the QR shown by the machine
4. Mercado Pago notifies the same Ballbox webhook endpoint
5. Ballbox fetches order details with the tenant-specific credentials, verifies approval, persists payment
6. tenant owns funds; Ballbox is not doing revenue-share settlement for those payments

Properties:
- Ballbox still owns the technical integration path
- tenant owns the collecting account
- Ballbox should provide guided setup, not heavy day-to-day support

## Why tenant-direct collection should still run through Ballbox
If Adidas/client collection is done outside Ballbox, Ballbox loses:
- unified TCN adapter behavior
- unified webhook and persistence behavior
- centralized debugging for payment-approved-but-no-vend cases
- shared analytics/reporting across machines
- cleaner future migration paths

The better boundary is:
- Ballbox owns the payment orchestration path
- tenant owns the payment account

## Architecture direction

### Core rule
Payment ownership should be resolved per machine or per contract, not globally.

### Required model concept
Each machine should resolve to something like:
- `paymentOwnerMode = BALLBOX | TENANT`
- payment config reference for Mercado Pago
- vending machine identity
- owning club/venue or tenant/customer relationship

### Provider-layer implication
Ballbox needs to choose the right Mercado Pago credentials/config before creating the order and before fetching webhook-triggered order details.

### Webhook implication
Keep one Ballbox webhook endpoint:
- `/notification/mercadopago`

But Ballbox must be able to determine which payment config applies when an event arrives.
That likely means preserving enough correlation to map:
- provider order / external reference -> vending machine -> payment owner mode -> MP config

## TCN integration direction
- TCN remains the machine-facing protocol.
- The machine should render the buyer-facing QR.
- Ballbox should implement the TCN payment adapter over the native Mercado Pago provider layer.
- The Ballbox admin QR page remains a test/debug harness, not the production machine UX.

Related docs:
- `docs/tcn-payments-integration-plan.md`
- `docs/tcn-payments-open-questions.md`
- `docs/tcn-payments-execution-plan.md`

## Rollout phases

### Phase 0. Provider proof
Goal:
- prove Ballbox native Mercado Pago order + webhook persistence works publicly

Output:
- one real approved payment persisted locally

Related work:
- `OPS-1`
- `docs/mercadopago-webhook-replay-notes-2026-04-23.md`

### Phase 1. TCN contract closure
Goal:
- confirm TCN `CodeUrl` and approval/dispense handshake details with sales/engineering

Output:
- precise adapter contract

Related work:
- `PAY-3`
- `docs/tcn-payments-open-questions.md`

### Phase 2. Single technical path with two payment-owner modes
Goal:
- support the same machine flow for both Ballbox-collected and tenant-collected machines

Output:
- machine-level payment owner resolution
- machine-facing TCN adapter over provider layer
- webhook handling that can resolve the correct config

### Phase 3. Guided onboarding for first five machines
Goal:
- launch 3 club machines and 2 Adidas rental machines

Outputs:
- 3 machines on `BALLBOX`
- 2 machines on `TENANT`
- setup checklist followed per machine
- real payment test per machine/account context

### Phase 4. Informal settlement ops for Ballbox-collected clubs
Goal:
- settle club share simply without blocking rollout

Output:
- lightweight manual ledger/export/notes process

### Phase 5. Re-evaluate automation later
Goal:
- only after machine flow is stable, volume increases, or settlement pain becomes real

Possible future paths:
- better internal settlement tooling
- Mercado Pago split / marketplace if it fits the later buyer flow

## Onboarding plan

### Shared machine onboarding
For every machine:
1. identify machine owner mode: `BALLBOX` or `TENANT`
2. map machine to club/venue or tenant contract
3. map machine identifier between TCN and Ballbox
4. confirm product/pricing setup
5. confirm public webhook reachability from Ballbox
6. run one real payment test
7. confirm approval persistence and vend outcome once hardware exists

### Club-machine onboarding (`BALLBOX`)
Needed now for the first 3 machines:
- confirm machine belongs to one club/venue
- confirm commercial revenue-share terms outside code
- confirm Ballbox account is the collecting account
- note settlement percentage/rule outside the provider path
- after launch, settle informally on a fixed cadence

### Adidas/client onboarding (`TENANT`)
Needed now for the first 2 machines:
- confirm they want to collect in their own Mercado Pago account
- guide them through MP setup only enough to make the machine flow work
- confirm they configure Ballbox webhook endpoint in their MP account if required by the final provider setup
- confirm any required token/POS/external POS values
- run one real payment test with their account
- do not promise heavy ongoing support for their Mercado Pago operations

## Operational expectations
- Manual settlement is acceptable for Ballbox-collected club machines in the first wave.
- For tenant-collected machines, Ballbox is facilitating setup, not owning their payout operations.
- No promise exists that clubs must collect directly in their own account.
- Clubs mainly care about net outcome and avoiding extra invoicing burden, not about ownership of the payment rails themselves.

## Risks
### Technical
- TCN approval/dispense handshake still needs confirmation
- tenant-specific webhook/config resolution may require extra correlation fields
- real webhook validation is not fully closed yet

### Operational
- guided Adidas setup may still stall on account/POS/webhook details
- manual club settlements can become messy if volume rises fast
- support boundaries for tenant-owned MP accounts must stay explicit

## Non-goals to enforce
- do not build split-marketplace complexity into the first machine rollout
- do not treat per-club direct collection as the universal default
- do not overbuild settlement tooling before real machine payments work

## Success criteria
- one Ballbox-collected machine completes payment flow end to end
- one tenant-collected machine completes payment flow end to end
- Ballbox persists approved payments for both owner modes
- TCN machine-facing contract is documented and implemented without guessing
- first five machines have an onboarding checklist that can be repeated

## Related docs
- `PLAN.md`
- `docs/implemented-payments.md`
- `docs/tcn-payments-integration-plan.md`
- `docs/tcn-payments-open-questions.md`
- `docs/tcn-payments-execution-plan.md`
- `docs/payments-club-settlement-strategy.md`
- `docs/mercadopago-webhook-replay-notes-2026-04-23.md`