El checkout · Payment Emulator Lab

Traducción de docs/en/frontend/checkout.md, que es el original. Si discrepan, manda el inglés.

apps/checkout es lo que ve un comprador. Es una aplicación Nuxt separada de la consola a propósito: otra persona, otra superficie, otra sesión sellada con otro secreto. Un solo secreto haciendo los dos trabajos dejaría que una cookie fuera la otra.

Es pública. No hay ningún token de operador dentro, y desde ella no se alcanza ninguna ruta del plano de control.

#Por qué lleva la cara de cada proveedor

Quien integra una pasarela tiene que reconocer lo que verá su comprador. Un formulario genérico con el nombre del proveedor en una esquina no enseña nada sobre la redirección, la lista de métodos ni el flujo — y este proyecto existe para que una integración construida contra el emulador sobreviva al contacto con lo real.

Así que un proveedor tiene dos mitades, y nunca se importan:

Mitad	Vive en	Contiene
Comportamiento	`apps/api/src/providers/<id>/`	Rutas, validación, vocabulario de estados, firma
Identidad	`apps/checkout/providers/<id>/`	El kit visual: el componente y su tema

Lo que el checkout necesita saber de un proveedor —nombre visible, métodos de pago, estados canónicos— lo lee de la API en ejecución. Nunca de un tipo compartido, porque un tipo compartido convertiría el reparto en un formalismo.

#Su forma

app/
  pages/
    mercadopago/checkout/[resourceId].vue   las rutas que usan los proveedores reales
    paypal/checkoutnow.vue
    stripe/c/pay/[resourceId].vue
  components/          el armazón: resumen, métodos, pagador, desenlace
  core/gateway.ts      lo que la API dice de este checkout
  core/kits.ts         identificador de proveedor → kit visual
providers/
  mercadopago/         Checkout.vue + theme.css
  stripe/              Checkout.vue + theme.css + logo.svg
  paypal/              Checkout.vue + theme.css + logo.svg

core/kits.ts es el registro, y es la razón de que ningún componente compartido ramifique sobre el identificador de un proveedor. Un proveedor sin kit cae al formulario llano del armazón — un checkout usable, no una página en blanco.

Son rutas locales inspiradas en los proveedores. Un PaymentIntent de Stripe no es una Checkout Session, y una Order de Mercado Pago no es una preferencia. Estas páginas no demuestran compatibilidad con sus SDK o redirecciones alojadas. PayPal tiene un kit de revisión y aprobación en /paypal/checkoutnow?token=.... Aprobar no mueve dinero; los enlaces de retorno y cancelación proceden de la API. Véase su fidelidad.

Stripe muestra resumen y tarjeta en dos columnas, apiladas en móvil. Mercado Pago utiliza cabecera azul/blanca y opciones de pago apiladas. Los datos de tarjeta son de solo lectura; IDs y rechazos deliberados quedan en detalles desplegables. Stripe no ofrece Link ni ACH, y los métodos regionales de Mercado Pago dependen del sitio configurado. La sesión aparece al elegir saldo interno. No se afirma igualdad píxel a píxel con todas las variantes de país o cuenta.

#Reglas

Aquí no hay PrimeVue. PrimeVue es el sistema de diseño de la consola. Una página de cara al comprador que heredara la librería de componentes de un panel de administración parecería un panel de administración, y el kit de cada proveedor no podría ser él mismo. El checkout se peina solo.
La API es el único contrato. Métodos de pago, moneda, importes y estado vienen de consultar el checkout; nada se fija en el código por proveedor fuera de su kit.
Los textos están en español e inglés, en el diccionario tipado propio del checkout. El código y los comentarios, en inglés.
La accesibilidad no es opcional. La lista de métodos es un role="radiogroup" que se maneja con las flechas, cada control tiene un <label> de verdad, el foco se ve, y los objetivos táctiles miden al menos 44 px. Un formulario de pago que no se puede completar con el teclado es un formulario de pago roto.

#La sesión del comprador

Un comprador entra con su propio correo y contraseña contra la API, igual que una persona en la consola — la diferencia es el rol. Un customer llega al checkout y no a la consola; eso lo decide la API, no la interfaz.

Pagar con saldo debita el libro mayor; pagar con tarjeta, ticket o transferencia mete dinero desde fuera. Cuál de las dos cosas hace un método es el funding_source que se anota con el pago, para que una devolución meses después no dependa de que la lista de métodos de un plugin siga diciendo hoy lo mismo.

#Relacionado

Flujos de petición críticos — el camino de la confirmación del checkout, de punta a punta.
Modelo de proveedor — de qué es dueño un plugin.
Banco falso y libro mayor — qué escribe realmente un pago.

Los tres kits incluyen una copia del SVG de su carpeta de llms. La guía de iconos también cubre tarjetas y selectores de la consola.

#Idioma y aviso de simulación

app/core/i18n/checkout.ts contiene los textos ES/EN de los tres kits, métodos, sesión opcional, resultados, errores y títulos. Los nombres de marcas, referencias, importes y estados técnicos recibidos de la API conservan su valor original.

El idioma se resuelve en servidor: ?lang=es|en → cookie emulator_checkout_locale → Accept-Language (regiones y pesos q) → es. Nuxt serializa la resolución para que la hidratación use el mismo idioma. El selector ES/EN escribe una cookie de un año, SameSite=Lax, ruta /, y actualiza lang conservando los demás parámetros, incluido el token de PayPal. La cookie es independiente de la consola y el atributo HTML lang se actualiza.

CheckoutFrame muestra un <aside> estático antes del kit con los tokens --caution-*: «Estos pagos son ficticios.» y la instrucción de no introducir datos reales. No usa role="alert". También aparece en el índice y las páginas de error.

La marca de agua es un SVG de dos líneas, rotado −30°, codificado completo con encodeURIComponent, y servido mediante --wm. La baldosa parte de 420 × 260 px y crece con la longitud de la traducción. Se repite como máscara CSS en .checkout::before, con opacidad 0.07 y color --wm-color: permite cambiar el color desde CSS, algo que un SVG en background-image no puede heredar. No añade nodos DOM, no recibe eventos ni tapa los paneles opacos. Un kit puede matizarla con .checkout:has(.kit-<id>) { --wm-color: ... } en su propio theme.css. En móvil el aviso visible mantiene el mensaje aunque la tarjeta cubra el fondo.

Validación: npm run test:checkout cubre negociación, paridad de diccionarios y codificación SVG. El arnés scripts/checkout-browser.mjs comprueba SSR, hidratación, cambio de idioma, desbordamiento y axe; guarda capturas de los tres kits en ambos idiomas, en escritorio y móvil. Necesita Playwright, axe y una pila local en marcha. npm run smoke:stack valida el flujo de pago completo.