Entiende el flujo de pago y los requisitos
Si quieres aprender cómo aceptar pagos en criptomonedas con Next.js, empieza por el flujo, no por el código. Un checkout con cripto suele tener 4 partes: crear un pedido, mostrar una solicitud de pago, vigilar la blockchain y marcar el pedido como pagado solo después de verificarlo.
Parece sencillo. Rara vez lo es.
“Aceptar cripto” en un sitio de Next.js no significa que tu app guarde monedas. En la mayoría de los casos, tu sitio crea una solicitud de pago para un cliente, el cliente envía los fondos desde una wallet y un servicio de pago o tu propio backend confirma la transferencia. Un buen checkout también necesita un tiempo de expiración, porque una cotización justa a las 10:00 puede dejar de serlo 20 minutos después.
También necesitas saber qué redes y activos vas a admitir. Una tienda que acepta USDT en Ethereum, Polygon y BNB Chain no hace lo mismo que un sitio que solo acepta BTC en una sola cadena. La elección de la red afecta las comisiones, el tiempo de confirmación y el tipo de wallet que necesita tu cliente. Si aceptas la red equivocada, el pago puede acabar en un lugar que no puedes vincular con un pedido.
Hay una prueba práctica aquí: ¿puede un cliente nuevo completar el pago en menos de 2 minutos? Si la respuesta es no, el flujo necesita mejoras. Una wallet, un importe, una dirección clara, una página de estado clara. Ese es el nivel de claridad que la gente espera.
Elige un proveedor de pagos cripto o una integración con wallet
Puedes crear un checkout cripto de 3 formas generales. La primera, un checkout alojado por un proveedor. La segunda, una integración directa con wallet, donde tu app habla con una biblioteca de wallets. La tercera, una pasarela de pago que se sitúa entre el usuario y la cadena. Cada opción tiene un coste de implementación distinto, y la respuesta correcta depende de si buscas velocidad, control o ambas cosas.
Un checkout alojado suele ser la forma más rápida de lanzar. Creas una factura, envías al cliente a una página alojada y el proveedor se encarga de detectar el pago. Una integración directa con wallet puede sentirse más integrada dentro de tu producto, pero normalmente implica más código, más casos límite y más responsabilidad a la hora de confirmar pagos. Una pasarela se sitúa en el medio y a menudo es la opción práctica para comercio, porque puede crear facturas, seguir confirmaciones y exponer webhooks.
Revisa 5 cosas antes de elegir: monedas admitidas, cadenas admitidas, soporte para webhooks, caducidad de la factura y cuánto código de backend espera que escribas el proveedor. Si estás comparando opciones para una tienda, la guía sobre la pasarela de pago cripto para ecommerce es un buen punto de partida porque plantea la misma decisión desde el punto de vista del vendedor. Un freelancer que factura a clientes puede preocuparse más por facturas y enlaces de pago que una tienda online, por eso también importa el enfoque de la pasarela de pago cripto para freelancers. Además, si tu objetivo es integrar pagos cripto en Next.js, conviene elegir un proveedor que se adapte bien a rutas del servidor, webhooks y confirmaciones idempotentes.
Un apunte: si un proveedor dice que admite “todos los activos principales”, pídele una lista precisa. “Todos” es vago. “BTC, ETH y USDC en 3 redes” es una decisión sobre la que sí puedes actuar.
Prepara tu proyecto de Next.js para pagos
Empieza con una estructura limpia de la app. En un proyecto de Next.js con app router, coloca la lógica de pagos en rutas del servidor o server actions, y mantén las claves secretas fuera del cliente. Una estructura sencilla podría incluir 1 página de producto, 1 formulario de pago, 1 ruta API para crear facturas y 1 ruta webhook para eventos de pago.
Las variables de entorno deben cubrir la clave secreta del proveedor de pagos, el secreto del webhook y los valores públicos de la API que se puedan exponer en el navegador. No pongas la clave secreta en un componente de cliente. Ese error puede comprometer toda la cuenta, y es uno de los pocos fallos que sale caro muy rápido.
Si tu proveedor ofrece un SDK, instálalo solo en la capa del servidor. Si ofrece endpoints HTTP simples, también funciona. La idea principal es la misma: el navegador le pide a tu backend de Next.js que cree una solicitud de pago, y el backend habla con el proveedor. El navegador nunca debe decidir que un pedido ya está pagado.
Para los equipos que vienen de pagos con tarjeta, la estructura no es muy diferente de un flujo de Stripe, solo que con pasos de verificación distintos. Si esa comparación te ayuda, lee cómo migrar desde Stripe antes de definir las rutas API. Una ruta API basta para un prototipo; 3 o 4 pueden ser mejores cuando añades reintentos, reembolsos e historial del estado del pedido.
Crea la interfaz de checkout en Next.js
La interfaz de checkout puede ser una tarjeta de producto, una página de carrito o un botón sencillo que inicie un pago. En un componente de cliente de Next.js, el botón suele enviar los datos del pedido a tu ruta del servidor, esperar la respuesta y luego redirigir al cliente o mostrar instrucciones para la wallet.
Mantén el formulario corto. Nombre del producto, importe, correo electrónico y quizá una nota del pedido suelen ser suficientes. Si pides 9 campos, espera más abandono. Si pides 3, la gente termina más rápido. Un checkout que tarda 30 segundos se siente mejor que uno que tarda 3 minutos, aunque ambos acaben con el mismo pago.
Para un botón de pago, la acción del usuario debe quedar clara: “Pagar con cripto”. No “Continuar” ni “Seguir”. Esas etiquetas ocultan el coste del siguiente paso. Cuando se pulse el botón, llama a tu backend, obtén la solicitud de pago y muestra la dirección de la wallet, el código QR y el importe en la misma vista.
Un patrón útil es mantener visible el resumen del pedido mientras se cargan las instrucciones de pago. Así el cliente ve juntos el artículo exacto y el importe exacto. Reduce la confusión cuando el valor del pago está fijado en USD pero se abona con un activo volátil. Si buscas un enfoque más orientado a comercio, esta misma interfaz puede funcionar como checkout de criptomonedas para ecommerce sin añadir pasos innecesarios.
Genera direcciones de pago, facturas o enlaces de pago
Cada pedido debería corresponder a 1 solicitud de pago única. Puede ser una dirección de wallet, un enlace de pago o un objeto de factura de tu proveedor. Reutilizar la misma dirección para cada cliente complica la conciliación y puede generar un trabajo de soporte que no quieres tener.
Para una tienda pequeña, podrías generar una dirección nueva por pedido y guardar la dirección, el importe esperado, el activo y la fecha de expiración en tu base de datos. En un flujo basado en proveedor, este puede devolver un ID de factura y un enlace de pago alojado en lugar de una dirección. En cualquier caso, vincula la solicitud de pago con el ID del pedido antes de que el cliente la vea.
Muestra los detalles al cliente de forma clara: activo, cadena, importe y destino. Un código QR ayuda, pero no debe sustituir al texto. Algunas wallets leen mal los QR; algunos usuarios copian y pegan manualmente. Una dirección clara sigue siendo la red de seguridad.
Si necesitas admitir facturación basada en direcciones para servicios o facturas, los patrones se parecen a los del artículo sobre la pasarela de pago cripto para freelancers. Un enlace de pago suele ser más fácil para pedidos puntuales; un registro de factura dedicado funciona mejor cuando necesitas historial de pagos y recordatorios.
Confirma los pagos en blockchain y actualiza el estado del pedido
La confirmación del pago es donde muchos equipos se descuidan. No marques un pedido como pagado cuando una wallet solo muestra una transferencia pendiente. No confíes solo en el navegador. Tu backend debe verificar la transacción comprobando la cadena directamente o recibiendo un webhook firmado del proveedor de pagos.
El flujo habitual es sencillo. El proveedor detecta el pago, envía un webhook a tu ruta de Next.js y tu servidor verifica la firma antes de cambiar el estado del pedido. Si implementas ese paso por tu cuenta, debes comprobar el hash de la transacción, la dirección de destino, el activo, el importe y el número de confirmaciones que exige tu política. Un pago puede parecer real antes de ser definitivo.
Usa un modelo de pedido de 3 estados: pendiente, confirmado, pagado. Pendiente significa que la solicitud existe. Confirmado significa que la cadena detectó el pago y tiene suficientes confirmaciones. Pagado significa que tu app ha actualizado la entrega o el control de acceso. Mantén esos estados separados, porque un agente de soporte necesita saber si el cliente está esperando, verificado o ya recibió lo correspondiente.
Si los webhooks forman parte de tu stack, valídalos siempre. El artículo sobre cómo verificar webhooks firmados de Payora es útil incluso si no usas PHP, porque la idea principal es la misma: rechazar mensajes que no demuestran que vienen del proveedor. Esa única comprobación puede detener en seco eventos falsos de pago.
Gestiona casos límite, seguridad y pruebas
El checkout cripto falla de más formas que el checkout con tarjeta. Una cotización puede caducar. Un cliente puede enviar fondos en la red equivocada. Una wallet puede pagar de menos por una pequeña cantidad. Un navegador puede recargarse a mitad del proceso. Cada caso necesita una respuesta, y cada una debe llevar al usuario a 1 siguiente paso.
Las cotizaciones caducadas no deberían quedarse en el limbo. Si un enlace de pago tiene una validez de 15 minutos, muestra ese temporizador con claridad y crea una solicitud nueva cuando expire. Las transferencias a la red incorrecta necesitan una vía de soporte, porque el dinero puede existir pero no estar donde tu app espera. Los pagos incompletos pueden aceptarse, rechazarse o marcarse para revisión, pero tu política debe estar escrita antes del lanzamiento, no después de la primera queja.
La seguridad no es opcional. Mantén las claves secretas en variables de entorno solo para servidor. Verifica las firmas de los webhooks. Guarda solo los datos mínimos de pago que necesites. Si registras IDs de transacción, oculta cualquier dato sensible que no sea necesario para depurar. Prueba en testnet o con las herramientas sandbox del proveedor antes de recibir tráfico real. Si quieres una lista práctica, mira cómo probar un pago cripto antes de conectar una wallet real.
No olvides los eventos duplicados. Algunos proveedores reintentan webhooks, y las cadenas pueden mostrar el mismo pago más de una vez en tu sistema si no tienes cuidado. Tu código de actualización de pedidos debe ser idempotente, es decir, que el mismo evento no marque el mismo pedido como pagado dos veces. Esa sola defensa ahorra horas.
Lanza, supervisa y mejora la experiencia de checkout
El despliegue en Vercel o en un host similar suele funcionar bien para Next.js, pero las partes de pago siguen necesitando atención. Asegúrate de que tu endpoint de webhook sea accesible públicamente, de que las variables de entorno estén configuradas en producción y de que tu build no dependa de valores que solo existen en local. Una ruta de pago que funciona en tu portátil y falla en producción es un error clásico.
El registro de eventos importa mucho aquí. Registra la creación de facturas, la recepción de webhooks, los resultados de verificación y los cambios de estado. Usa suficiente detalle para seguir un pedido del principio al final, pero no vuelques secretos en los logs. Si un cliente dice que pagó a las 14:32, deberías poder encontrar el evento correspondiente en segundos, no en horas.
Pequeños cambios de UX pueden reducir la fricción más de lo que la gente espera. Muestra el importe dos veces: una en el resumen del pedido y otra en el paso de pago. Mantén visible el botón de pago después de cargar la factura. Añade un botón de copiar junto a la dirección. Muestra con claridad el paso de confirmación, porque los usuarios suelen recargar la página mientras esperan. Una actualización de estado de 5 segundos puede parecer de 5 minutos si la página está en silencio.
A partir de aquí, el verdadero trabajo no es el primer pago. Es el segundo, el tercero y el que falla justo en el límite entre una wallet, una cadena y tu backend de Next.js. Si tu sistema puede manejar esos 3 casos con claridad, tendrás un checkout en el que los clientes pueden confiar.
Comentarios