How to record a manual payment
Record a completed manual payment against a Harbor Soho TPV ticket, with full payment, partial line payment, cash received, change and tip handling kept inside the ticket payment flow.
In this article
Manual payment recording is the operator-controlled path for closing all or part of a TPV ticket when the selected payment method is handled manually. The payment screen keeps the ticket, selected lines, pending amount, payment method, terminal and staff context together before the operator confirms the charge.
Use this flow for full payments, partial payments by line, and cash received or change handling. Cash-like methods require an open cash register session on the same terminal and service session before the payment can be recorded.
Before you start
- The operator is working in Harbor Demo Group at Harbor Soho and has `tpv:use` access for the location.
- A Harbor Soho ticket exists, is not void, and still has an outstanding balance. The GB documentation runtime provides `TPV_TICKET_ID` for this purpose.
- An active manual payment method is available to the operator and terminal. The runtime provides `TPV_PAYMENT_METHOD_ID` with `TPV_PAYMENT_METHOD_EXECUTION_CURRENT=manual`.
- The route includes a valid `TPV_TERMINAL_ID` and `TPV_STAFF_ID`; if the method is cash-like, that terminal has an open `cash_register_session` for the ticket service session.
- Any capture that presses `Cobrar ...` runs only in the disposable documentation runtime, because it creates `ticket_payment` data and can change ticket and item payment status.
Instructions
- 1.
Open Advanced payment for the ticket
Open the TPV ticket payment route with `TPV_TICKET_ID`, `TPV_TERMINAL_ID` and `TPV_STAFF_ID`, or enter from the ticket detail screen through `Pago avanzado`. The screen loads the ticket, TPV settings, compatible payment methods and payment history.
- 2.
Check the pending balance and selected lines
Review `Pendiente`, `A cobrar` and the selected ticket lines. The advanced payment screen selects pending units by default, so a full payment can be recorded without changing the line selection.
- 3.
Choose the manual payment method
Select the active manual method available for the current operator and terminal. For cash, CashDro, Cashlogy, CashGuard, Glory or CashKeeper methods, confirm the cash register session is open before charging.
- 4.
Adjust the payment when it is partial
For a partial payment, leave only the required pending units selected or enter an amount lower than the selected pending balance. The system sends allocations for the selected ticket items and recalculates each line as unpaid, partially paid or paid.
- 5.
Enter received amount, change or tip
For cash-like methods, an amount received above the selected pending balance is stored as cash received with the difference as change. For non-cash methods, the difference is treated as tip while the payment amount stays capped to the selected pending balance.
- 6.
Press the visible `Cobrar ...` button
The screen sends the method, terminal, amount, optional cash/change/tip values and line allocations to `POST /api/app/{orgId}/{locationId}/tickets/{ticketId}/payments`. On success, the ticket refreshes and the operator sees the success message.
- 7.
Review the payment result
Use the payment history and ticket totals to confirm the completed payment row, method, amount and refreshed balance. If no split is needed, the ticket detail quick-payment path can use the same payment endpoint for the full outstanding balance.
Validations and limits
- The ticket must belong to the same Harbor Soho location, must exist in the active context, and must not have `status = "void"`.
- `payment_method_id` is required and must refer to a payment method from the same location. Document this action with manual methods, because the advanced UI routes non-manual methods to payment operations.
- Cash-like methods require a resolved `terminal_id` and an open `cash_register_session` for the same location, service session and terminal.
- Each allocation must point to an item on the same ticket, be greater than 0, and stay within that line's remaining pending amount; the total allocated amount cannot exceed the payment amount.
- The advanced UI disables charging when the calculated amount is 0 or no lines are selected, and caps the charged amount to the selected pending balance.
- Completed payments count towards ticket and item payment status; refunded payments do not. Amount, tip, cash received and change values must be non-negative.
Expected result
A completed `ticket_payment` is created, allocations are stored, ticket and item payment status are recalculated, and the TPV screen refreshes with the updated balance and payment history.