SDK, URL y token de Web Checkout

Estado documental: Propuesto. La forma exacta de las URLs, nombres del SDK y eventos deberá confirmarse durante el desarrollo.

Concepto

El SDK de Web Checkout es una ventana temporal hacia los servidores de YUPY.

La empresa no integra cada QR, texto, instrucción o estado de forma individual. Integra un contenedor y abre dentro de él la URL temporal que YUPY creó para una transacción específica.

Servidor de la empresa
    → solicita la pantalla
    → recibe checkout_url

Frontend de la empresa
    → entrega checkout_url al SDK

SDK
    → abre una ventana segura
    → carga el contenido desde YUPY

YUPY
    → sabe qué transacción corresponde
    → muestra el contenido adecuado
    → actualiza el estado

La URL estándar

YUPY debe devolver una URL completa, estable en su estructura y variable en su token.

Forma conceptual:

https://<YUPY_CHECKOUT_HOST>/checkout/<OPAQUE_TOKEN>

También sería técnicamente posible usar un parámetro:

https://<YUPY_CHECKOUT_HOST>/checkout?token=<OPAQUE_TOKEN>

La forma definitiva se decidirá durante la implementación. Para el integrador no debe existir diferencia: YUPY devuelve checkout_url completa y la plataforma usa exactamente ese valor.

Por qué se devuelve la URL completa

• permite cambiar rutas internas sin romper al integrador;
• evita errores al codificar el token;
• permite aplicar versiones y dominios distintos;
• facilita migraciones de infraestructura;
• mantiene la generación y seguridad bajo control de YUPY.

Qué representa el token

El token es una credencial opaca y temporal vinculada con una sesión.

external_transaction_id
        ↔
yupy_transaction_id
        ↔
checkout_session_id
        ↔
opaque token dentro de checkout_url

El token permite que YUPY resuelva:

• monto y moneda;
• empresa y marca;
• comprador, cuando corresponda;
• perfil de cobro;
• QR y cuenta habilitados;
• idioma y presentación;
• vigencia;
• estado actual;
• resultado de conciliación.

El token no debe contener esos valores de forma legible ni permitir inferir otras transacciones.

El SDK

La empresa carga una biblioteca JavaScript estable y versionada.

<script src="<YUPY_SDK_URL>/v1/yupy-checkout.js"></script>

Luego entrega la URL a la biblioteca.

Montaje dentro de un contenedor

<div id="yupy-payment"></div>

<script>
  const checkout = YupyCheckout.mount({
    container: "#yupy-payment",
    checkoutUrl: "<CHECKOUT_URL_RETURNED_BY_YUPY>"
  });
</script>

Apertura como modal

const checkout = YupyCheckout.open({
  checkoutUrl: "<CHECKOUT_URL_RETURNED_BY_YUPY>"
});

Los nombres YupyCheckout.mount, YupyCheckout.open y checkoutUrl son propuestas de API pública.

Implementación interna probable

El SDK puede crear un iframe seguro que cargue checkout_url.

YupyCheckout.mount(...)
    → valida configuración
    → crea iframe
    → carga checkout_url
    → valida origen
    → escucha eventos permitidos
    → comunica eventos a la página

La plataforma no necesita crear ni administrar el iframe manualmente.

Qué controla la empresa

• dónde se coloca el contenedor;
• cuándo se abre;
• cuándo se cierra visualmente;
• dimensiones permitidas;
• idioma o perfil visual cuando el contrato lo admita;
• qué hace su página ante los eventos visuales;
• cómo actualiza su propia interfaz.

Qué controla YUPY

• contenido interno;
• QR y cuentas habilitados;
• monto mostrado;
• nombre receptor;
• instrucciones;
• estado de espera;
• acción “Ya pagué”;
• verificación;
• mensajes de diferencia;
• vencimiento;
• confirmación;
• errores financieros y operativos.

La empresa integra la ventana. YUPY administra la experiencia dentro de ella.

Contenido evolutivo

YUPY puede mejorar textos, orden, diseño y secuencia sin exigir que el integrador cambie su frontend.

También puede mostrar nuevos medios de pago cuando estén:

• implementados;
• habilitados para la empresa;
• incluidos en su perfil de cobro;
• cubiertos por un contrato compatible;
• verificados para producción.

Actualmente la ventana se documenta para Yape QR, Plin QR y transferencia bancaria opcional.

Eventos visuales

El SDK debe exponer un conjunto pequeño y estable.

checkout.ready
checkout.opened
checkout.closed
payment.reported
payment.processing
payment.reconciled
payment.amount_difference
payment.expired
checkout.error

Ejemplo conceptual:

const checkout = YupyCheckout.mount({
  container: "#yupy-payment",
  checkoutUrl: checkoutUrl,
  onEvent(event) {
    if (event.type === "payment.reconciled") {
      showPaymentConfirmation();
    }
  }
});

El callback no sustituye al webhook

Los eventos del SDK ayudan a actualizar el navegador. Pueden perderse por cierre de pestaña, pérdida de conexión, bloqueo del navegador o navegación.

Evento del SDK
→ actualiza la experiencia visual

Webhook server-to-server
→ actualiza de forma confiable la operación comercial

La empresa no debe emitir una factura, liberar un producto o cerrar definitivamente una reserva usando únicamente un callback del navegador.

Recarga y reapertura

Al reabrir la misma URL:

• si la sesión sigue activa, se muestra su estado actual;
• si fue conciliada, se muestra el resultado;
• si venció, se muestra vencimiento;
• si existe un pago tardío, se muestra el estado definido;
• si fue cancelada, no se reactiva;
• si el token es inválido, se muestra un error seguro.

Reabrir la URL no debe crear una nueva orden.

Varias pestañas o dispositivos

YUPY mantiene un estado central. Varias ventanas pueden reflejar el mismo resultado, pero el backend de la empresa debe depender del webhook y no de una pestaña específica.

Cierre de la ventana

El SDK puede ofrecer:

checkout.close()
checkout.unmount()

Cerrar la ventana no cancela automáticamente la orden, no detiene la conciliación y no impide detectar un pago posterior.

Seguridad

La implementación deberá contemplar:

• HTTPS;
• token opaco y temporal;
• validación de origen;
• iframe aislado cuando corresponda;
• mensajes con origen validado;
• restricción de acciones por sesión;
• protección contra inyección;
• no exposición de secretos backend;
• política de referencia restrictiva;
• prevención de filtración a analítica y terceros;
• revocación y expiración;
• logs con el token redactado.

Compatibilidad y versiones

Dentro de una misma versión, YUPY puede cambiar el contenido interno sin romper:

• URL o mecanismo de apertura publicado;
• métodos públicos del SDK;
• configuración aceptada;
• nombres y significado de eventos;
• requisitos de seguridad;
• compatibilidad de navegadores declarada.

Un cambio incompatible requiere una nueva versión del SDK.

Errores mínimos

El SDK debe manejar:

• biblioteca no cargada;
• contenedor inexistente;
• URL ausente o inválida;
• token vencido;
• sesión inexistente;
• sesión cancelada;
• pérdida de conexión;
• servidor temporalmente no disponible;
• origen no autorizado;
• navegador no compatible.

Criterios de aceptación

1. YUPY devuelve checkout_url completa.
2. La plataforma no construye la URL.
3. El token es opaco y temporal.
4. La URL resuelve una sola sesión.
5. El SDK acepta la URL devuelta.
6. El SDK puede abrir modal o contenedor.
7. YUPY controla el contenido interno.
8. La empresa controla únicamente el contenedor y comportamiento externo permitido.
9. El SDK emite eventos documentados.
10. Los mensajes validan origen.
11. Los callbacks no sustituyen el webhook.
12. Reabrir no crea otra orden.
13. Cerrar no altera la realidad financiera.
14. El token se redacta en logs.
15. Los cambios incompatibles usan nueva versión.

Resumen

Servidor del cliente pide una pantalla.
YUPY crea una sesión.
YUPY devuelve una URL completa con token opaco.
El frontend entrega esa URL al SDK.
El SDK abre una ventana temporal hacia YUPY.
YUPY administra lo que aparece dentro.
YUPY detecta y concilia por detrás.
El webhook confirma el resultado al servidor del cliente.