Vigencia, espera y pagos tardíos

Contrato vigente de Web Checkout

POST /v1/checkouts requiere:

external_transaction_id: identificador de la transacción en el sistema del comercio.
amount: monto.
currency: moneda ISO de 3 letras, por ejemplo PEN.

Campos opcionales:

payment_method: por defecto qr.
payer.first_name y payer.last_name: si el comercio conoce el nombre del pagador/cliente.
timeout_seconds: vigencia solicitada por el comercio.

YUPY deriva internamente channel=web y resuelve client, counter, location, instrument y policy. Para correlación comercial del Web Checkout use external_transaction_id; source_reference no debe usarse como un segundo identificador comercial.

Hoy, cuando el comercio envía timeout_seconds, ese valor reemplaza el timeout fijo de policy para esa operación. Cuando exista el motor automático de cálculo de timeout, el valor calculado por YUPY tendrá precedencia.

{
  "external_transaction_id": "TX-12345",
  "amount": "125.50",
  "currency": "PEN",
  "payment_method": "qr",
  "payer": {
    "first_name": "Juan",
    "last_name": "Perez"
  },
  "timeout_seconds": 240
}

Respuesta inmediata HTTP 201

{
  "external_transaction_id": "TX-12345",
  "checkout_uid": "chk_...",
  "checkout_token": "cks_...",
  "checkout_url": "https://api.yupy.us/v1/checkouts/browser#token=...",
  "payment_order_uid": "po_...",
  "status": "pending",
  "amount": "125.50",
  "currency": "PEN",
  "payment_method": "qr",
  "channel": "web",
  "checkout_created_at": "2026-08-28T03:39:50Z",
  "timeout_seconds": 240,
  "delivery": {}
}

Esta respuesta confirma la creación del Checkout y de la Payment Order asociada. Las notificaciones posteriores de estado se documentan por separado.

Estado documental: Implementado y verificado en Producción.

Autoridad del timeout

client_id autenticado
    ↓
Counter virtual Web
    ↓
master_data.resolve_checkout_context(...)
    ↓
timeout_seconds + instrumento + policy
    ↓
POO

El caller no controla libremente el timeout.

Creación y presentación

checkout creado
≠
checkout presentado

La presentación efectiva ocurre cuando Browser carga el QR y registra presented.

presented_at

POO conserva presented_at como timestamp efectivo de presentación.

expires_at

POO devuelve el expires_at real. Browser usa ese timestamp como fuente del countdown.

POO expires_at
    ↓
Browser
    ↓
countdown visual

El frontend no debe hardcodear 180 segundos ni calcular el vencimiento desde la hora de creación.

Countdown en cero

00:00
    ↓
POST /v1/checkouts/browser/status
    ↓
estado canónico POO

Browser no cambia localmente el estado a timeout. Solo POO/YUPY determinan el resultado terminal.

Estados terminales

pagado
cancelado
timeout
failed

Cierre manual

cancelled_by_user es un resultado local del SDK, no un timeout ni cancelación financiera.

Reapertura

Si la checkout_url sigue siendo válida, volver a abrirla recupera el estado central. No crea otra Payment Order ni reinicia silenciosamente el timeout.

Pago alrededor del vencimiento

La realidad financiera pertenece a YUPY/POO y conciliación. El navegador no decide un pago tardío únicamente por su reloj local.

API Technical Docs