Cómo cancelar una operación de pago TPV
Anula una operación de pago vinculada a un ticket TPV, registra los datos disponibles de cancelación y deja el ticket listo para revisar el cobro o elegir otro medio de pago.
En este artículo
Usa esta guía cuando una operación de pago del TPV debe anularse antes de cerrarla como cobrada. La acción se realiza desde el cobro avanzado del ticket y también puede ejecutarse desde el panel de operaciones del terminal.
La cancelación no crea pagos ni asignaciones en el ticket. Solo actualiza la operación de pago y conserva la trazabilidad disponible: motivo, personal, terminal, fecha y referencia externa cuando el método de pago la aporta.
Antes de empezar
- Tener permiso `tpv:use` en la ubicación; para actualización directa por API también puede usarse `tpv:manage`.
- Trabajar dentro de la organización y ubicación correctas, por ejemplo Grupo Marea Demo y Marea Gran Via en el demo ES.
- Disponer de una operación de pago existente vinculada al ticket TPV.
- Usar el terminal correcto: la operación debe estar asignada al terminal actual o no estar reclamada por otro terminal.
- Para registrar una cancelación externa, el método de pago debe estar activo y usar un adapter compatible: `redirect_payment`, `http_bridge_payment` o `mock_payment`.
Instrucciones
- 1.
Abrir el cobro avanzado del ticket
Entra en el cobro del ticket desde el TPV. La pantalla carga el ticket, los métodos de pago activos y las operaciones relacionadas por `ticket_id`, con refresco periódico.
- 2.
Localizar la operación cancelable
Revisa la tarjeta de la operación en la sección de operaciones del ticket. El botón `Cancelar` aparece cuando la operación no está `completed` ni `cancelled` y pertenece al ámbito del terminal seleccionado.
- 3.
Pulsar Cancelar
Pulsa `Cancelar`. Si el método de pago tiene un adapter local compatible, la pantalla intenta cancelar primero contra ese adapter usando el terminal disponible para la operación.
- 4.
Confirmar el resultado
Tras la respuesta correcta, la operación queda en estado `cancelled`. En el cobro avanzado se registran los datos de cancelación disponibles, incluidos motivo, personal, terminal, referencia externa y `response_payload.cancellation` cuando corresponde.
- 5.
Usar el panel del terminal como alternativa
Desde el TPV, abre `Más acciones del TPV` y entra en `Operaciones de pago del terminal`. Ese panel también permite cancelar operaciones del terminal, pero lo hace mediante una actualización más simple y sin invocar el adapter local.
Validaciones y límites
- No hay endpoint específico `/cancel`; la cancelación usa `PUT /api/app/{orgId}/{locationId}/tpv-payment-operations/{operationId}`.
- Desde la UI no se muestra la acción para operaciones `completed` o `cancelled`. Las operaciones reclamadas por otro terminal no aparecen como accionables para el terminal actual.
- Si el adapter externo falla o devuelve `status: "failed"`, la pantalla muestra error y no envía el `PUT` de cancelación al backend.
- El backend fija `cancelled_at` si todavía estaba vacío y conserva valores opcionales cuando el payload los omite o los envía vacíos.
- Cancelar una operación no crea `ticket_payment`, `ticket_payment_allocation` ni `tpv_output_job`.
Resultado esperado
La operación queda cancelada y trazable, mientras el ticket permanece disponible para revisar el cobro o seleccionar otro método de pago.