Pinpad app (unpispas-ptf)

Staff-facing SPA for payment terminals (datáfonos). Operators sign in, pick a place, and work from a mobile-first home: Mesas, Avisos, Tickets, optional Caja, and cart with the same product selector as POS mobile (upp-cart-select). This page covers access (epic 01), payment-terminal linking (epic 02), the work screen (epic 03), card charge on the terminal (epic 04), what happens when the charge goes wrong (epic 05), printing the receipt on the terminal (epic 06), automatic receipt on payment (epic 07), cash block (epic 08), card refunds on the terminal (epic 09), charging guest payment requests from a table (epic 10), and charge from the POS till (epic 11).

Floor guides (Spanish, no API names): staff · manager. Print-service wire contract and handoff for pispas-connect: Print-service requirements.

Layer	Where
App shell	apps/unpispas-ptf/ — Access = 'LOGIN', WorkMode = 'PTF', AppProfile = { mode: 'mobile', zoom: 0.9 }
Screens	libs/feature/pinpad/upp-feature-pinpad.mdc (home, work, tables, tickets, cash, cart)
Login / user	Reuses feature-login / feature-user (no feature-place / feature-guest)
Sync (PTF)	Shared floor-first priorities (RN-SYNC-30); client=PTF → server datamodel target pinpad (no cash-control transfer, RN-SYNC-31); refresh ×4; Start awaits create — sync.mdc RN-SYNC-30…33
REST	POST /login?client=PTF (via adhoc WorkMode) marks SESSION.mode; device-name clash → Exists (8) — OpenAPI in docs/swagger/
Terminals (POS)	libs/feature/devices — PINPAD under each print service

Canonical URL

Surface	Host	Public path
Nx docker	ptf.nx.{domain}	/unpispas-ptf/
DEV/LAB edge	ptf.{DOMAIN} (PTF_DOMAIN)	Host / (own ACME cert, not in api+app SAN). Legacy /unpispas-ptf/* 301 to that Host.

Production baseHref is /; development keeps /unpispas-ptf/. Materialize writes appPath: 'ptf.' and appRoute: '/' for this app. Opening app.* on a datáfono does not redirect to ptf (RN-PTA-03).

Staff flow

Step	Behaviour
Login	Always remembers session; device name field uses shared @login_deviceid_* (PTF catalog customizes copy; name is display / fingerprint disambiguation only, not a unique id). Query client=PTF from adhoc. Splash uses the same MarkReady paint delay as POS (500 ms).
Place	Auto-enter when the user has a single place; otherwise picker.
Home / work	Mobile chrome; work tabs Mesas / Avisos (badge = pending PayRequests) / Tickets; Caja only with TillManage and exactly one till (hydrate on first open). Settings zoom 50–100%; change place if multi-place; logout confirm. Ticket detail and cart follow the POS mobile panel pattern: one shell upp-panel; header/tabs hide while ticket/cart fill panel-content (same idea as place/upp-view / upp-cart / QRA order layers).
Warnings	Unlinked when the session PosDevice has no linked terminal (!Linked); “does not look like a datáfono” via platform.SeemsMobile — never block navigation.

Payment terminals (epic 02)

Terminals are registered in the usual POS app (app.*), under each print service’s device editor — never inside ptf.* (RN-PTF-09).

Topic	Behaviour
Where	feature/devices → service editor → «Terminal de pago» (upp-pinpad-edit / upp-pinpad-view)
Data	Name, host, port (default 8887), optional write-only API key, oncash / oncard / nocash
Persist	PINPAD.posdevice → POSDEVICE.objid (cross-DB, same pattern as RASPPICONNECT / SESSION)
Link UI	Choose a PosDevice from PTF sessions (place.sessions) plus already-linked devices (pinpads); selection and exclusion use instance identity (===); one active device per place
Presence	«Connected» when the row’s mode=PTF session is IsActive (AC + touch ≤ 10 min)
On ptf	UppPinpadHomeComponent.Linked when session.device.pinpad returns a terminal

Model detail: data-objects — Pinpad. Rules: upp-model.mdc (RN-DIL-* / RN-PTM-*), upp-feature-devices.mdc, upp-feature-pinpad.mdc (RN-PTF-06).

Card charge (epic 04)

When the place has active payment terminals and this datáfono is linked (PlaceView.CardMethod === 'TERMINAL'), Tarjeta opens upp-pinpad-payment (owned by feature/pinpad; ticket hosts open the dialog) against PlaceView.OwnPinpad via paytefService. Unlinked devices show @ticket_cardterm_unlinked and do not open a dialog.

Charge from the POS till (epic 11)

On the till app (unpispas-pos), if the place has ≥1 active PINPAD, CardMethod is also TERMINAL and Tarjeta opens the same Paytef dialog against a terminal resolved from inventory (OwnPinpad is null on POS — so cash blocking and auto-receipt stay off on the till). One terminal is used without asking; several open upp-pinpad-select on every payment (rows from BuildOptions: till label + connected badge, informational only — no session memory of the last choice). Card returns use the same three options as on ptf; an unbound refund picks via place.pinpads / the same picker. Without a BAR printer, fiscal receipts can go through a terminal on the till service (place.service.pinpads, resolved by the print queue). Confirming a guest table PAYCARD request (RequestDone) still registers with DoPayment (no pinpad UI in feature/qrcode — Nx isolation).

What the waiter sees	Behaviour
Stages	Connecting → waiting card → PIN / currency / signature / customer → processing (RF-04-05 texts).
Approved	«Aprobado», auto-close ≈1.5 s, ticket closed with PinpadCharge.Settle → ApplyPinpad (no accept button).
Cancel	Disables cancel, shows «Cancelando el cobro»; if the terminal already approved → hint «ya se había aprobado».
Failure (clean / DE)	The reason in its own words, with Reintentar, Marcar como pagado and Cerrar (see When the charge goes wrong).
Uncertain (PE / PENDING)	Status-first: WAITING polls Resolve (5 s, up to 90 s of UNKNOWN; IN_PROGRESS does not burn the budget). No Reintentar. Idle → Consultar / Manual / X (no new charge while the terminal is unreachable).
Escape / outside	Ignored while the charge dialog is open.
Reopen with PE	Poll Resolve (same as uncertain); if still unknown → idle / persistent «pendiente de comprobar» with ⋯ unlock. Tarjeta stays enabled but the dialog never charges until the prior attempt is clear or discarded.

Ticket data stored (PINPADPAY): reference, amounts, terminal codes, auth, timestamps, receipts, signature, status PE/AP/DE/MM/MA. Closing the ticket is only via TicketView.ApplyPinpad() after an approved (AP) or manually declared (MA) charge.

When the charge goes wrong (epic 05)

Clean failures (DE) leave the dialog open with the reason and Retry / Manual / Close. Uncertain results (PE) do not offer Retry: the panel polls terminal status first (Adyen/MarketPay pattern). Nothing closes by itself and nothing is charged twice to “resolve doubt”.

Exit	What it does
Reintentar	Starts a new charge for the same amount only when the previous attempt is known not charged. Not offered while PE remains, nor on amount mismatch.
Consultar de nuevo	From idle: restarts the Resolve poll on the same attempt.
Marcar como pagado	Records that the waiter took the payment by other means and closes the ticket as paid by card (with confirmation if a PE is still unresolved).
Cerrar	Leaves the ticket unpaid. An attempt that could not be checked stays pending and is checked when the ticket is reopened. Discard without a new charge is only from the ticket ⋯ unlock menu (Supersede).

The messages below are indicative wording (final texts are agreed with the customer). The app never guesses the reason from free text: it shows the one the print service reports, and the generic message when none is reported.

Situation	Message (es)
No payment service on this device	No hay servicio de cobro
No connection with the terminal	Sin conexión con el datáfono
Terminal not operational	El datáfono no está operativo
Paytef service unavailable	El servicio del datáfono no está disponible
Operation not authorised	El datáfono no autoriza la operación
Terminal busy (another device or this one)	El datáfono está ocupado
Charge could not start	No se pudo iniciar el cobro
State of the charge cannot be read	No se pudo consultar el estado del cobro
Three minutes without paying	Tiempo de espera agotado
No result obtained	No se obtuvo el resultado del cobro
Cancelled on the terminal	Cobro cancelado en el datáfono
Declined	Pago denegado
Terminal charged another amount	El importe cobrado no coincide

• The earlier attempt is checked before repeating. If the customer already paid but the dialog missed it, the dialog shows it as approved instead of charging again; if the terminal cannot be asked, the waiter must confirm explicitly.
• «Marcar como pagado» is a declaration of the waiter. It is stored as a manual payment (status MA), without terminal receipts, and closes the ticket exactly like an approved charge.
• While the terminal waits, Cancelar asks the terminal to cancel, and Marcar como pagado cancels first and then declares the payment, unless the terminal had already approved it. If the terminal does not answer the cancellation, the dialog closes anyway with a warning and the charge is checked when the ticket is reopened.
• Two charges at once are not possible on the same ticket or the same terminal from this app: the second shows «El datáfono está ocupado» and is not queued.

Print-service requirements (contract points)

Handoff for pispas-connect. The Nx app (unpispas-ptf / POS) already speaks the 13-point wire contract. Closing the Payteff plan on the app side leaves the print-service gaps below as the next owned work in pispas-connect (desktop paytef.rs + Android PaytefService.java). Publish the durable behaviour write-up as pispas-connect/docs/PAYTEF.md and link it from MODULES.md. Checklist contrasted on 2026-10-24 (code + unit tests; no real pinpad in that pass).

#	Need	Desktop	Android
1	Order language es/en/eu reaches the pinpad	no	no
2	3 min ceiling: cancel and read final result	no (5 min, no final read)	no (no ceiling)
3	Last-result query (op, ref, amount, time, free/busy)	no	no
4	Refund with caller-supplied original operation number	no (24 h local cache only)	no
5	Typed failure cause	no (generic error string)	no
6	Full result (tip, original amount, returned ref, receipts)	no (partial payload)	no
7	Ask for receipts; no tips; no pinpad receipt options; keep signature	no (createReceipt: false)	no
8	Busy: reject without queueing, report busy	no	no
9	Print success from printer result; query presence/width	no (HTTP 2xx = success)	no
10	Honour terminal host/port	yes	no (always 127.0.0.1:8887, by design on-device)
11	Optional API key sent when present	no	no
12	Forward transaction/card status as-is	yes	yes
13	CANCEL on another connection during SALE; answer PING on the waiting connection	unproven / PING blocked	unproven / PING blocked

Priority for connect: 2, 3, 5, 7, 8, 9, 13 (busy + last-result + cancel life-cycle unblock CA that the app already implements). Client transport: WSConnection with timeoutMs, suspended keep-alive, and OnProgress. Charge failures without a typed cause show the generic message; print without a printed flag surfaces as UNKNOWN / browser backup.

Print the receipt on the datáfono (epic 06)

On ptf, Imprimir on a ticket does not open the browser dialog first. Destination order (owned by queueService):

1. BAR printers of the till service (same as POS).
2. Else the own Paytef terminal (place.OwnPinpad) — same print path as BAR; the fiscal QR is already on the paid ticket.
3. Else the browser print dialog.

Outcome	What the operator sees
Printed on terminal or BAR	Nothing (silent). History gets one RECEIPT.
Terminal unreachable / offline	«Sin conexión con el terminal», then browser backup. No RECEIPT.
Terminal busy	«El datáfono está ocupado», then browser. No RECEIPT.
No printer on terminal	«Este datáfono no tiene impresora», then browser. No RECEIPT.
Other print failure	«No se pudo imprimir en el terminal», then browser. No RECEIPT.

• Fiscal QR: produced at payment, before any print job. The terminal printer is equivalent to a BAR printer: it prints the ticket as-is (QR included when the place emits VeriFactu/TicketBAI).
• Paying on ptf never opens the cash drawer. The receipt is printed on request with Imprimir, or automatically when the option described below is on.
• Card voucher: menu option «Imprimir comprobante de tarjeta» when a stored merchant/customer copy exists and there is an own terminal. Chooses copy if both exist; terminal only (no BAR/browser, no RECEIPT).

Automatic receipt on payment (epic 07)

Each payment terminal has two switches, edited in the POS app (app.*) under the print service's «Terminal de pago» editor: «Imprimir recibo al cobrar con tarjeta» (oncard) and «Imprimir recibo al cobrar en efectivo» (oncash). With one on, the receipt comes out on the datáfono by itself when the waiter charges in that modality from ptf.

Situation	What happens
Card charge approved, or Marcar como pagado, with oncard on	One receipt on the datáfono.
Cash payment with oncash on	One receipt on the datáfono. The drawer is not opened.
Option off for that modality	Nothing is printed; Imprimir keeps working as before.
Refund, mixed payment, account payment, partial payment, account settlement	No automatic receipt.
Several payments in a row	One receipt per ticket, in charge order, one at a time; a failed one does not stop the next.
Screen closed right after charging	The receipt is still printed.
Datáfono busy right after the sale	Retried up to 3 times, 2 s apart (assumed values, to be confirmed in the pilot); then the «ocupado» warning.
No paper / unreachable / other failure	The warning with the cause. No browser dialog and no RECEIPT; the payment stays correct and Imprimir retries.

• The automatic receipt goes only to the own terminal, even if a BAR printer is configured; the POS app is unchanged.
• The charge never waits for the paper: printing runs in the background.

Cash block (epic 08)

Each payment terminal has «No permitir efectivo» (nocash), edited in the POS app under the print service's «Terminal de pago» editor. When it is on for the own terminal of a ptf session, that datáfono no longer offers cash collection.

Situation	What happens
Own terminal with nocash on	Cash button (ticket and list), «change to cash», mixed and partial disappear.
Same ticket on the POS till	Cash stays available (place.CanCash ignores nocash outside ptf).
Option turned off, then sync	ptf offers cash again, including with a ticket already open on screen.
Two datáfonos, only one with nocash	Each applies its own terminal's option.
Datáfono without a linked terminal	Block does not apply (place.CanCash stays on place option); card charge still needs a link (epic 04).
Ticket already paid in cash	History, payment and amounts stay unchanged.
Cash refunds	Not changed by this epic (see refunds epic).

• Tarjeta and account charge keep the same routes.
• No new warnings or language keys: blocked actions are simply not shown.
• A cash choice already pending locally (_pendpay) is not revoked when the option flips mid-flow.

Card refunds (epic 09)

When a closed ticket has a card part to give back and this datáfono is linked (PlaceView.CardMethod === 'TERMINAL'), returning products with a card amount reuses the same upp-pinpad-payment dialog in refund mode instead of just adjusting the ticket. The waiter decides how, the app decides which terminal.

What the waiter sees	Behaviour
No terminal involved	Cash-only, TPV without a terminal, or CardMethod === 'UNLINKED': the return registers exactly as before epic 09.
Linkable refund	A full refund of a single approved card charge (not a mixed/manual one, no prior refund of it, not part of a multi-order account charge) offers the sale's own terminal, even if this datáfono is a different one.
Loose refund	A partial card refund, or one that cannot be linked, offers this datáfono's own terminal.
Sale's terminal unreachable	Only Marcar como pagado and Cancelar; the terminal dialog never opens.
Cancel at the choice	Nothing changes: no OnReturn, no commit, no new PINPADPAY row.
Approved on the terminal, or declared manually	The return registers (OnReturn + commit), then the refund row is marked applied. A failed or cancelled attempt leaves the ticket untouched.
Already-approved refund of the same amount	Registers straight away without asking or reaching the terminal again (a known limit: a later legitimate refund of the same exact amount would also be absorbed by that leftover row until it is consumed).
Cash blocked on this terminal (epic 08)	The cash refund option disappears; a full card refund is still offered.
Reopening with a refund pending	Same persistent-notice pattern as a pending charge, checked first: pending card charge, then pending refund, then an approved-but-unregistered refund, then nothing.

The approved path, end to end:

• No automatic receipt, no reprint. A refund never triggers the automatic-receipt option (epic 07) and this epic does not offer a voucher reprint for it.
• No two card operations at once. A charge and a refund never run together on the same ticket or the same terminal from this app.
• Terminal first, ticket after. The ticket is only touched (OnReturn + commit) once the terminal has approved — or the waiter declared it manually — never before.

Table payment requests (epic 10)

Guests on qra still only request payment (cash/card AskWaiter + IsToPay). They never run Paytef. On ptf, pending asks surface like POS: the shared topbar WAITER strip (place.AlertSize / AlertTables) and Attention on the mesa thumb. There is no Avisos footer tab. Tapping the topbar strip (single mesa) or an Attention mesa opens upp-table-edit (ventana de cobro). Work remaps topbar placetables onto the Mesas tab.

What the waiter sees	Behaviour
Topbar WAITER	Same strip as POS; one mesa → open that table Attention; several → Mesas tab with Attention thumbs.
Mesa with Attention	Tap opens upp-table-edit cobro (POS parity).
Charge card / cash	Same ticket / Attention payment flows as POS (upp-pinpad-payment, cash when CanCash).
Fail / cancel	Tickets stay IsToPay; asks stay open; topbar / Attention remain.
Later refund of one bill	Joint-charge rows with Orders.length > 1 stay loose refunds (epic 09 / RF-09-09b).
Auto receipt	One automatic receipt per paid ticket (epic 07).

Helper: upp-pinpad-paycharge for joint-charge orchestration when needed. Model: PayRequest / PlaceView.PayRequests / AlertTables (upp-model.mdc RN-ASK-PAYREQ-*). Service: multi-ticket Charge / incidents (upp-paytef-service.mdc).

Assumptions checked in the pilot (S-PTF-*)

Conservative working assumptions. A row is only relaxed when a real Paytef pinpad confirms otherwise. The Nx Payteff plan is closed (2026-10-31): field pilot and customer sign-off stay outside this closure (connect team + local acceptance). Until that field pass, every row stays Not yet run.

ID	Assumption still in force	Field result
S-PTF-01	Linked refund only for the full amount of that charge and with no prior refunds; partials, later refunds and one bill of a joint charge go loose	Not yet run on a real pinpad
S-PTF-02	Charge reference ≤ 32 characters, no specials; joint charge = first order + +N	Not yet run
S-PTF-03	Cancel does not guarantee “not charged”: the final result is read; if approved, the ticket is charged	Not yet run
S-PTF-04	Card receipts may be required; the app asks for them and stores them. The current print service sends createReceipt: false	Not yet run
S-PTF-05	API key optional on the terminal; HTTPS out of this plan. The current print service never sends the key	Not yet run
Charge in the 5 s result window (epic 04 scenario 10)	Whether the pinpad accepts a new sale or answers busy	Not yet run

Isolation

• stateService.WorkMode === 'PTF' drives client behaviour; POS stays POS.
• No imports of feature-place / feature-guest from feature-pinpad or the ptf shell.
• Session mark SESSION.mode drives presence/linking; guests get mode = QRA.

Contracts

• App: apps/unpispas-ptf/unpispas-ptf.mdc
• Feature: libs/feature/pinpad/upp-feature-pinpad.mdc
• Devices: libs/feature/devices/upp-feature-devices.mdc
• Floor guides: ptf-personal, ptf-responsable
• Print service handoff: table above → implement + document in pispas-connect (docs/PAYTEF.md, MODULES.md); client contract libs/feature/drivers/src/lib/upp-paytef-service.mdc
• View profile: libs/upp-base/src/frontlib/view.mdc (AppProfile)
• Login / device-name Exists: server/src/App/Services/login/login.mdc, libs/feature/login/.../upp-login.mdc
• Deploy Host: unpispas.deploy PTF_DOMAIN (parity LAB/DEV with QRA_DOMAIN pattern)