Estados y ciclo de vida

Estado documental: Contrato propuesto. Este catálogo define el significado esperado de los estados; cada valor pasa a implementado o verificado únicamente cuando exista en el producto y haya sido probado.

Objetivo

Esta página es la referencia canónica para interpretar los estados de los recursos de YUPY.

Estado financiero:
reconciled

Evento:
payment.reconciled

Tipo de caso:
late_payment

Motivo:
payment_detected_after_expiration

Cómo leer un estado

Un mismo recurso puede conservar más de una dimensión de estado.

{
  "state": {
    "operational": "active",
    "financial": "awaiting_payment"
  }
}

La dimensión operativa describe si la experiencia comercial continúa disponible. La dimensión financiera describe qué sabe YUPY sobre el pago.

Estados operativos de una orden

Un estado operativo terminal no elimina la posibilidad de identificar posteriormente un ingreso.

Estados financieros de una orden

Clasificación de diferencias

Cuando el estado financiero es amount_difference, la respuesta puede incluir una clasificación:

La clasificación no sustituye el estado financiero ni la orden original.

Estados de una sesión de Web Checkout

Una orden puede tener más de una sesión de checkout a lo largo de su vida. La expiración de una sesión no elimina la orden.

Estados de evidencia y OCR

El procesamiento de evidencia no constituye confirmación financiera.

Estados de casos pendientes

Un caso pendiente no sustituye a la orden. Conserva el problema operativo y su resolución.

Estados de devoluciones

Estados de trabajos de reporte

Estados de entregas

Las entregas pueden corresponder a instrucciones operativas o intentos de webhook. Cada recurso debe indicar su tipo.

delivered significa que el receptor aceptó la entrega técnica. No demuestra por sí solo que haya completado su efecto comercial.

Estados de turnos, dispositivos e integraciones

Transiciones

La API puede rechazar una transición cuando el recurso ya no admite la acción solicitada.

HTTP 409
invalid_state_transition

No todas las transiciones son reversibles. Una corrección debe conservar la decisión anterior y registrar una nueva acción auditada.

Tratamiento de valores desconocidos

El cliente debe:

• no interpretar un valor desconocido como éxito;
• conservar el valor para diagnóstico;
• continuar procesando campos conocidos cuando sea seguro;
• consultar la versión del contrato y el changelog;
• evitar fallos totales por la incorporación compatible de un nuevo estado no terminal.

Criterios de aceptación documental

1. Los estados están separados por recurso y dimensión.
2. Los eventos no se presentan como estados.
3. payment_reported no equivale a reconciled.
4. La expiración operativa no borra un posible resultado financiero posterior.
5. Las diferencias conservan su clasificación.
6. OCR no confirma financieramente un pago.
7. Un caso pendiente no sustituye a la orden.
8. refund_approved no equivale a refund_completed.
9. Una entrega técnica no garantiza el efecto comercial.
10. Los valores desconocidos no se tratan como éxito.

Payment Order lifecycle v1

Los estados de recursos específicos que aparecen en esta referencia —verificación financiera, diferencias de monto, sesiones de checkout, entregas, devoluciones y otros— siguen siendo útiles y no deben comprimirse en un único enum. Payment Order v1 agrega una capa de lifecycle propia para determinar cuándo una orden de cobro continúa abierta y cuándo queda cerrada definitivamente.

Estados terminales de la Payment Order

Todo cierre terminal registra closed_at. Mientras la Payment Order permanezca abierta, su Counter continúa adquirido en exclusividad y no puede ser reutilizado por otra Payment Order.

Estados financieros y lifecycle no son la misma dimensión

Los estados financieros existentes conservan su significado:

awaiting_payment
payment_reported
movement_detected
reconciled
amount_difference
ambiguous
review_required
late_detected

Estas señales describen el conocimiento financiero o la necesidad de revisión. No sustituyen el lifecycle terminal de la Payment Order.

payment_reported significa que comprador o vendedor afirmó haber pagado o entregó evidencia. Una fotografía/captura recibida también es evidencia. Ninguna de esas señales confirma financieramente por sí sola.

payment_reported / evidencia
        ↓
verificación
        ↓
Reconciliation
        ↓
reconciled
        ↓
Payment Order = confirmed
confirmed_at
closed_at
Counter released

Confirmación financiera

El Payment Order Orchestrator no confirma financieramente de manera independiente. Reconciliation encuentra y normaliza la evidencia suficiente del pago; ese resultado puede producir payment.reconciled y llevar la Payment Order a confirmed.

Expiración de Payment Order y expiración de checkout

Una sesión de checkout sigue siendo un recurso separado. Por ello:

payment_order.expires_at
≠
checkout_session.expires_at

La expiración de una sesión Web no significa necesariamente que la Payment Order haya expirado, y una Payment Order puede tener más de una sesión de checkout a lo largo de su vida según el contrato del canal.

Pagos tardíos

Cuando una Payment Order pasa a expired o cancelled, queda cerrada y libera el Counter. Si posteriormente aparece evidencia financiera relacionada, YUPY puede registrar late_detected y el evento público payment.late_detected.

Ese hallazgo tardío no reabre la Payment Order original, no elimina su closed_at y no vuelve a ocupar el Counter que ya fue liberado. La resolución comercial o contable posterior se trata como un proceso separado.

Eventos internos de cierre

El Event Log interno puede incluir:

PAYMENT_CONFIRMED
ORDER_EXPIRED
ORDER_CANCELLED
ORDER_FAILED
COUNTER_RELEASED
ORDER_CLOSED

El orden exacto de persistencia debe conservar trazabilidad suficiente para demostrar por qué se cerró la Payment Order y cuándo quedó disponible nuevamente el Counter.

Changelog — Payment Order / API Engine

2026-08-09 — Payment Order / API Engine v1.0: se documentó inicialmente el lifecycle de Payment Order. Contrato vigente: los cierres comerciales son confirmed, expired y cancelled; failed queda reservado a fallos técnicos internos cuando corresponda y no es un terminal comercial público. Se mantiene closed_at, la liberación del Counter en cierres terminales y la separación entre lifecycle operativo y estado financiero.

Exposición externa: los resultados terminales públicos del callback payment_order.terminal son pagado | cancelado | timeout.