/mnt/rpi/tcn-machine-onboarding/handoff-for-agent.md:185:- If third-party payment exists, how does the machine know when to vend?
/mnt/rpi/tcn-machine-onboarding/handoff-for-agent.md:202:  - `rg -n -i "payment|slot|commodity|remote|advertis|machine management|delivery|refund|inventory|price" /mnt/rpi/tcn-machine-onboarding/docs/*.txt`
/home/sebas/work/projects/ballbox/docs/domain-model-target.md:4:- Define the final Ballbox ownership model across `network`, `payments`, `tvs`, `sports`, and `players`.
/home/sebas/work/projects/ballbox/docs/domain-model-target.md:39:  - optional future extraction if approvals/webhooks need their own lifecycle
/home/sebas/work/projects/ballbox/docs/implemented-host-app.md:13:  - `/admin/payments`
/home/sebas/work/projects/ballbox/docs/implemented-host-app.md:22:- Ballbox owns native MercadoPago QR order creation at `/api/integrations/payments/orders` and native webhook intake at `/notification/mercadopago`.
/home/sebas/work/projects/ballbox/docs/implemented-host-app.md:23:- Native payment persistence validates canonical `payment-vm_{vendingMachineId}-txn_{machineTxnId}` references before writing local approved sessions.
/home/sebas/work/projects/ballbox/docs/implemented-host-app.md:24:- Ballbox exposes admin payments operations under `/api/admin/payments/*`.
/home/sebas/work/projects/ballbox/docs/implemented-host-app.md:26:- Route JSON/envelope helper boundaries now live in shared `lib/http/*-route-helpers.ts` modules (network, payments, players, sports) instead of route-local helper files under `app/api`.
/home/sebas/work/projects/ballbox/docs/implemented-host-app.md:50:- Browser e2e currently covers TVs offline runtime, active admin navigation, mobile smoke for `/admin/network` and `/admin/tvs`, network CRUD, payments CRUD/reconciliation smoke, players CRUD, and sports CRUD.
/home/sebas/work/projects/ballbox/docs/coaches-opportunity-brief.md:9:- Ballbox today already has host app, admin, network, TVs, payments, players, and a sports foundation.
/home/sebas/work/projects/ballbox/docs/coaches-opportunity-brief.md:56:  - focuses on one recurring operational loop instead of trying to solve scheduling, CRM, payments, and growth all at once
/home/sebas/work/projects/ballbox/docs/coach-availability-rfc.md:45:- Booking writes or payment flow.
/home/sebas/work/projects/ballbox/docs/coach-availability-rfc.md:196:- Current UI opens on a dashboard with per-club metrics plus a strip of days with booked classes, then shows affiliation, assigned sede when present, editable weekly availability inside allowed venue/club hours, reusable sales packages, and a Mercado Pago placeholder field inside `Mi Perfil`. A third `Alumnos` section now handles the student roster, contacts, and manually occupied slots.
/home/sebas/work/projects/ballbox/docs/coach-availability-rfc.md:206:- Coaches can also save a Mercado Pago alias/email placeholder for future payout wiring.
/home/sebas/work/projects/ballbox/docs/payments-machine-implementation-rfc.md:5:- Builds on `docs/payments-machine-rollout-rfc.md`.
/home/sebas/work/projects/ballbox/docs/payments-machine-implementation-rfc.md:8:Implement one machine-payment flow in Ballbox that:
/home/sebas/work/projects/ballbox/docs/payments-machine-implementation-rfc.md:10:- creates Mercado Pago QR orders
/home/sebas/work/projects/ballbox/docs/payments-machine-implementation-rfc.md:11:- persists approved payments through the Ballbox webhook
/home/sebas/work/projects/ballbox/docs/payments-machine-implementation-rfc.md:12:- supports two payment-owner modes without forking the stack:
/home/sebas/work/projects/ballbox/docs/payments-machine-implementation-rfc.md:24:- order create route: `app/api/integrations/payments/orders/route.ts`
/home/sebas/work/projects/ballbox/docs/payments-machine-implementation-rfc.md:25:- webhook intake: `app/notification/mercadopago/route.ts`
/home/sebas/work/projects/ballbox/docs/payments-machine-implementation-rfc.md:26:- provider helper: `lib/payments-mercadopago.ts`
/home/sebas/work/projects/ballbox/docs/payments-machine-implementation-rfc.md:27:- payment persistence + correlation: `lib/payments.ts`
/home/sebas/work/projects/ballbox/docs/payments-machine-implementation-rfc.md:28:- payment contracts: `lib/contracts/payments.ts`
/home/sebas/work/projects/ballbox/docs/payments-machine-implementation-rfc.md:32:- webhook fetch path currently assumes one Mercado Pago config
/home/sebas/work/projects/ballbox/docs/payments-machine-implementation-rfc.md:39:- which payment-owner mode applies to this machine/request/order
/home/sebas/work/projects/ballbox/docs/payments-machine-implementation-rfc.md:40:- which Mercado Pago config should be used
/home/sebas/work/projects/ballbox/docs/payments-machine-implementation-rfc.md:43:- `lib/payments-mercadopago-config.ts`
/home/sebas/work/projects/ballbox/docs/payments-machine-implementation-rfc.md:48:- return a normalized config object used by both order-create and webhook-fetch flows
/home/sebas/work/projects/ballbox/docs/payments-machine-implementation-rfc.md:58:  webhookSecret: string | null;
/home/sebas/work/projects/ballbox/docs/payments-machine-implementation-rfc.md:64:## 2. Resolve payment owner per machine
/home/sebas/work/projects/ballbox/docs/payments-machine-implementation-rfc.md:68:- add machine-level payment ownership fields to the Ballbox data model
/home/sebas/work/projects/ballbox/docs/payments-machine-implementation-rfc.md:72:- `paymentOwnerMode`
/home/sebas/work/projects/ballbox/docs/payments-machine-implementation-rfc.md:73:- `paymentOwnerKey`
/home/sebas/work/projects/ballbox/docs/payments-machine-implementation-rfc.md:74:- optional override `paymentExternalPosId`
/home/sebas/work/projects/ballbox/docs/payments-machine-implementation-rfc.md:77:- `paymentOwnerMode`: `BALLBOX` or `TENANT`
/home/sebas/work/projects/ballbox/docs/payments-machine-implementation-rfc.md:78:- `paymentOwnerKey`: resolver key for the MP config to use
/home/sebas/work/projects/ballbox/docs/payments-machine-implementation-rfc.md:79:- `paymentExternalPosId`: optional machine-specific override when not using the owner default POS
/home/sebas/work/projects/ballbox/docs/payments-machine-implementation-rfc.md:89:- `payment-vm_{vendingMachineId}-txn_{machineTxnId}`
/home/sebas/work/projects/ballbox/docs/payments-machine-implementation-rfc.md:92:But add enough persistence so webhook-triggered fetch can derive config without guessing.
/home/sebas/work/projects/ballbox/docs/payments-machine-implementation-rfc.md:94:Recommended minimum persisted fields on payment/session side:
/home/sebas/work/projects/ballbox/docs/payments-machine-implementation-rfc.md:98:- `paymentOwnerMode`
/home/sebas/work/projects/ballbox/docs/payments-machine-implementation-rfc.md:99:- `paymentOwnerKey`
/home/sebas/work/projects/ballbox/docs/payments-machine-implementation-rfc.md:101:If `PaymentSession` should remain approved-only and lean, add a lightweight pre-approval payment operation record instead.
/home/sebas/work/projects/ballbox/docs/payments-machine-implementation-rfc.md:103:## 4. Introduce a pre-approval payment operation record
/home/sebas/work/projects/ballbox/docs/payments-machine-implementation-rfc.md:105:- webhook can arrive before a final approved `PaymentSession` exists
/home/sebas/work/projects/ballbox/docs/payments-machine-implementation-rfc.md:109:- add a lightweight table for initiated machine payments
/home/sebas/work/projects/ballbox/docs/payments-machine-implementation-rfc.md:121:- `paymentOwnerMode`
/home/sebas/work/projects/ballbox/docs/payments-machine-implementation-rfc.md:122:- `paymentOwnerKey`
/home/sebas/work/projects/ballbox/docs/payments-machine-implementation-rfc.md:130:- webhook can resolve order id -> `PaymentOperation` -> correct MP config
/home/sebas/work/projects/ballbox/docs/payments-machine-implementation-rfc.md:149:- `lib/payments-machine-flow.ts`
/home/sebas/work/projects/ballbox/docs/payments-machine-implementation-rfc.md:154:- create or reuse payment operation row
/home/sebas/work/projects/ballbox/docs/payments-machine-implementation-rfc.md:155:- call Mercado Pago order create
/home/sebas/work/projects/ballbox/docs/payments-machine-implementation-rfc.md:173:## 7. TCN route should sit on top of the machine-payment service
/home/sebas/work/projects/ballbox/docs/payments-machine-implementation-rfc.md:176:- TCN route should translate between TCN contract and Ballbox machine-payment service only
/home/sebas/work/projects/ballbox/docs/payments-machine-implementation-rfc.md:179:- `app/api/integrations/tcn/payments/init/route.ts` or similar
/home/sebas/work/projects/ballbox/docs/payments-machine-implementation-rfc.md:184:- call machine-payment service
/home/sebas/work/projects/ballbox/docs/payments-machine-implementation-rfc.md:189:That avoids a separate payment stack for admin testing vs machine runtime.
/home/sebas/work/projects/ballbox/docs/payments-machine-implementation-rfc.md:192:- `/api/integrations/payments/orders` becomes a Ballbox test/operator entrypoint
/home/sebas/work/projects/ballbox/docs/payments-machine-implementation-rfc.md:194:- both converge on one machine-payment service underneath
/home/sebas/work/projects/ballbox/docs/payments-machine-implementation-rfc.md:199:Add machine ownership to `VendingMachine` and payment initiation state to a new `PaymentOperation` table.
/home/sebas/work/projects/ballbox/docs/payments-machine-implementation-rfc.md:203:- webhook correlation becomes reliable
/home/sebas/work/projects/ballbox/docs/payments-machine-implementation-rfc.md:216:1. webhook payload yields `orderId`
/home/sebas/work/projects/ballbox/docs/payments-machine-implementation-rfc.md:218:3. from that row Ballbox gets `paymentOwnerMode` + `paymentOwnerKey`
/home/sebas/work/projects/ballbox/docs/payments-machine-implementation-rfc.md:237:- webhook replays should be no-op once the approval is persisted
/home/sebas/work/projects/ballbox/docs/payments-machine-implementation-rfc.md:248:Add machine-payment service layer.
/home/sebas/work/projects/ballbox/docs/payments-machine-implementation-rfc.md:254:Move `/api/integrations/payments/orders` onto that service.
/home/sebas/work/projects/ballbox/docs/payments-machine-implementation-rfc.md:260:Update webhook route to resolve config from `PaymentOperation` first.
/home/sebas/work/projects/ballbox/docs/payments-machine-implementation-rfc.md:267:- webhook route is idempotent with repeated notifications
/home/sebas/work/projects/ballbox/docs/payments-machine-implementation-rfc.md:276:- `BALLBOX` machine order create -> webhook persist
/home/sebas/work/projects/ballbox/docs/payments-machine-implementation-rfc.md:277:- `TENANT` machine order create -> webhook persist
/home/sebas/work/projects/ballbox/docs/payments-machine-implementation-rfc.md:278:- webhook config resolution by `providerOrderId`
/home/sebas/work/projects/ballbox/docs/payments-machine-implementation-rfc.md:282:- exact TCN payment-success / dispense handshake
/home/sebas/work/projects/ballbox/docs/payments-machine-implementation-rfc.md:283:- whether tenant webhook/POS setup needs any special MP product variation
/home/sebas/work/projects/ballbox/docs/payments-machine-implementation-rfc.md:289:- a shared machine-payment service
/home/sebas/work/projects/ballbox/docs/payments-machine-implementation-rfc.md:295:- `docs/payments-machine-rollout-rfc.md`
/home/sebas/work/projects/ballbox/docs/payments-machine-implementation-rfc.md:296:- `docs/tcn-payments-integration-plan.md`
/home/sebas/work/projects/ballbox/docs/payments-machine-implementation-rfc.md:297:- `docs/tcn-payments-execution-plan.md`
/home/sebas/work/projects/ballbox/docs/payments-machine-implementation-rfc.md:298:- `docs/implemented-payments.md`
/home/sebas/work/projects/ballbox/docs/maintainability-priorities-2026-03.md:15:  - P0.1 fail-closed payments callback auth
/home/sebas/work/projects/ballbox/docs/maintainability-priorities-2026-03.md:19:  - P1.6 first route-helper/envelope standardization pass across `network`, `players`, `sports`, and `payments`
/home/sebas/work/projects/ballbox/docs/maintainability-priorities-2026-03.md:22:  - P0.3 remaining admin clients: `payments`, `tvs`
/home/sebas/work/projects/ballbox/docs/maintainability-priorities-2026-03.md:33:### 1. Fail closed on payments callback auth
/home/sebas/work/projects/ballbox/docs/maintainability-priorities-2026-03.md:36:- Risk: `app/api/integrations/payments/approved/route.ts` can accept writes in a misconfigured environment.
/home/sebas/work/projects/ballbox/docs/maintainability-priorities-2026-03.md:39:  - `app/api/integrations/payments/approved/route.ts`
/home/sebas/work/projects/ballbox/docs/maintainability-priorities-2026-03.md:42:  - It weakens the whole payments integration if env setup drifts.
/home/sebas/work/projects/ballbox/docs/maintainability-priorities-2026-03.md:60:  - Split by domain: `network`, `tvs`, `payments`, `players`, `sports`, `classes`.
/home/sebas/work/projects/ballbox/docs/maintainability-priorities-2026-03.md:80:  - `components/payments-admin-client.tsx`
/home/sebas/work/projects/ballbox/docs/maintainability-priorities-2026-03.md:100:  - apply the same pattern to `payments-admin-client.tsx`
/home/sebas/work/projects/ballbox/docs/maintainability-priorities-2026-03.md:129:  - `components/payments-admin-client.tsx`
/home/sebas/work/projects/ballbox/docs/maintainability-priorities-2026-03.md:149:  - Inconsistent candidates: `app/api/admin/tvs/screens/[screenId]/route.ts`, `app/api/admin/tvs/tv-devices/route.ts`, `app/api/admin/payments/sessions/route.ts`
/home/sebas/work/projects/ballbox/docs/maintainability-priorities-2026-03.md:158:- Follow-on slices shipped: players, sports, and payments route families now use the same helper pattern for JSON parsing plus strict success/error envelopes, including focused invalid-payload contract coverage.
/home/sebas/work/projects/ballbox/docs/maintainability-priorities-2026-03.md:241:  - `app/api/integrations/payments/health/route.ts`
/home/sebas/work/projects/ballbox/docs/maintainability-priorities-2026-03.md:265:### 14. Tighten domain lifecycle modeling in sports and payments
/home/sebas/work/projects/ballbox/docs/maintainability-priorities-2026-03.md:269:  - `lib/payments.ts`
/home/sebas/work/projects/ballbox/docs/maintainability-priorities-2026-03.md:284:1. Fix payments callback auth and add env validation.
/home/sebas/work/projects/ballbox/docs/coaches-wedges-matrix.md:15:| Collections/admin follow-up | Chasing payments and reminders consumes time | Time savings, maybe cashflow | Low | Medium | Medium | Could be too generic and weakly differentiated |
/home/sebas/work/projects/ballbox/docs/coaches-wedges-matrix.md:35:- If a wedge requires broad CRM/payments/attendance/product surface from day one, narrow it or drop it.
/home/sebas/work/projects/ballbox/docs/next-steps-queue.md:49:  - deep relative helper imports removed from network, players, sports, and payments route handlers
/home/sebas/work/projects/ballbox/docs/next-steps-queue.md:69:  - public webhook smoke against the native MercadoPago webhook path
/home/sebas/work/projects/ballbox/docs/next-steps-queue.md:70:  - real payment persisted as approved in `/admin/payments`
/home/sebas/work/projects/ballbox/docs/next-steps-queue.md:72:- Progress (2026-04-14): payments migration to host app started in one feature branch; health/sessions now expose internal MercadoPago mode, Ballbox ships `/notification/mercadopago` intake with order fetch verification, and native order creation now exists at `/api/integrations/payments/orders`.
/home/sebas/work/projects/ballbox/docs/next-steps-queue.md:73:- Progress (2026-04-19): PAY-2 cleanup removed bridge-oriented operational status from host-app health/docs; OPS-1 is now focused on validating the native MercadoPago order-create + webhook-persist path only.
/home/sebas/work/projects/ballbox/docs/next-steps-queue.md:74:- Progress (2026-04-23): TCN protocol review shows the `additional hardware devices` note is about machine-side QR scanning, while the machine payment flow (`FunCode=8000`) already returns `CodeUrl` for machine-screen QR display. This means the admin QR page should be treated as a provider test harness, and production integration should move to a TCN adapter layer.
/home/sebas/work/projects/ballbox/docs/next-steps-queue.md:75:- Progress (2026-05-05): first production order-create attempt against `https://ballbox.app/api/integrations/payments/orders` failed before buyer payment with Mercado Pago `400 unsupported_properties` because `notification_url` was rejected (`additionalProperties '$.notification_url' not allowed`). Ballbox should stop sending inline `notification_url` for this account/API surface and rely on the existing account-level Mercado Pago webhook configuration before rerunning the real-payment check.
/home/sebas/work/projects/ballbox/docs/next-steps-queue.md:76:- Closure (2026-05-13): a real approved payment now persists locally and is visible in `/admin/payments`. Mercado Pago webhook noise from `topic_merchant_order_wh` remains intentionally ignored. Closure required two Ballbox compatibility fixes for live provider payloads: product id fallback from `items[0].external_code` and robust parsing of `total_amount` when Mercado Pago returns a string.
/home/sebas/work/projects/ballbox/docs/next-steps-queue.md:144:### PAY-2 Full payments migration into Ballbox host app
/home/sebas/work/projects/ballbox/docs/next-steps-queue.md:149:  - native MercadoPago webhook + QR order lifecycle is now owned in Ballbox routes/lib
/home/sebas/work/projects/ballbox/docs/next-steps-queue.md:153:  - `/notification/mercadopago`
/home/sebas/work/projects/ballbox/docs/next-steps-queue.md:154:  - `/api/integrations/payments/orders`
/home/sebas/work/projects/ballbox/docs/next-steps-queue.md:155:  - `app/api/integrations/payments/health/route.ts`
/home/sebas/work/projects/ballbox/docs/next-steps-queue.md:156:  - `app/api/integrations/payments/sessions/route.ts`
/home/sebas/work/projects/ballbox/docs/next-steps-queue.md:157:  - `docs/implemented-payments.md`
/home/sebas/work/projects/ballbox/docs/next-steps-queue.md:158:- Expected payoff: one-repo payments ownership, simpler operations, faster debugging
/home/sebas/work/projects/ballbox/docs/next-steps-queue.md:165:  - define the Ballbox machine-facing adapter for TCN payment init (`FunCode=8000`) over the existing MercadoPago order-create route
/home/sebas/work/projects/ballbox/docs/next-steps-queue.md:166:  - map TCN `MachineID`, `TradeNo`, `SlotNo`, `Price`, `NotityUrl`, and response `CodeUrl` to Ballbox-native payment fields
/home/sebas/work/projects/ballbox/docs/next-steps-queue.md:167:  - define the payment-success handshake back to TCN so approved payments can unlock dispense
/home/sebas/work/projects/ballbox/docs/next-steps-queue.md:168:  - support one shared machine payment flow with two payment-owner modes:
/home/sebas/work/projects/ballbox/docs/next-steps-queue.md:171:  - keep `/admin/payments` positioned as an operator test/debug harness rather than the production vending UX
/home/sebas/work/projects/ballbox/docs/next-steps-queue.md:174:  - TCN protocol evidence is documented in `docs/tcn-payments-integration-plan.md`
/home/sebas/work/projects/ballbox/docs/next-steps-queue.md:175:  - master rollout direction is documented in `docs/payments-machine-rollout-rfc.md`
/home/sebas/work/projects/ballbox/docs/next-steps-queue.md:176:  - technical implementation shape is documented in `docs/payments-machine-implementation-rfc.md`
/home/sebas/work/projects/ballbox/docs/next-steps-queue.md:183:### PAY-4 Mercado Pago native split for club revenue share
/home/sebas/work/projects/ballbox/docs/next-steps-queue.md:189:  - document Mercado Pago native split as the only future automation path under consideration for club payouts
/home/sebas/work/projects/ballbox/docs/next-steps-queue.md:193:  - Ballbox currently runs QR vending payments through the native Mercado Pago order/webhook flow, so split automation is a separate future decision
/home/sebas/work/projects/ballbox/docs/next-steps-queue.md:195:  - keep this behind real-world payments validation first (`OPS-1`) and machine-facing TCN adapter definition (`PAY-3`)
/home/sebas/work/projects/ballbox/docs/next-steps-queue.md:196:- Expected payoff: a clear path from manual settlements to a future Mercado Pago split if the machine flow and business volume justify it
/home/sebas/work/projects/ballbox/docs/tcn-payments-open-questions.md:1:# TCN payments open questions
/home/sebas/work/projects/ballbox/docs/tcn-payments-open-questions.md:10:   - Mercado Pago deep link
/home/sebas/work/projects/ballbox/docs/tcn-payments-open-questions.md:12:2. After payment approval, how does the machine learn that the vend can proceed?
/home/sebas/work/projects/ballbox/docs/tcn-payments-open-questions.md:18:4. What is the exact payload shape expected for the payment-success notify/result message?
/home/sebas/work/projects/ballbox/docs/tcn-payments-open-questions.md:25:7. Are there any timeout / expiry expectations for the QR payment window from the machine side?
/home/sebas/work/projects/ballbox/docs/tcn-payments-open-questions.md:26:8. What should Ballbox return to the machine when payment creation fails or times out?
/home/sebas/work/projects/ballbox/docs/tcn-payments-open-questions.md:28:10. Are there additional payment-related endpoints beyond `8000` required for a production dispense flow?
/home/sebas/work/projects/ballbox/docs/tcn-payments-open-questions.md:30:## Questions for Mercado Pago / internal validation
/home/sebas/work/projects/ballbox/docs/tcn-payments-open-questions.md:32:2. Does current Ballbox order creation produce the same QR/deeplink payload shape expected by a buyer using Mercado Pago app?
/home/sebas/work/projects/ballbox/docs/tcn-payments-open-questions.md:33:3. Is the current webhook exposure stable enough for real public notifications on the production-like Ballbox URL?
/home/sebas/work/projects/ballbox/docs/tcn-payments-open-questions.md:37:- A resolved field-mapping note added back into `docs/tcn-payments-integration-plan.md`
/home/sebas/work/projects/ballbox/docs/coaches-interview-script.md:44:- User speaks in vague preferences, not real recurring events.
/home/sebas/work/projects/ballbox/docs/coaches-solution-thesis.md:36:- Not assuming the first win is payments
/home/sebas/work/projects/ballbox/docs/implemented-sports.md:14:- `/coaches/settings` now opens on a coach workspace split into `Calendar`, `Performance`, `Alumnos`, and `Horarios y Clases`: calendar shows the current week in an hour-by-hour class matrix, groups simultaneous reservations into one individual or group class, surfaces each student's basic profile data (name, sexo, edad, categoria), marks which reservations are paid vs pending, and starts with a large `Agregar clase` CTA that takes the coach into `Alumnos`; `Performance` shows club-level results plus weekly earnings and student consistency rows, while `Horarios y Clases` auto-saves club selection, availability, packages, and Mercado Pago setup without manual save buttons and no longer shows the club's court-fee pricing to the coach. Pending autosave writes are also flushed if the coach leaves the page before the debounce finishes.
/home/sebas/work/projects/ballbox/docs/implemented-sports.md:32:- `Coach` now also stores a Mercado Pago placeholder handle and reusable `CoachSalesPackage` rows for price, duration, class type, and max-student setup.
/home/sebas/work/projects/ballbox/docs/implemented-sports.md:90:- The selected slot is still a local lead preference, not a confirmed reservation; ATC availability can move between render and submit, and Ballbox rejects stale selections when revalidation no longer finds the slot.
/home/sebas/work/projects/ballbox/docs/payments-machine-rollout-rfc.md:5:- Use this as the master document for payment ownership modes, TCN integration, onboarding, and rollout sequencing.
/home/sebas/work/projects/ballbox/docs/payments-machine-rollout-rfc.md:9:- Support two payment-owner modes in that flow:
/home/sebas/work/projects/ballbox/docs/payments-machine-rollout-rfc.md:10:  - `BALLBOX`: Ballbox owns the Mercado Pago account that collects funds.
/home/sebas/work/projects/ballbox/docs/payments-machine-rollout-rfc.md:11:  - `TENANT`: the client/tenant owns the Mercado Pago account that collects funds.
/home/sebas/work/projects/ballbox/docs/payments-machine-rollout-rfc.md:16:- Do not block rollout on Mercado Pago native split or marketplace approval.
/home/sebas/work/projects/ballbox/docs/payments-machine-rollout-rfc.md:20:- The immediate risk is not payout automation. The immediate risk is getting the machine payment path working end to end.
/home/sebas/work/projects/ballbox/docs/payments-machine-rollout-rfc.md:21:- TCN machine integration and Mercado Pago webhook persistence are still the highest-risk technical pieces.
/home/sebas/work/projects/ballbox/docs/payments-machine-rollout-rfc.md:25:- Running all machines through Ballbox keeps one integration surface, one webhook surface, and one observability path.
/home/sebas/work/projects/ballbox/docs/payments-machine-rollout-rfc.md:29:- TCN machine payment adapter
/home/sebas/work/projects/ballbox/docs/payments-machine-rollout-rfc.md:30:- Mercado Pago provider integration through Ballbox
/home/sebas/work/projects/ballbox/docs/payments-machine-rollout-rfc.md:31:- machine-level payment-owner mode selection
/home/sebas/work/projects/ballbox/docs/payments-machine-rollout-rfc.md:34:- webhook handling through Ballbox
/home/sebas/work/projects/ballbox/docs/payments-machine-rollout-rfc.md:39:- Mercado Pago marketplace/split as a requirement for launch
/home/sebas/work/projects/ballbox/docs/payments-machine-rollout-rfc.md:51:2. Ballbox creates the Mercado Pago order with Ballbox credentials
/home/sebas/work/projects/ballbox/docs/payments-machine-rollout-rfc.md:53:4. Mercado Pago notifies Ballbox webhook
/home/sebas/work/projects/ballbox/docs/payments-machine-rollout-rfc.md:54:5. Ballbox fetches order details, verifies approval, persists payment
/home/sebas/work/projects/ballbox/docs/payments-machine-rollout-rfc.md:67:2. Ballbox creates the Mercado Pago order using tenant credentials/config
/home/sebas/work/projects/ballbox/docs/payments-machine-rollout-rfc.md:69:4. Mercado Pago notifies the same Ballbox webhook endpoint
/home/sebas/work/projects/ballbox/docs/payments-machine-rollout-rfc.md:70:5. Ballbox fetches order details with the tenant-specific credentials, verifies approval, persists payment
/home/sebas/work/projects/ballbox/docs/payments-machine-rollout-rfc.md:71:6. tenant owns funds; Ballbox is not doing revenue-share settlement for those payments
/home/sebas/work/projects/ballbox/docs/payments-machine-rollout-rfc.md:81:- unified webhook and persistence behavior
/home/sebas/work/projects/ballbox/docs/payments-machine-rollout-rfc.md:82:- centralized debugging for payment-approved-but-no-vend cases
/home/sebas/work/projects/ballbox/docs/payments-machine-rollout-rfc.md:87:- Ballbox owns the payment orchestration path
/home/sebas/work/projects/ballbox/docs/payments-machine-rollout-rfc.md:88:- tenant owns the payment account
/home/sebas/work/projects/ballbox/docs/payments-machine-rollout-rfc.md:97:- `paymentOwnerMode = BALLBOX | TENANT`
/home/sebas/work/projects/ballbox/docs/payments-machine-rollout-rfc.md:98:- payment config reference for Mercado Pago
/home/sebas/work/projects/ballbox/docs/payments-machine-rollout-rfc.md:103:Ballbox needs to choose the right Mercado Pago credentials/config before creating the order and before fetching webhook-triggered order details.
/home/sebas/work/projects/ballbox/docs/payments-machine-rollout-rfc.md:106:Keep one Ballbox webhook endpoint:
/home/sebas/work/projects/ballbox/docs/payments-machine-rollout-rfc.md:107:- `/notification/mercadopago`
/home/sebas/work/projects/ballbox/docs/payments-machine-rollout-rfc.md:109:But Ballbox must be able to determine which payment config applies when an event arrives.
/home/sebas/work/projects/ballbox/docs/payments-machine-rollout-rfc.md:111:- provider order / external reference -> vending machine -> payment owner mode -> MP config
/home/sebas/work/projects/ballbox/docs/payments-machine-rollout-rfc.md:116:- Ballbox should implement the TCN payment adapter over the native Mercado Pago provider layer.
/home/sebas/work/projects/ballbox/docs/payments-machine-rollout-rfc.md:120:- `docs/tcn-payments-integration-plan.md`
/home/sebas/work/projects/ballbox/docs/payments-machine-rollout-rfc.md:121:- `docs/tcn-payments-open-questions.md`
/home/sebas/work/projects/ballbox/docs/payments-machine-rollout-rfc.md:122:- `docs/tcn-payments-execution-plan.md`
/home/sebas/work/projects/ballbox/docs/payments-machine-rollout-rfc.md:128:- prove Ballbox native Mercado Pago order + webhook persistence works publicly
/home/sebas/work/projects/ballbox/docs/payments-machine-rollout-rfc.md:131:- one real approved payment persisted locally
/home/sebas/work/projects/ballbox/docs/payments-machine-rollout-rfc.md:135:- `docs/mercadopago-webhook-replay-notes-2026-04-23.md`
/home/sebas/work/projects/ballbox/docs/payments-machine-rollout-rfc.md:146:- `docs/tcn-payments-open-questions.md`
/home/sebas/work/projects/ballbox/docs/payments-machine-rollout-rfc.md:148:### Phase 2. Single technical path with two payment-owner modes
/home/sebas/work/projects/ballbox/docs/payments-machine-rollout-rfc.md:153:- machine-level payment owner resolution
/home/sebas/work/projects/ballbox/docs/payments-machine-rollout-rfc.md:155:- webhook handling that can resolve the correct config
/home/sebas/work/projects/ballbox/docs/payments-machine-rollout-rfc.md:165:- real payment test per machine/account context
/home/sebas/work/projects/ballbox/docs/payments-machine-rollout-rfc.md:180:- Mercado Pago split / marketplace if it fits the later buyer flow
/home/sebas/work/projects/ballbox/docs/payments-machine-rollout-rfc.md:190:5. confirm public webhook reachability from Ballbox
/home/sebas/work/projects/ballbox/docs/payments-machine-rollout-rfc.md:191:6. run one real payment test
/home/sebas/work/projects/ballbox/docs/payments-machine-rollout-rfc.md:204:- confirm they want to collect in their own Mercado Pago account
/home/sebas/work/projects/ballbox/docs/payments-machine-rollout-rfc.md:206:- confirm they configure Ballbox webhook endpoint in their MP account if required by the final provider setup
/home/sebas/work/projects/ballbox/docs/payments-machine-rollout-rfc.md:208:- run one real payment test with their account
/home/sebas/work/projects/ballbox/docs/payments-machine-rollout-rfc.md:209:- do not promise heavy ongoing support for their Mercado Pago operations
/home/sebas/work/projects/ballbox/docs/payments-machine-rollout-rfc.md:215:- Clubs mainly care about net outcome and avoiding extra invoicing burden, not about ownership of the payment rails themselves.
/home/sebas/work/projects/ballbox/docs/payments-machine-rollout-rfc.md:220:- tenant-specific webhook/config resolution may require extra correlation fields
/home/sebas/work/projects/ballbox/docs/payments-machine-rollout-rfc.md:221:- real webhook validation is not fully closed yet
/home/sebas/work/projects/ballbox/docs/payments-machine-rollout-rfc.md:224:- guided Adidas setup may still stall on account/POS/webhook details
/home/sebas/work/projects/ballbox/docs/payments-machine-rollout-rfc.md:231:- do not overbuild settlement tooling before real machine payments work
/home/sebas/work/projects/ballbox/docs/payments-machine-rollout-rfc.md:234:- one Ballbox-collected machine completes payment flow end to end
/home/sebas/work/projects/ballbox/docs/payments-machine-rollout-rfc.md:235:- one tenant-collected machine completes payment flow end to end
/home/sebas/work/projects/ballbox/docs/payments-machine-rollout-rfc.md:236:- Ballbox persists approved payments for both owner modes
/home/sebas/work/projects/ballbox/docs/payments-machine-rollout-rfc.md:242:- `docs/implemented-payments.md`
/home/sebas/work/projects/ballbox/docs/payments-machine-rollout-rfc.md:243:- `docs/tcn-payments-integration-plan.md`
/home/sebas/work/projects/ballbox/docs/payments-machine-rollout-rfc.md:244:- `docs/tcn-payments-open-questions.md`
/home/sebas/work/projects/ballbox/docs/payments-machine-rollout-rfc.md:245:- `docs/tcn-payments-execution-plan.md`
/home/sebas/work/projects/ballbox/docs/payments-machine-rollout-rfc.md:246:- `docs/payments-club-settlement-strategy.md`
/home/sebas/work/projects/ballbox/docs/payments-machine-rollout-rfc.md:247:- `docs/mercadopago-webhook-replay-notes-2026-04-23.md`
/home/sebas/work/projects/ballbox/docs/coaches-form-current.md:15:- Detect whether court reservation, payments, club coordination, or growth/admin issues appear often enough to justify follow-up interviews.
/home/sebas/work/projects/ballbox/docs/coaches-form-current.md:119:- Whether scheduling, attendance reminders, payments, court reservation, club friction, or acquisition appear frequently in self-report.
/home/sebas/work/projects/ballbox/docs/tcn-payments-execution-plan.md:1:# TCN payments execution plan
/home/sebas/work/projects/ballbox/docs/tcn-payments-execution-plan.md:4:Ordered execution plan for getting from current Ballbox native Mercado Pago support to real TCN machine payments.
/home/sebas/work/projects/ballbox/docs/tcn-payments-execution-plan.md:7:- Goal: prove Ballbox native Mercado Pago flow works end to end without TCN hardware.
/home/sebas/work/projects/ballbox/docs/tcn-payments-execution-plan.md:9:  - `docs/implemented-payments.md`
/home/sebas/work/projects/ballbox/docs/tcn-payments-execution-plan.md:10:  - `docs/mercadopago-webhook-replay-notes-2026-04-23.md`
/home/sebas/work/projects/ballbox/docs/tcn-payments-execution-plan.md:12:  - validate public webhook reachability for `/notification/mercadopago`
/home/sebas/work/projects/ballbox/docs/tcn-payments-execution-plan.md:13:  - run one real approved payment
/home/sebas/work/projects/ballbox/docs/tcn-payments-execution-plan.md:14:  - confirm local `PaymentSession` persistence in `/admin/payments`
/home/sebas/work/projects/ballbox/docs/tcn-payments-execution-plan.md:17:  - one real approved payment persists locally through webhook flow
/home/sebas/work/projects/ballbox/docs/tcn-payments-execution-plan.md:22:  - `docs/tcn-payments-integration-plan.md`
/home/sebas/work/projects/ballbox/docs/tcn-payments-execution-plan.md:23:  - `docs/tcn-payments-open-questions.md`
/home/sebas/work/projects/ballbox/docs/tcn-payments-execution-plan.md:24:  - `test-results/tcn-payment-protocol/findings-2026-04-23.md`
/home/sebas/work/projects/ballbox/docs/tcn-payments-execution-plan.md:30:  - `CodeUrl` meaning and payment-success handshake are confirmed
/home/sebas/work/projects/ballbox/docs/tcn-payments-execution-plan.md:35:  - `docs/tcn-payments-integration-plan.md`
/home/sebas/work/projects/ballbox/docs/tcn-payments-execution-plan.md:46:- Goal: add the TCN-facing Ballbox endpoints over existing Mercado Pago primitives.
/home/sebas/work/projects/ballbox/docs/tcn-payments-execution-plan.md:51:  - map TCN requests to Ballbox/Mercado Pago order creation
/home/sebas/work/projects/ballbox/docs/tcn-payments-execution-plan.md:52:  - map approved-payment state back into TCN success flow
/home/sebas/work/projects/ballbox/docs/tcn-payments-execution-plan.md:61:  - test payment approval -> vend path
/home/sebas/work/projects/ballbox/docs/tcn-payments-execution-plan.md:64:  - one real vend succeeds through Ballbox-backed payment flow
/home/sebas/work/projects/ballbox/docs/tcn-payments-execution-plan.md:71:  - `docs/payments-club-settlement-strategy.md`
/home/sebas/work/projects/ballbox/docs/atc-integration-discovery.md:132:- no visible webhook/event model for booking changes
/home/sebas/work/projects/ballbox/docs/streetcast-parity.md:6:- Local media cache: covered by screen-scoped browser cache with cached blob playback preference.
/home/sebas/work/projects/ballbox/docs/index.md:33:- `docs/implemented-payments.md`
/home/sebas/work/projects/ballbox/docs/index.md:52:- `docs/payments-machine-rollout-rfc.md`
/home/sebas/work/projects/ballbox/docs/index.md:53:- `docs/payments-machine-implementation-rfc.md`
/home/sebas/work/projects/ballbox/docs/index.md:54:- `docs/tcn-payments-integration-plan.md`
/home/sebas/work/projects/ballbox/docs/index.md:55:- `docs/tcn-payments-open-questions.md`
/home/sebas/work/projects/ballbox/docs/index.md:56:- `docs/tcn-payments-execution-plan.md`
/home/sebas/work/projects/ballbox/docs/index.md:57:- `docs/payments-club-settlement-strategy.md`
/home/sebas/work/projects/ballbox/docs/mercadopago-webhook-replay-notes-2026-04-23.md:1:# Mercado Pago webhook replay notes
/home/sebas/work/projects/ballbox/docs/mercadopago-webhook-replay-notes-2026-04-23.md:6:- Replayed real Ballbox Mercado Pago webhook payloads against `https://ballbox.app/notification/mercadopago`.
/home/sebas/work/projects/ballbox/docs/mercadopago-webhook-replay-notes-2026-04-23.md:13:- Ballbox ignored both because Mercado Pago order fetch returned the orders as expired:
/home/sebas/work/projects/ballbox/docs/mercadopago-webhook-replay-notes-2026-04-23.md:17:- The webhook endpoint is live.
/home/sebas/work/projects/ballbox/docs/mercadopago-webhook-replay-notes-2026-04-23.md:20:- These specific replay ids are no longer useful for persistence validation because the orders expired in Mercado Pago.
/home/sebas/work/projects/ballbox/docs/mercadopago-webhook-replay-notes-2026-04-23.md:24:  - a fresh approved `order.processed` id still valid in Mercado Pago, or
/home/sebas/work/projects/ballbox/docs/mercadopago-webhook-replay-notes-2026-04-23.md:25:  - a real buyer-side payment to create a new approved order.
/home/sebas/work/projects/ballbox/docs/mercadopago-webhook-replay-notes-2026-04-23.md:28:- Keep the webhook path as-is.
/home/sebas/work/projects/ballbox/docs/mercadopago-webhook-replay-notes-2026-04-23.md:29:- When resuming, use a fresh approved order id from a recent live payment or the buyer app flow.
/home/sebas/work/projects/ballbox/docs/mercadopago-webhook-replay-notes-2026-04-23.md:32:- Attempted a new production QR order create against `https://ballbox.app/api/integrations/payments/orders` before the real buyer-payment step.
/home/sebas/work/projects/ballbox/docs/mercadopago-webhook-replay-notes-2026-04-23.md:33:- Result: Ballbox returned provider failure details from Mercado Pago:
/home/sebas/work/projects/ballbox/docs/mercadopago-webhook-replay-notes-2026-04-23.md:39:  - `OPS-1` is blocked before payment approval, not at webhook persistence
/home/sebas/work/projects/ballbox/docs/mercadopago-webhook-replay-notes-2026-04-23.md:42:  - rely on the Mercado Pago account-level webhook configuration already associated with the production setup
/home/sebas/work/projects/ballbox/docs/mercadopago-webhook-replay-notes-2026-04-23.md:43:  - then rerun `OPS-1` with a fresh real payment
/home/sebas/work/projects/ballbox/docs/coaches-icp-segmentation.md:39:- Strong evidence that payment/collections pain dominates over scheduling pain.
/home/sebas/work/projects/ballbox/docs/payments-club-settlement-strategy.md:5:- Do not force Mercado Pago split payments into the current vending QR flow.
/home/sebas/work/projects/ballbox/docs/payments-club-settlement-strategy.md:6:- Treat Mercado Pago native split as a future option, not the default operating model.
/home/sebas/work/projects/ballbox/docs/payments-club-settlement-strategy.md:9:- Current Ballbox payments flow is QR/order-based at `/v1/orders`.
/home/sebas/work/projects/ballbox/docs/payments-club-settlement-strategy.md:10:- Mercado Pago split docs point to marketplace / checkout flows, OAuth, and seller onboarding.
/home/sebas/work/projects/ballbox/docs/payments-club-settlement-strategy.md:16:- The first rollout uses two payment-owner modes documented in `docs/payments-machine-rollout-rfc.md`:
/home/sebas/work/projects/ballbox/docs/payments-club-settlement-strategy.md:18:  - `TENANT`: the tenant/client collects directly in their own Mercado Pago account; no Ballbox settlement is needed for those payments.
/home/sebas/work/projects/ballbox/docs/payments-club-settlement-strategy.md:54:### Mercado Pago native split
/home/sebas/work/projects/ballbox/docs/payments-club-settlement-strategy.md:55:Best if Ballbox later changes the buyer flow to a supported Mercado Pago checkout path.
/home/sebas/work/projects/ballbox/docs/payments-club-settlement-strategy.md:69:- only if we replatform the buyer payment flow to something MP split supports
/home/sebas/work/projects/ballbox/docs/payments-club-settlement-strategy.md:83:- Revisit Mercado Pago native split only after machine payments are stable and the club count justifies it.
/home/sebas/work/projects/ballbox/docs/atc-access-request-checklist.md:17:- Any webhook/event support for booking changes
/home/sebas/work/projects/ballbox/docs/implemented-network.md:28:- `Screen` and `TvDevice` also live in the same shared core and are consumed today by TVs and payments flows.
/home/sebas/work/projects/ballbox/docs/implemented-network.md:33:- Cross-links from TVs/payments back into `/admin/network` are not in place yet.
/home/sebas/work/projects/ballbox/docs/implemented-payments.md:4:- Ballbox owns the admin surface, native MercadoPago webhook intake, and native QR order creation.
/home/sebas/work/projects/ballbox/docs/implemented-payments.md:5:- `/notification/mercadopago` is the first-party MercadoPago QR webhook route that fetches the upstream order, ignores unsupported merchant-order topics, and persists approved orders.
/home/sebas/work/projects/ballbox/docs/implemented-payments.md:6:- `/api/integrations/payments/orders` is the first-party QR order creation route.
/home/sebas/work/projects/ballbox/docs/implemented-payments.md:7:- `/api/integrations/payments/sessions` lists Ballbox-local approved payment records plus native MercadoPago config status.
/home/sebas/work/projects/ballbox/docs/implemented-payments.md:8:- `/admin/payments` now manages local approved payment sessions directly for reconciliation/correction and also generates live MercadoPago QR orders for arbitrary amounts or product-priced orders.
/home/sebas/work/projects/ballbox/docs/implemented-payments.md:9:- The admin QR generator should now be treated as an operator test/debug harness for Mercado Pago and webhook validation, not as the final buyer-facing vending-machine payment UX.
/home/sebas/work/projects/ballbox/docs/implemented-payments.md:10:- The QR generator accepts money values in major units with decimals (for example `15.00` or `1000.00`) and converts them to Mercado Pago minor units before submission.
/home/sebas/work/projects/ballbox/docs/implemented-payments.md:13:- `/api/admin/payments/operations`
/home/sebas/work/projects/ballbox/docs/implemented-payments.md:14:- `/api/admin/payments/sessions`
/home/sebas/work/projects/ballbox/docs/implemented-payments.md:15:- `/api/admin/payments/sessions/[sessionId]`
/home/sebas/work/projects/ballbox/docs/implemented-payments.md:16:- `/api/integrations/payments/health`
/home/sebas/work/projects/ballbox/docs/implemented-payments.md:17:- `/api/integrations/payments/sessions`
/home/sebas/work/projects/ballbox/docs/implemented-payments.md:18:- `/api/integrations/payments/orders`
/home/sebas/work/projects/ballbox/docs/implemented-payments.md:19:- `/notification/mercadopago`
/home/sebas/work/projects/ballbox/docs/implemented-payments.md:22:- Ballbox persists approved payment records as `PaymentSession` rows in Ballbox Postgres.
/home/sebas/work/projects/ballbox/docs/implemented-payments.md:23:- Native MercadoPago webhook intake fetches the upstream order, maps approved orders into the canonical Ballbox payment shape, and persists them locally.
/home/sebas/work/projects/ballbox/docs/implemented-payments.md:28:- Playwright now covers local `/admin/payments` create, edit, and delete flows with deterministic cleanup of E2E `PaymentSession` rows.
/home/sebas/work/projects/ballbox/docs/implemented-payments.md:31:- Ballbox native MercadoPago webhook path is `/notification/mercadopago`.
/home/sebas/work/projects/ballbox/docs/implemented-payments.md:32:- Ballbox native QR order creation path is `/api/integrations/payments/orders`.
/home/sebas/work/projects/ballbox/docs/implemented-payments.md:33:- For the current Ballbox Mercado Pago account/API surface, QR order create relies on the account-level webhook configuration instead of sending inline `notification_url` in the order payload, because Mercado Pago rejects that field on `POST /v1/orders` for this setup.
/home/sebas/work/projects/ballbox/docs/implemented-payments.md:35:- The order route rejects values below Mercado Pago's minimum charge (`15.00 ARS`) before calling the provider.
/home/sebas/work/projects/ballbox/docs/implemented-payments.md:36:- QR webhook persistence now depends on the upstream order fetch plus canonical-reference mapping; merchant-order topic events are ignored.
/home/sebas/work/projects/ballbox/docs/implemented-payments.md:37:- Legacy approved-callback path `/api/integrations/payments/approved` is removed as an operational integration and now returns `410 PAYMENTS_APPROVED_CALLBACK_REMOVED`.
/home/sebas/work/projects/ballbox/docs/implemented-payments.md:38:- Native payment correlation requires canonical `externalReference` values shaped as `payment-vm_{vendingMachineId}-txn_{machineTxnId}`.
/home/sebas/work/projects/ballbox/docs/implemented-payments.md:42:- Host app now owns the native MercadoPago order creation + webhook persistence path inside Ballbox.
/home/sebas/work/projects/ballbox/docs/implemented-payments.md:43:- Real-world validation is now closed: one real public webhook and one real approved payment were persisted and verified in `/admin/payments` on 2026-05-13.
/home/sebas/work/projects/ballbox/docs/implemented-payments.md:46:- First rollout planning now assumes one shared technical flow with two payment-owner modes: `BALLBOX` for club machines Ballbox collects on, and `TENANT` for client-owned collection setups such as Adidas rental machines; see `docs/payments-machine-rollout-rfc.md`.
/home/sebas/work/projects/ballbox/docs/implemented-payments.md:48:- The webhook route is fetch-first: the webhook is just the trigger, and Ballbox verifies the order state by fetching Mercado Pago before persisting.
/home/sebas/work/projects/ballbox/docs/implemented-payments.md:49:- TCN protocol review indicates the `additional hardware devices` warning applies to machine-side QR scanning, while the payment flow (`FunCode=8000`) returns `CodeUrl` for machine-screen QR display; see `docs/tcn-payments-integration-plan.md` and `test-results/tcn-payment-protocol/findings-2026-04-23.md`.
/home/sebas/work/projects/ballbox/docs/implemented-payments.md:50:- Recent replay validation against two older live `ORD...` ids returned `MERCADOPAGO_ORDER_NOT_APPROVED_expired`; see `docs/mercadopago-webhook-replay-notes-2026-04-23.md` when resuming webhook persistence checks.
/home/sebas/work/projects/ballbox/docs/implemented-payments.md:53:- End-to-end payment validation succeeded against Ballbox native MercadoPago webhook configuration.
/home/sebas/work/projects/ballbox/docs/implemented-payments.md:58:  - public HTTPS webhook endpoint `/notification/mercadopago`
/home/sebas/work/projects/ballbox/docs/implemented-payments.md:60:  - a real payment was approved upstream
/home/sebas/work/projects/ballbox/docs/implemented-payments.md:61:  - MercadoPago reached Ballbox webhook publicly
/home/sebas/work/projects/ballbox/docs/implemented-payments.md:62:  - Ballbox fetched order details and recorded the approved payment locally
/home/sebas/work/projects/ballbox/docs/implemented-payments.md:64:  - the session was visible in `/admin/payments`
/home/sebas/work/projects/ballbox/docs/tcn-payments-integration-plan.md:1:# TCN payments integration plan
/home/sebas/work/projects/ballbox/docs/tcn-payments-integration-plan.md:4:- Treat the current `/admin/payments` QR generator as an operator test harness, not the final production payment UX for vending machines.
/home/sebas/work/projects/ballbox/docs/tcn-payments-integration-plan.md:10:- The payment section (`2.1.5 Integral exchange`, `FunCode=8000`) already defines a dynamic payment flow:
/home/sebas/work/projects/ballbox/docs/tcn-payments-integration-plan.md:18:2. TCN machine requests Ballbox payment session using the TCN payment contract.
/home/sebas/work/projects/ballbox/docs/tcn-payments-integration-plan.md:19:3. Ballbox creates a Mercado Pago QR order.
/home/sebas/work/projects/ballbox/docs/tcn-payments-integration-plan.md:20:4. Ballbox maps the Mercado Pago output into the TCN response shape and returns `CodeUrl`.
/home/sebas/work/projects/ballbox/docs/tcn-payments-integration-plan.md:22:6. Buyer scans with Mercado Pago app on phone.
/home/sebas/work/projects/ballbox/docs/tcn-payments-integration-plan.md:23:7. Payment provider notifies Ballbox webhook.
/home/sebas/work/projects/ballbox/docs/tcn-payments-integration-plan.md:24:8. Ballbox validates/persists approved payment.
/home/sebas/work/projects/ballbox/docs/tcn-payments-integration-plan.md:29:- Define a Ballbox route for TCN `8000` payment-init requests.
/home/sebas/work/projects/ballbox/docs/tcn-payments-integration-plan.md:37:- Confirm whether TCN expects raw payment URL, QR payload string, or a specific provider deep link in `CodeUrl`.
/home/sebas/work/projects/ballbox/docs/tcn-payments-integration-plan.md:40:- Map how Ballbox should signal payment success back into the TCN flow.
/home/sebas/work/projects/ballbox/docs/tcn-payments-integration-plan.md:42:- Confirm how TCN links approved payment to dispense using `TradeNo` and/or `SlotNo`.
/home/sebas/work/projects/ballbox/docs/tcn-payments-integration-plan.md:49:- `/admin/payments` remains useful for:
/home/sebas/work/projects/ballbox/docs/tcn-payments-integration-plan.md:50:  - Mercado Pago config checks
/home/sebas/work/projects/ballbox/docs/tcn-payments-integration-plan.md:52:  - webhook validation
/home/sebas/work/projects/ballbox/docs/tcn-payments-integration-plan.md:54:- Do not frame it as the final vending-machine payment UX.
/home/sebas/work/projects/ballbox/docs/tcn-payments-integration-plan.md:58:- Exact success callback / notify shape between Ballbox and TCN after payment approval.
/home/sebas/work/projects/ballbox/docs/tcn-payments-integration-plan.md:59:- Whether machine-side polling (`4000`) participates in payment completion or only app-driven vend/load flows.
/home/sebas/work/projects/ballbox/docs/tcn-payments-integration-plan.md:60:- Whether TCN needs additional payment-status endpoints beyond `8000` for a full dispense flow.
/home/sebas/work/projects/ballbox/docs/tcn-payments-integration-plan.md:64:- Keep Mercado Pago-native Ballbox routes as the provider layer underneath that adapter.
/home/sebas/work/projects/ballbox/docs/tcn-payments-integration-plan.md:67:- `test-results/tcn-payment-protocol/Protocol 2.5V English version.pdf`
/home/sebas/work/projects/ballbox/docs/tcn-payments-integration-plan.md:68:- `test-results/tcn-payment-protocol/findings-2026-04-23.md`

[Showing lines 144-470 of 470 (50.0KB limit). Full output: /tmp/pi-bash-940c7268f6667360.log]


**Inspecting documentation for endpoints**

I need a concise answer along with links to the documentation and specifics on what to send. It might help to scrape the exact endpoints. I could check if the provider uses something like a /v1/orders webhook. I'll quickly inspect the MP docs for references related to order creation and webhooks too. This way, I can gather all the relevant information efficiently!

bash

python - <<'PY'
import requests,re,json
u='https://www.mercadopago.com/developers/en/docs/qr-code/overview'
html=requests.get(u,timeout=20,headers={'User-Agent':'Mozilla/5.0'}).text
for pat in ['QR Code','Create an order','orders','webhook','notifications','point_of_interaction','qr_data','v1/orders']:
    if pat.lower() in html.lower():
        print('FOUND',pat)
print(re.findall(r'https://www\.mercadopago\.com/developers/en/docs/[^"]+', html)[:20])
PY

python - <<'PY'
import requests,re
u='https://www.mercadopago.com/developers/en/docs/checkout-api/integration-configuration/integrate-with-link-and-webhooks'
html=requests.get(u,timeout=20,headers={'User-Agent':'Mozilla/5.0'}).text
print('status ok len',len(html))
for s in ['webhook','notifications','x-signature','order.processed','payment.created']:
    print(s, s.lower() in html.lower())
PY


FOUND QR Code
FOUND orders
FOUND webhook
FOUND notifications
[]


status ok len 949815
webhook False
notifications True
x-signature False
order.processed False
payment.created False


**Considering documentation improvements**

I need to think about a better documentation path for Spanish users. It might be helpful to provide only high-level links. I should include information about creating orders and webhook documentation. If they need API specifications from Mercado Pago, it likely involves the "Orders API" rather than something QR-specific. I should also take a look at Ballbox's implemented documentation to understand the actual endpoints they are using.


- Ballbox native MercadoPago webhook path is `/notification/mercadopago`.
- Ballbox native QR order creation path is `/api/integrations/payments/orders`.
- For the current Ballbox Mercado Pago account/API surface, QR order create relies on the account-level webhook configuration instead of sending inline `notification_url` in the order payload, because Mercado Pago rejects that field on `POST /v1/orders` for this setup.
- That route accepts an explicit amount for arbitrary charges or falls back to the Ballbox `Product.priceMinor` when the amount is omitted, which powers per-product QR generation in the admin UI.
- The order route rejects values below Mercado Pago's minimum charge (`15.00 ARS`) before calling the provider.
- QR webhook persistence now depends on the upstream order fetch plus canonical-reference mapping; merchant-order topic events are ignored.
- Legacy approved-callback path `/api/integrations/payments/approved` is removed as an operational integration and now returns `410 PAYMENTS_APPROVED_CALLBACK_REMOVED`.
- Native payment correlation requires canonical `externalReference` values shaped as `payment-vm_{vendingMachineId}-txn_{machineTxnId}`.
- `NEXT_PUBLIC_SITE_URL` is required if Ballbox should expose a concrete `recommendedMercadoPagoWebhookUrl`.

## Validation Status
- Host app now owns the native MercadoPago order creation + webhook persistence path inside Ballbox.
- Real-world validation is now closed: one real public webhook and one real approved payment were persisted and verified in `/admin/payments` on 2026-05-13.
- Live MercadoPago payload quirks handled during closure: `topic_merchant_order_wh` remains intentionally ignored, `items[0].external_code` is accepted as product-id fallback, and `total_amount` is parsed from either string or number before persistence.
- Club revenue share is currently handled through scheduled manual settlements/bookkeeping for Ballbox-collected machines; no provider-native split payout path is live.
- First rollout planning now assumes one shared technical flow with two payment-owner modes: `BALLBOX` for club machines Ballbox collects on, and `TENANT` for client-owned collection setups such as Adidas rental machines; see `docs/payments-machine-rollout-rfc.md`.
- The admin surface includes a live QR generator preview for provider-level scan-and-pay validation, but production vending flow should move behind the TCN machine protocol instead of relying on that admin page.
- The webhook route is fetch-first: the webhook is just the trigger, and Ballbox verifies the order state by fetching Mercado Pago before persisting.
- TCN protocol review indicates the `additional hardware devices` warning applies to machine-side QR scanning, while the payment flow (`FunCode=8000`) returns `CodeUrl` for machine-screen QR display; see `docs/tcn-payments-integration-plan.md` and `test-results/tcn-payment-protocol/findings-2026-04-23.md`.
- Recent replay validation against two older live `ORD...` ids returned `MERCADOPAGO_ORDER_NOT_APPROVED_expired`; see `docs/mercadopago-webhook-replay-notes-2026-04-23.md` when resuming webhook persistence checks.

[15 more lines in file. Use offset=51 to continue.]


**Preparing final answer in Spanish**

I see the user is looking for a final answer in Spanish. I'll need to include relevant links and maybe a message template to send to TCN, asking for the estimated time of arrival (ETA). It might also be a good idea to mention the Mercado Pago account-level webhook. Okay, let's start crafting that response!


Updated #2 (in_progress → completed)

Search user-provided PDFs/docs for MML app QR/webview flow mention

Find only in passed docs/PDFs whether MML machine app mentions external QR in webview or describes that flow.

Find Mercado Pago API docs relevant to TCN external QR payment integration

Identify the Mercado Pago API/docs to send TCN so they can estimate delivery time vs hardware fallback.


Sí. Lo más útil para pasarles es esto:

Docs MP:
- Orders API:
  https://www.mercadopago.com/developers/en/docs/checkout-api/overview
- QR Code docs:
  https://www.mercadopago.com/developers/en/docs/qr-code/overview
- Webhooks / notifications:
  https://www.mercadopago.com/developers/en/docs/your-integrations/notifications/webhooks
- API reference:
  https://www.mercadopago.com/developers/en/reference

Qué les diría técnicamente:
- nosotros generamos QR dinámico por orden
- usamos Mercado Pago Orders API
- la confirmación de pago llega por webhook
- después nuestro backend puede devolverles
  el estado aprobado / trigger de dispense

Importante para no mandar humo:
- en Ballbox ya validaste create order
  + webhook real
- además tu setup actual parece usar
  `POST /v1/orders`
- y en tu caso el webhook va por config
  de cuenta, no inline `notification_url`

O sea, el paquete mínimo que ellos
necesitan evaluar es:
1. crear orden QR en MP
2. recibir webhook de aprobación
3. mapear ese pago a su software
4. disparar dispense

Mensaje listo para pasarles:

We already have Mercado Pago integrated
on our side.

Relevant Mercado Pago docs:
- Orders API:
https://www.mercadopago.com/developers/en/docs/checkout-api/overview
- QR Code:
https://www.mercadopago.com/developers/en/docs/qr-code/overview
- Webhooks:
https://www.mercadopago.com/developers/en/docs/your-integrations/notifications/webhooks
- API reference:
https://www.mercadopago.com/developers/en/reference

Our flow is:
1. create a dynamic QR order
2. customer pays from phone
3. Mercado Pago sends payment notification
   to our backend
4. backend confirms approved payment
5. machine dispenses product

Can your software team review this and
tell us:
- if this integration is feasible with
  your standard payment software
- what exact interface you need from us
- and an estimated delivery time?

If this would take several weeks, we may
instead move forward with external
payment hardware first.

Si quieres, te lo compacto más para
WhatsApp, con menos texto y más presión
por ETA.


[telegram] dale


Use este:

We already have Mercado Pago
integrated on our side.

Relevant docs:
- Orders API:
https://www.mercadopago.com/developers/en/docs/checkout-api/overview
- QR Code:
https://www.mercadopago.com/developers/en/docs/qr-code/overview
- Webhooks:
https://www.mercadopago.com/developers/en/docs/your-integrations/notifications/webhooks
- API reference:
https://www.mercadopago.com/developers/en/reference

Our expected flow is:
1. customer selects product
2. machine shows QR
3. customer pays from phone
4. Mercado Pago notifies our backend
5. backend confirms payment
6. machine dispenses product

Could your software team review this
and tell us:

1. if this can be integrated into your
standard payment software
2. what exact interface you need from us
3. approximate delivery time

If this would take several weeks, we may
go first with external payment hardware,
so an honest ETA would help us decide.


/new


queued new Telegram Pi session: pi-telegram


Hecho. Roté la sesión.