# TCN payments execution plan

## Purpose
Ordered execution plan for getting from current Ballbox native Mercado Pago support to real TCN machine payments.

## Step 1. Finish provider-layer proof
- Goal: prove Ballbox native Mercado Pago flow works end to end without TCN hardware.
- Inputs:
  - `docs/implemented-payments.md`
  - `docs/mercadopago-webhook-replay-notes-2026-04-23.md`
- Tasks:
  - validate public webhook reachability for `/notification/mercadopago`
  - run one real approved payment
  - confirm local `PaymentSession` persistence in `/admin/payments`
  - document exact payload and public URL evidence
- Exit criterion:
  - one real approved payment persists locally through webhook flow

## Step 2. Ask TCN the machine-contract questions
- Goal: close the remaining machine-side unknowns before coding the adapter.
- Inputs:
  - `docs/tcn-payments-integration-plan.md`
  - `docs/tcn-payments-open-questions.md`
  - `test-results/tcn-payment-protocol/findings-2026-04-23.md`
- Tasks:
  - send the question list to the TCN sales contact
  - ask them to confirm with engineers
  - capture answers in repo docs
- Exit criterion:
  - `CodeUrl` meaning and payment-success handshake are confirmed

## Step 3. Freeze Ballbox-TCN contract
- Goal: convert answers into a concrete adapter spec.
- Inputs:
  - `docs/tcn-payments-integration-plan.md`
  - answers captured from Step 2
- Tasks:
  - define request/response schema for TCN `8000`
  - define success/failure callback or polling behavior
  - define duplicate/idempotency behavior for repeated `TradeNo`
  - define machine-id mapping rules
- Exit criterion:
  - implementation spec is precise enough to code without guesswork

## Step 4. Implement adapter layer
- Goal: add the TCN-facing Ballbox endpoints over existing Mercado Pago primitives.
- Inputs:
  - concrete contract spec from Step 3
- Tasks:
  - add machine-facing endpoint(s)
  - map TCN requests to Ballbox/Mercado Pago order creation
  - map approved-payment state back into TCN success flow
  - persist any extra machine correlation fields needed
- Exit criterion:
  - local/manual adapter flow works without real machine hardware

## Step 5. Hardware validation when machines arrive
- Goal: verify actual stock TCN machine behavior.
- Tasks:
  - test real QR render on machine screen
  - test payment approval -> vend path
  - capture timing, retries, and failure cases
- Exit criterion:
  - one real vend succeeds through Ballbox-backed payment flow

## Step 6. Only then revisit payout automation
- Goal: avoid solving club payout distribution before the machine path is stable.
- Current default:
  - scheduled manual settlements / bookkeeping
- Related docs:
  - `docs/payments-club-settlement-strategy.md`