Web Checkout: visión general

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

{
  "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": {}
}

Estado documental: Implementado y verificado en Producción.

Web Checkout es la experiencia Web temporal de YUPY para presentar y seguir una operación de pago sin obligar al integrador a construir la UI financiera.

Flujo general

Backend del comercio
  → autentica
  → POST /v1/checkouts
  → recibe checkout_url

Frontend
  → YupyCheckout.open(checkout_url)

YUPY
  → resuelve contexto
  → crea Payment Order
  → presenta QR
  → administra presented, timeout y estado
  → devuelve resultado terminal

Qué muestra el Browser Checkout QR

• branding YUPY;
• nombre del cliente;
• monto;
• QR desde delivery.image_url;
• cuenta, CCI y empresa cuando existen como datos seguros del instrumento;
• instrucciones;
• countdown basado en expires_at;
• estado;
• botón Ya pagué.

SDK

<script src="https://api.yupy.us/v1/checkouts/browser/sdk.js"></script>

const result = await YupyCheckout.open(checkoutUrl);

Endpoints internos del Browser

La experiencia alojada utiliza internamente:

POST /v1/checkouts/browser/context
POST /v1/checkouts/browser/presented
POST /v1/checkouts/browser/status
POST /v1/checkouts/browser/simulate-payment   # solo cuando está autorizado

Estos endpoints pertenecen al Browser Checkout y no son la superficie normal de negocio del comercio. El integrador utiliza checkout_url y el SDK.

Presented

Browser registra presentación cuando el QR termina de cargar. Crear checkout no equivale a presentarlo.

Timeout

POO es autoridad. Browser recibe expires_at, muestra el countdown y al llegar a cero consulta nuevamente el estado canónico.

“Ya pagué”

En modo normal, Ya pagué registra en POO la declaración canónica PAYMENT_DECLARED y luego continúa consultando el estado real de la Payment Order. La declaración es no terminal: no marca pagado, no establece confirmed_at y no sustituye la confirmación financiera.

Payment Simulation

YUPY puede habilitar un modo de prueba para un Web Checkout cuando la credencial que lo creó estaba autorizada con payments:simulate.

Browser Context expone únicamente la capacidad segura:

{
  "payment_simulation_enabled": true
}

No expone scopes, Client Secret, Bearer ni payment_order_uid como autoridad del navegador.

La operación Browser de simulación recibe únicamente el checkout_token. YUPY resuelve server-side la sesión y su Payment Order. El navegador no envía como autoridad payment_order_uid, client_id, counter_id, result ni un campo libre simulate=true.

Cuando la simulación está autorizada, YUPY aplica al Payment Order Orchestrator el mismo resultado terminal canónico usado por el flujo normal:

pagado

Después vuelve a consultar el estado real del POO y lo entrega al Browser/SDK. No existen estados simulated, simulation_paid, test_paid ni equivalentes.

Estados terminales

pagado
cancelado
timeout
failed

Cierre manual del modal

{
  "status": "cancelled_by_user",
  "terminal": false,
  "source": "yupy_sdk"
}

Es cierre local de UI; no cancela la Payment Order.

Resultado SDK

{
  "status": "pagado",
  "terminal": true,
  "source": "yupy_checkout"
}

Responsabilidades