Pagos con criptomonedas en PrestaShop

El módulo de CryptoLike agrega «Pagar con cripto» a tu tienda online en PrestaShop y pasa el pedido a «Pago aceptado» solo cuando el pago se confirma en la blockchain. Después, PrestaShop registra el pago y, si las usas, la factura. Tus clientes pagan en Bitcoin, USDT, Ethereum, Litecoin, TRON o USDC desde su propia billetera.

#Requisitos

El módulo es compatible con PrestaShop 8.x y declara 1.7.8 como versión mínima. Se probó de principio a fin en PrestaShop 8.1 con PHP 8.1; en 1.7.8 necesita PHP 7.4 o posterior. La tienda debe estar accesible desde internet por https:// para que lleguen los webhooks. El endpoint de webhook no necesita sesión ni cookie y también responde en modo de mantenimiento.

#Qué hace el módulo

Al instalarse, el módulo crea tres estados de pedido propios: Esperando pago con cripto (la página de pago está abierta o la transferencia se está confirmando), Pago con cripto insuficiente (un pago insuficiente que el cliente todavía puede completar) y Revisión del pago con cripto (dinero que requiere la decisión de una persona). Los pedidos pagados pasan al estado Pago aceptado de PrestaShop; los vencidos y cancelados, a Cancelado. Puedes cambiar cada uno en la configuración.

• Redirección o página integrada. El cliente va a la página de pago de CryptoLike o la ve dentro de la página de estado del pedido de la tienda.
• Una página de estado para el cliente, enlazada desde los detalles de su pedido: «Pago detectado. Esperando confirmación.», «Pago confirmado.», cuánto falta después de un pago insuficiente y el botón Crear un pago nuevo cuando el pago venció.
• Un mensaje privado en el pedido en cada paso: pago creado, ID de la transacción, monto pagado, pago excedente y qué hacer en revisión.
• Un solo pago abierto por pedido. Si el cliente recarga la página o vuelve a hacer clic, recibe la misma página; si se edita el total del pedido, la página anterior se cancela y se crea una nueva.
• Elección de moneda en la página de pago de CryptoLike o en el paso de pago de la tienda. Monedas ofrecidas limita ambas opciones; en la página de pago, sin selección significa todas las monedas disponibles para facturas en tu cuenta.
• Una URL de conciliación para el cron del servidor, por si un webhook no logró llegar a la tienda.

#1. Instala el módulo

En el back office abre Módulos → Gestor de módulos → Subir un módulo, elige el archivo del módulo que está en esta página y haz clic en Configurar. También puedes descomprimir el zip en modules/ e instalar CryptoLike: pagos con cripto desde la lista. El módulo crea sus tablas y sus tres estados de pedido.

#2. Conecta tu cuenta de CryptoLike

En el panel de CryptoLike abre Desarrolladores → Claves API → Crear clave con los permisos create_invoice y read, y pega el ID de la clave y el secreto en la configuración del módulo; el secreto se muestra una sola vez. Copia la URL del webhook desde la página de configuración (https://shop/module/cryptolike/webhook), agrégala en el panel en Desarrolladores → Webhooks → Agregar endpoint con los ocho eventos invoice.* y pega el secreto del endpoint en Secreto del webhook.

#3. Comprueba la conexión y empieza a cobrar

Haz clic en Comprobar la conexión: verás «Conectado: N monedas disponibles». En Pago → Preferencias, desmarca las monedas, los países o los transportistas donde no quieras ofrecer cripto. Agrega la URL de conciliación de la configuración al cron del servidor cada 15 minutos. Haz primero una prueba con una clave ck_test_ y la URL de la API de prueba en URL de la API (el valor predeterminado es producción; pide la URL de prueba a soporte de CryptoLike). Las claves de prueba funcionan con redes de prueba, el checkout muestra «Modo de prueba: monedas de red de prueba, sin fondos reales» y en modo de prueba se rechaza una clave real.

#Qué pasa con un pedido

El tiempo para pagar es el de la configuración de tu cuenta (30 minutos por defecto), salvo que definas otro valor en el módulo. La página del pedido en el back office también muestra el pago actual: ID, estado, plazo y el enlace a la página de pago.

Las mismas reglas entre pago y pedido se aplican en todas las plataformas; las demás plataformas de tiendas se comparan en pagos con cripto para tiendas online.

#Solución de problemas

Los registros están en Parámetros avanzados → Registros, tipo de objeto Cryptolike, sin secretos, firmas, cuerpos de webhooks ni datos de clientes. Al desinstalar el módulo se eliminan la configuración, ambos secretos y las tablas del módulo; los tres estados de pedido quedan ocultos porque los pedidos existentes los usan.

#Para desarrolladores

El módulo implementa el contrato común de los plugins de CryptoLike: creación del pago en el servidor con un solo pago abierto por pedido (idempotency_by_order_id), firmas de webhook verificadas sobre el cuerpo sin procesar, deduplicación por event_id, bloqueo de fila en el pedido y respuesta 200 solo después de guardar el estado. El archivo incluye un README para desarrolladores con la estructura del módulo.

#Preguntas frecuentes

#¿Qué pasa si el cliente paga menos que el total del pedido?

El pedido pasa a Pago con cripto insuficiente, y la página de estado le muestra al cliente cuánto falta, a qué dirección enviarlo y hasta cuándo. Si el resto llega antes del plazo, el pedido pasa a Pago aceptado. Después del plazo pasa a Revisión del pago con cripto, y un mensaje privado en el pedido indica qué debes decidir.

#¿Y si el cliente paga después de que el pago venció?

CryptoLike acredita los fondos a tu saldo, y el pedido pasa a Revisión del pago con cripto en lugar de Pago aceptado. El mensaje privado en el pedido muestra el monto. Tú decides si completas el pedido o le devuelves el dinero al cliente; el módulo nunca marca ese pedido como pagado por su cuenta.

#¿Cómo funcionan los reembolsos?

La tienda no puede revertir una transferencia en la blockchain, así que los reembolsos son manuales. Pídele al cliente una dirección y envía el monto como retiro desde el panel de CryptoLike. La estimación muestra la comisión de la plataforma y la comisión de red antes de que confirmes; las comisiones vigentes están en la página de precios.

#¿Qué monedas puedo usar en la tienda?

El módulo crea cada pago en la moneda del carrito (USD, EUR, UAH, GBP o CAD), y CryptoLike la convierte a cripto con un tipo de cambio fijado hasta que el pago vence. Si tu cuenta no acepta una moneda, el pago falla con «El pago con cripto no está disponible», así que desmárcala en Pago → Preferencias.

#¿Puedo probar el módulo sin dinero real?

Sí. Activa el modo de prueba, guarda una clave ck_test_ e ingresa la URL de la API de prueba que te da el soporte de CryptoLike. Las claves de prueba funcionan con redes de prueba, y las monedas de prueba no tienen valor. La página de configuración muestra un aviso de «Modo de prueba», y el checkout dice «Modo de prueba: monedas de red de prueba, sin fondos reales». En modo de prueba, el formulario rechaza una clave real.

#¿Qué ve el cliente si no se puede crear la página de pago?

El pedido sigue en Esperando pago con cripto y el cliente llega a la página de estado con el motivo y un botón Crear un pago nuevo. Esto pasa cuando la API no responde o la moneda no está habilitada. Esa misma página, enlazada desde los detalles del pedido del cliente, muestra después el estado actualizado.