Web Checkout: visión general

Estado documental: Propuesto. Este documento define el comportamiento funcional esperado del Web Checkout y debe confirmarse durante la implementación.

Qué es Web Checkout

Web Checkout es una experiencia temporal de pago servida por YUPY y asociada con una transacción comercial específica.

El servidor de la empresa solicita a YUPY una pantalla de pago. Para ello envía el monto, la moneda, el identificador de su transacción y los datos adicionales necesarios para contextualizar la experiencia.

YUPY crea la orden, genera una sesión temporal y devuelve una URL completa. La web de la empresa abre esa URL directamente o la muestra dentro de una ventana embebida mediante el SDK.

Servidor de la empresa
    → solicita una pantalla de pago
    → envía monto e ID de transacción

YUPY
    → crea la orden
    → crea una sesión temporal
    → devuelve checkout_url

Web de la empresa
    → abre checkout_url
    → la muestra como página, modal o ventana embebida

YUPY
    → controla el contenido de la ventana
    → espera, detecta y concilia el pago
    → actualiza la experiencia
    → notifica al servidor de la empresa

Qué envía el servidor de la empresa

Como mínimo:

• identificador externo de la transacción;
• monto;
• moneda.

Según el caso, también puede enviar:

• nombre y apellido del comprador;
• identificador del comprador;
• identificador del sitio, marca o comercio;
• identificador del cliente o cuenta dentro de la plataforma;
• perfil de cobro;
• idioma;
• URL de retorno;
• perfil visual o logotipo previamente autorizado;
• local, vendedor, turno o terminal;
• referencias adicionales de correlación.

Los datos visuales no deben enviarse libremente sin validación. La opción preferida es referenciar un perfil de marca previamente configurado. Cuando el contrato permita una URL de logotipo, YUPY deberá validarla antes de mostrarla.

Qué devuelve YUPY

YUPY devuelve como mínimo una referencia de sesión y una URL completa.

{
  "yupy_transaction_id": "ypt_01JXYZ...",
  "external_transaction_id": "ORDER-10482",
  "checkout_session": {
    "checkout_session_id": "ycs_01JXYZ...",
    "checkout_url": "https://<YUPY_CHECKOUT_HOST>/checkout/<OPAQUE_TOKEN>",
    "expires_at": "2026-07-20T14:45:02-05:00"
  }
}

La plataforma debe usar exactamente el valor de checkout_url. No debe construir la URL ni concatenar manualmente el token.

Cómo se muestra

Página alojada

La plataforma redirige al comprador o abre la URL en una nueva vista.

Ventana embebida mediante SDK

La plataforma reserva un contenedor, carga el SDK y le entrega la URL recibida. El SDK abre la experiencia dentro de un modal, iframe o componente controlado.

Web de la empresa
└── SDK de YUPY
    └── ventana temporal
        └── checkout_url servido por YUPY

La misma sesión puede utilizarse como página alojada o dentro del SDK, siempre que el contrato de seguridad y vigencia lo permita.

Qué puede aparecer dentro de la ventana

La empresa necesita conocer el propósito general de la experiencia, pero no tiene que implementar ni aprobar cada elemento interno.

YUPY puede mostrar:

• uno o varios QR de Yape;
• uno o varios QR de Plin;
• una cuenta bancaria o CCI cuando la transferencia esté habilitada;
• monto y moneda;
• nombre receptor;
• instrucciones;
• estado de espera;
• acción “Ya pagué”;
• verificación en proceso;
• vencimiento operativo;
• diferencias de monto;
• mensajes de error;
• confirmación de conciliación;
• instrucciones posteriores al resultado.

El contenido exacto puede evolucionar en YUPY sin modificar la integración base del cliente, siempre que se conserve el contrato de apertura, compatibilidad, seguridad y eventos.

Alcance actual

La primera versión está prevista para:

Yape mediante QR
Plin mediante QR
Transferencia bancaria opcional

El perfil de cobro determina cuáles de esas opciones están habilitadas para la empresa.

Qué no hace el SDK

El SDK no:

• crea la venta comercial por sí solo;
• guarda credenciales privadas de integración;
• consulta directamente el banco;
• decide arbitrariamente que un pago fue realizado;
• sustituye la conciliación;
• sustituye el webhook server-to-server;
• obliga a la empresa a implementar la interfaz interna.

Fuente de verdad

Ventana abierta
≠ pago detectado

“Ya pagué”
≠ pago confirmado

Evento visual del SDK
≠ cierre financiero definitivo

Movimiento conciliado por YUPY
= pago confirmado por YUPY

La ventana refleja el estado. El backend de YUPY mantiene la realidad financiera y notifica al servidor de la empresa mediante webhook o consulta autenticada.

Responsabilidades

Servidor de la empresa

• crear la solicitud;
• autenticarse;
• enviar un ID externo estable;
• conservar la correlación;
• recibir webhooks;
• actualizar la venta de forma idempotente.

Frontend de la empresa

• abrir la URL o montar el SDK;
• reservar espacio suficiente;
• manejar apertura y cierre;
• mostrar estados visuales complementarios cuando corresponda;
• no interpretar un callback visual como única evidencia financiera.

YUPY

• crear y proteger la sesión;
• resolver el contenido;
• mostrar las opciones habilitadas;
• actualizar el estado visible;
• detectar y conciliar;
• emitir eventos y webhooks;
• proteger datos y credenciales.

Extensibilidad futura

La ventana podrá incorporar posteriormente otros medios, como tarjetas, otras billeteras virtuales, Google Pay, Apple Pay o criptoactivos, sin exigir que la empresa reconstruya el contenedor.

Esos medios son parte del roadmap y no deben considerarse disponibles hasta que exista una versión contractual e implementación verificada.

Criterios de aceptación

1. El servidor de la empresa puede solicitar una pantalla.
2. YUPY exige monto, moneda e ID externo.
3. Los datos opcionales se validan.
4. YUPY devuelve una URL completa.
5. La plataforma no construye la URL.
6. La URL abre la transacción correcta.
7. La misma experiencia puede abrirse alojada o embebida.
8. YUPY controla el contenido interno.
9. El SDK no contiene secretos backend.
10. La conciliación continúa aunque se cierre la ventana.
11. El webhook mantiene actualizado el sistema comercial.