Claim a TPV payment operation
Assign an existing pending payment operation to the active POS terminal without completing the payment, marking the ticket as paid, creating ticket-payment records or sending output jobs.
In this article
Use this guide when a floor operator or supervisor needs the Harbor Soho POS terminal to take ownership of a pending payment request before the payment result is known.
Claiming changes the existing `tpv_payment_operation` to `claimed` and records terminal ownership. It is deliberately separate from complete, cancel and fail actions, so the payment remains unresolved until the operator performs the next payment step.
Before you start
- You are signed in to Harbor Demo Group with Harbor Soho selected and POS use access for the location.
- A POS terminal is selected, such as the Harbor Soho web terminal from the GB demo runtime.
- A `tpv_payment_operation` already exists for the current service session or ticket, normally with `status: "pending"`.
- The operation is visible to the active terminal: it is unassigned, assigned to the selected terminal, or already scoped to the same claimed terminal.
- For the main POS payment-operations panel, the operation does not use `manual` or `backend_api` execution mode because those modes are hidden from that screen.
- For GB captures, prepare a documentation-only pending non-manual operation and log the demo seed gap when the runtime does not already provide one.
Instructions
- 1.
Open the POS context
Open the Harbor Soho POS floor with the selected terminal, or open the advanced ticket payment route for the ticket being settled. If the POS asks for staff context, select Olivia Hart before reviewing payment operations.
- 2.
Find the pending operation
In the main POS, open More POS actions and then the terminal payment operations panel. In the advanced ticket payment screen, review the Payments section for the operation tied to the opened ticket.
- 3.
Check terminal scope
Confirm the operation is pending and available to this terminal. Operations already claimed by a different terminal are filtered out of the current terminal's actionable list.
- 4.
Claim the operation
Use the Claim action on the operation card. In the current GB runtime, missing English translation keys may render the fallback label `Reclamar`; it is the same claim action.
- 5.
Confirm the claimed state
After refresh, confirm the operation shows `claimed` and the claim action is gone. Continue only with the correct follow-up action, such as complete, cancel or fail, after the payment result is known.
Validations and limits
- The UI screens require POS use access; read-only access may view payment operations but cannot perform the claim update.
- Claim is sent through the generic payment-operation update route, not through a dedicated claim endpoint.
- The UI offers Claim only for pending operations, but the backend validates the target status value rather than enforcing a previous pending state.
- If `terminal_id` is supplied, it must resolve to a terminal in the same Harbor Soho location.
- `claimed_at` is set by the backend if it was empty and is preserved if the operation was already timestamped.
- Claiming does not create `ticket_payment`, `ticket_payment_allocation` or `tpv_output_job` records and does not mark the ticket as paid.
- Malformed terminal ownership values can still fail at persistence because `claimed_by_terminal_id` is stored as a UUID column.
Expected result
The existing payment operation is marked `claimed`, associated with the active terminal when terminal identifiers are supplied, and refreshed across POS lists and ticket context. The payment itself remains unfinished until a separate complete, cancel or fail action is performed.