POS vía chat: visión general

Estado documental: Propuesto. Este documento define la modalidad POS vía chat dentro del modelo Payment Order / API Engine v1.0.

Qué es POS vía chat

POS vía chat permite iniciar, presentar, acompañar y conciliar cobros desde un canal conversacional. La modalidad no depende de una plataforma específica: puede operar mediante WhatsApp, chat propio de YUPY, Messenger, Telegram u otros canales integrados.

Una cobranza puede originarse de dos formas principales:

• Creación manual: una persona que opera un turno solicita el cobro desde el chat.
• Creación desde un sistema integrado: el sistema de ventas envía la intención de cobro mediante la API pública y YUPY resuelve el contexto operativo necesario para entregarla al Counter correspondiente.

La creación manual debe continuar disponible aun cuando exista integración con un sistema de ventas.

Modelo común: toda cobranza es una Payment Order

Toda operación de cobro en POS vía chat se materializa internamente como una Payment Order. La Payment Order permanece asociada a un Counter exclusivo mientras esté abierta.

Persona o sistema origen
        ↓
YUPY API Engine / Adapter del origen
        ↓
resuelve Cliente y contexto operativo
        ↓
resuelve Counter
        ↓
Payment Order Orchestrator
        ↓
adquiere Counter
resuelve instrumento concreto
crea Payment Order
        ↓
canal conversacional
        ↓
presenta instrucción de pago

El contrato público y el contrato interno del Payment Order Orchestrator son distintos. El caller expresa la intención de cobro; YUPY resuelve los identificadores internos necesarios antes de invocar al Orchestrator.

Counter, Cuenta WhatsApp y Persona son entidades diferentes

En POS vía chat deben mantenerse separadas tres identidades operativas:

La Payment Order se enruta al Counter y, cuando corresponde, YUPY resuelve la Cuenta WhatsApp asignada a ese Counter. La persona logueada no sustituye esa configuración de routing.

Origen manual

En creación manual, la persona inicia el cobro desde la conversación. YUPY conoce el contexto operativo de la sesión y puede resolver el Counter asociado antes de crear la Payment Order.

Persona operando turno
    ↓
“Cobrar 85.50”
    ↓
YUPY identifica sesión / contexto
    ↓
resuelve Counter
    ↓
crea Payment Order
    ↓
resuelve instrumento
    ↓
envía instrucción de pago al canal

El operador no debe elegir manualmente un QR concreto, un ID interno de instrumento, una Cuenta WhatsApp o un Reconciliation Target.

Origen desde un sistema integrado

Cuando el sistema de ventas origina la cobranza, la API pública recibe la intención comercial. El Adapter de POS resuelve el Counter aplicable antes de entregar el request canónico al Payment Order Orchestrator.

El integrador conserva al menos su identidad comercial mediante external_transaction_id y utiliza Idempotency-Key para los reintentos técnicos. YUPY devuelve payment_order_uid como identidad canónica de la Payment Order.

Campos como counter_id, client_id, QR ID, Cuenta WhatsApp, Agencia o Reconciliation Target no deben exponerse como selección libre del caller salvo que un contrato especializado lo justifique expresamente.

Un solo medio solicitado por Payment Order

El modelo actual ya no trata Yape QR, Plin QR y transferencia como un menú de alternativas que YUPY debe devolver para una misma Payment Order. El caller o la operación manual seleccionan el tipo de medio requerido y YUPY resuelve el instrumento concreto elegible para el Counter.

Para el flujo QR actual:

payment_method = qr
payment_instrument_type = qr_bbva

YUPY administra el QR BBVA. Yape y Plin son mecanismos que el pagador puede utilizar para leer y pagar ese QR; no son dos instrumentos QR administrados independientes.

Presentación al pagador

Preparar el payload o resolver el QR no equivale a haber presentado la instrucción al pagador. El canal debe registrar el momento efectivo de presentación mediante el concepto:

payment_instruction.presented
presented_at

En un flujo conversacional, presented_at corresponde al momento en que el canal confirma que la instrucción de pago fue realmente entregada o mostrada según el tipo de integración. Ese momento permite iniciar el reloj operativo real de presentación.

Participación directa del comprador

El comprador puede participar directamente en el chat cuando la experiencia lo permita. Por ejemplo, puede recibir la instrucción de pago, informar que ya pagó o enviar una fotografía/captura de su operación.

La participación del comprador no cambia la identidad de la Payment Order ni del Counter.

“Ya pagó”, fotografías y OCR

Las señales operativas de pago deben distinguirse de la confirmación financiera:

SELLER_CLAIMS_PAID
SELLER_PHOTO_RECEIVED
BUYER_CLAIMS_PAID
        ↓
verificar lo antes posible
        ↓
Reconciliation
        ↓
PAYMENT_CONFIRMED

Una persona puede marcar Ya pagó y puede enviar una fotografía o captura. Una fotografía es evidencia y puede activar OCR para extraer información visible, pero por sí sola no significa que la Payment Order esté financieramente confirmada.

La confirmación canónica ocurre cuando Reconciliation encuentra y normaliza evidencia suficiente del pago; entonces se registra confirmed_at.

Turnos y dispositivos

POS vía chat conserva trazabilidad de quién operó el cobro y desde qué contexto. Cuando aplica, la operación mantiene referencias a turno y dispositivo para auditoría y routing interno.

Una sesión de turno identifica a una persona operando desde una Cuenta WhatsApp o canal determinado. La Cuenta WhatsApp conserva su propia identidad operativa independientemente de quién esté logueado.

Lifecycle y liberación del Counter

Los estados terminales v1 de una Payment Order son:

confirmed
expired
cancelled
failed

Al alcanzar un estado terminal, YUPY registra closed_at y libera el Counter. Mientras la Payment Order permanezca abierta, el Counter no debe ser utilizado simultáneamente por otra Payment Order.

Pagos tardíos

Si una Payment Order expira o se cancela, el Counter se libera. Una evidencia financiera detectada posteriormente puede registrarse como pago tardío, pero no reabre la Payment Order original ni vuelve a ocupar su Counter.

Eventos internos relevantes

El flujo interno puede registrar, entre otros:

ORDER_CREATED
COUNTER_ACQUIRED
INSTRUMENT_SELECTED
DELIVERY_PREPARED
PAYMENT_INSTRUCTION_PRESENTED
SELLER_CLAIMS_PAID
SELLER_PHOTO_RECEIVED
BUYER_CLAIMS_PAID
VERIFICATION_SCHEDULED
VERIFICATION_STARTED
VERIFICATION_NOT_FOUND
VERIFICATION_AMBIGUOUS
PAYMENT_CONFIRMED
ORDER_EXPIRED
ORDER_CANCELLED
ORDER_FAILED
COUNTER_RELEASED
ORDER_CLOSED

No todos estos eventos internos tienen que convertirse en webhooks públicos. La API pública mantiene su propio catálogo y versionado.

Ejemplo conceptual

1. Persona abre turno.
2. Solicita cobrar S/ 85.50.
3. YUPY resuelve Cliente, sesión y Counter.
4. El Counter queda adquirido para la nueva Payment Order.
5. La operación solicita QR / qr_bbva.
6. YUPY resuelve el QR concreto habilitado para ese Counter.
7. El canal presenta la instrucción y registra presented_at.
8. El comprador paga con Yape o Plin leyendo el QR BBVA.
9. El vendedor puede reportar “Ya pagó” o enviar foto.
10. Reconciliation verifica el pago.
11. YUPY registra confirmed_at.
12. La Payment Order se cierra y el Counter se libera.

Reglas de diseño

• POS vía chat es una modalidad; WhatsApp no es el nombre del producto.
• La creación manual y la creación desde API pueden coexistir.
• El Counter es la unidad exclusiva de ejecución de una Payment Order abierta.
• La Cuenta WhatsApp es un canal/destino, no la identidad del operador ni la propietaria del QR.
• La Persona conserva identidad propia y puede operar desde distintas Cuentas WhatsApp autorizadas.
• El caller selecciona el tipo de medio requerido; YUPY resuelve el instrumento concreto.
• Yape y Plin son mecanismos de pago sobre el QR BBVA administrado por YUPY.
• “Ya pagó” y las fotografías son claims/evidencia, no confirmación financiera.
• Reconciliation es quien produce la confirmación financiera normalizada.
• La expiración o cancelación libera el Counter incluso si luego aparece evidencia tardía.

Changelog

2026-08-09 — Payment Order / API Engine v1.0: se alineó POS vía chat con Payment Orders y Counters exclusivos; se separaron Counter, Cuenta WhatsApp y Persona; se estableció que el Adapter del origen resuelve el Counter antes del Orchestrator; se reemplazó el menú histórico de QR Yape/Plin/transferencia por selección de un medio e instrumento requerido, usando qr + qr_bbva para el flujo QR actual; se incorporó payment_order_uid, la confirmación de presentación payment_instruction.presented, la distinción entre claims/fotos y confirmación financiera, y la liberación del Counter al cierre.