Cómo mostrar un checkout de pagos QR en React

Incorporar pagos con código QR en tu aplicación React es más sencillo de lo que imaginas. Con herramientas como Checkout.js, puedes renderizar un checkout pagos QR React de forma rápida y segura, permitiendo que tus clientes paguen con Yape, Plin y cualquier billetera interoperable sin salir de tu plataforma. En esta guía te explicamos cómo integrar el checkout de una pasarela peruana en tu frontend React y manejar el estado del pago en tiempo real.

¿Por qué integrar pagos QR en tu app React?

Los pagos con QR interoperable están transformando el e-commerce y el comercio digital en Perú. Para los desarrolladores frontend, ofrecer un flujo de pago que no requiera redirigir a páginas externas ni depender de capturas de pantalla es una ventaja enorme.

Con un checkout pagos QR React, obtienes:

Cero contracargos, porque el pago se realiza directamente desde la billetera del cliente, sin procesar tarjetas.
Verificación bancaria en tiempo real: el pago se confirma de inmediato, sin validación manual.
Experiencia nativa: el usuario escanea el código QR desde tu propia interfaz y paga en segundos.
Compatibilidad total: aceptas Yape, Plin y cualquier billetera conectada a la interoperabilidad del BCRP a través de la Cámara de Compensación Electrónica (CCE).

Al eliminar las “capturas falsas” y las confirmaciones tardías, el checkout QR mejora la conversión y reduce la fricción. Si ya tienes un backend en Node.js, PHP o .NET, integrar un checkout de pagos QR en React te permite ofrecer un flujo de pago moderno que cumple con la regulación peruana de prevención de lavado de activos (PLAFT) y está respaldado por la infraestructura supervisada por la SBS.

Aprende qué son los pagos QR interoperables y por qué están cambiando el comercio peruano.

El flujo de un checkout pagos QR React paso a paso

Antes de escribir código, conviene entender el recorrido completo de un cobro con QR. La integración se divide en tres partes:

Tu backend crea el cobro: mediante una API REST (o usando el SDK de JavaScript/TypeScript) generas un cobro único con monto fijo y referencia. La respuesta incluye un checkout_url y la imagen del QR dinámico, que expira en 15 minutos.
El frontend React muestra el checkout: puedes cargar Checkout.js (que renderiza el QR y el estado automáticamente) o redirigir al checkout_url si prefieres un enfoque más simple.
Confirmación por webhook: la pasarela envía una notificación en tiempo real a un endpoint de tu backend cuando el pago se acredita. Tu frontend puede entonces reflejar el éxito o el fallo.

Este flujo aprovecha la idempotencia de la API, evitando cobros duplicados, y utiliza firmas HMAC-SHA256 para garantizar la integridad de cada solicitud. La pasarela no procesa tarjetas, solo billeteras, por lo que cada transacción es definitiva y no genera contracargos.

Profundiza en la seguridad de los pagos digitales y qué debe cumplir tu comercio.

Cómo mostrar el checkout QR en React con Checkout.js

Checkout.js es un script ligero que encapsula toda la lógica del frontend de pago: genera el QR dinámico, muestra instrucciones para el usuario y actualiza el estado automáticamente. En React, puedes integrarlo en un componente funcional con useEffect y un ref.

Aquí tienes un esquema típico de integración (el código exacto debes consultarlo en la documentación de tu pasarela, pero el patrón es similar):

import { useEffect, useRef } from 'react';

const QrCheckout = ({ paymentId, token, containerId }) => {
  const containerRef = useRef(null);

  useEffect(() => {
    // Cargar el script de Checkout.js dinámicamente
    const script = document.createElement('script');
    script.src = 'https://cdn.taypi.pe/checkout.js'; // ejemplo de ruta
    script.async = true;
    script.onload = () => {
      // Inicializar el checkout en el contenedor
      if (window.Checkout) {
        window.Checkout.render({
          container: `#${containerId}`,
          payment_id: paymentId,
          token: token,
          // opciones adicionales: idioma, tema, etc.
        });
      }
    };
    document.body.appendChild(script);

    return () => {
      document.body.removeChild(script);
    };
  }, [paymentId, token, containerId]);

  return <div id={containerId} ref={containerRef} />;
};

Algunos puntos importantes:

El paymentId y el token los obtienes desde tu backend después de crear el cobro.
El script de Checkout.js se encarga de mostrar el QR y de gestionar el temporizador de expiración (15 minutos).
Puedes escuchar eventos del checkout para reaccionar a cambios de estado, aunque la confirmación final siempre la recibirás vía webhook en tu servidor.

Si prefieres no usar un script externo, puedes redirigir al checkout_url que devuelve la API. Sin embargo, Checkout.js te da una experiencia más integrada, sin sacar al usuario de tu app React.

Manejando el estado del pago en tiempo real

Una vez que el cliente escanea y paga, el estado del cobro debe reflejarse en tu interfaz. La pasarela notifica a tu backend mediante un webhook en tiempo real con la confirmación bancaria. Tu trabajo como desarrollador frontend es mostrar ese resultado.

El enfoque recomendado es:

Tu backend expone un endpoint de consulta de estado (por ejemplo, GET /api/payments/:id). Este endpoint devuelve si el pago está pendiente, confirmado o expirado.
El frontend realiza un polling periódico (cada 3-5 segundos) mientras el QR esté activo. Cuando el estado cambia a “confirmado”, muestras la pantalla de éxito.
Alternativa más avanzada: implementar WebSockets o Server-Sent Events (SSE) para que el backend empuje la actualización al frontend. Esto reduce las consultas innecesarias pero requiere infraestructura adicional.

Recuerda que el QR dinámico expira a los 15 minutos. Si el usuario no ha pagado en ese lapso, debes mostrar un mensaje de vencimiento y ofrecer la opción de generar un nuevo cobro. Con Checkout.js, la expiración se maneja automáticamente; si construyes tu propia UI, deberás controlar ese temporizador en tu componente React.

Descubre cómo funcionan los webhooks de pago en tiempo real y cómo integrarlos.

Comparativa: integración con Checkout.js vs. redirección al checkout_url

Característica	Checkout.js (embebido)	Redirección al checkout_url
Experiencia de usuario	Se mantiene dentro de tu app React	El usuario sale de tu dominio
Personalización visual	Limitada al tema del script	Puede ser más genérica
Tiempo de implementación	Mínimo, casi plug & play	Aún más rápido, solo un enlace
Control del flujo post-pago	Depende de eventos del script y polling	Depende de webhooks y URL de retorno
Ideal para	Aplicaciones SPA que quieren retener al usuario	Sitios web con menos énfasis en UX nativa

Si tu prioridad es una integración rápida y profesional sin construir todo el frontend desde cero, Checkout.js es la opción más eficiente. Te permite añadir un checkout pagos QR React con pocas líneas de código y con el respaldo de la seguridad de la pasarela.

Mejores prácticas para un checkout pagos QR React seguro y rápido

Independientemente de si usas Checkout.js o una implementación personalizada, sigue estas recomendaciones:

Nunca expongas tus claves secretas en el frontend. La creación del cobro siempre debe hacerse desde tu backend, con autenticación HMAC-SHA256.
Habilita la idempotencia. Así evitas que un mismo cobro se procese dos veces si el usuario recarga la página.
Usa el entorno sandbox durante el desarrollo. La pasarela proporciona claves de prueba para que puedas simular pagos sin mover dinero real.
Controla la expiración del QR. Muestra siempre un contador regresivo de 15 minutos y bloquea el pago si se vence.
Optimiza para móviles. La mayoría de tus clientes pagará desde un celular; el QR debe ser legible y la interfaz, responsiva.
Valida siempre la confirmación en tu backend. No confíes solo en eventos del frontend; el webhook es la fuente de verdad.

Conoce la importancia de la idempotencia en APIs de pago y cómo implementarla.

Preguntas frecuentes

¿Qué es Checkout.js y cómo funciona?

Checkout.js es una biblioteca JavaScript que te permite embeber el flujo de pago con QR directamente en tu sitio o aplicación web. Recibe un identificador de cobro y un token desde tu backend, y renderiza automáticamente el código QR dinámico junto con las instrucciones para el usuario. Se encarga además de mostrar el estado del pago y manejar la expiración del QR.

¿Puedo personalizar el diseño del checkout QR?

Checkout.js ofrece opciones básicas de personalización (como colores y logotipo) según la configuración de tu comercio en la plataforma de la pasarela. Si necesitas un control total del diseño, puedes usar la imagen del QR que devuelve la API y construir tu propia interfaz en React, aunque eso implica programar también la lógica de expiración y el polling del estado.

¿Cómo manejo la expiración del QR de 15 minutos en React?

Si usas Checkout.js, el temporizador y la invalidación del QR se gestionan automáticamente. Si optas por una UI personalizada, debes guardar la fecha de creación del cobro y restarle la fecha actual en intervalos de 1 segundo usando setInterval. Cuando el tiempo restante llegue a cero, deshabilitas el escaneo y muestras un aviso al usuario.

¿Es seguro integrar pagos QR en mi aplicación React?

Sí, siempre que sigas las prácticas recomendadas. La seguridad no depende de React sino de cómo gestionas las claves, la creación de cobros desde el backend y la verificación de las notificaciones de pago. La pasarela utiliza cifrado TLS 1.3, firmas HMAC-SHA256 y QR de un solo uso, además de cumplir con la normativa PLAFT y operar sobre la infraestructura supervisada por la SBS.

¿Cómo verifico que el pago se realizó correctamente?

La confirmación oficial llega a tu backend mediante un webhook. Tu frontend puede obtener el estado actual consultando un endpoint de tu API que refleje esa información. Nunca debes considerar un pago como exitoso basándote solo en lo que muestra el frontend, ya que podría manipularse. El webhook es la única confirmación válida.

Conclusión

Integrar un checkout pagos QR React en tu aplicación es un proceso directo con las herramientas adecuadas. Checkout.js te ahorra tiempo de desarrollo y te proporciona una experiencia de pago segura y fluida para tus usuarios, mientras que el backend se encarga de la creación del cobro y la confirmación vía webhook.

Si buscas una pasarela de pagos peruana que ofrezca QR interoperable, cero contracargos, activación inmediata y una integración pensada para developers, considera explorar TAYPI. Puedes empezar hoy mismo desde su documentación para desarrolladores y tener un checkout funcional en cuestión de horas.

Explora la documentación técnica y comienza tu integración.

¿Listo para implementar pagos QR en tu app React sin fricciones? Crea tu cuenta gratis en TAYPI y accede al entorno sandbox para empezar a probar.

¿Listo para cobrar con QR?

Crea tu cuenta gratis y genera tu primer QR en minutos.

Abrir cuenta gratis