Pagos con criptomonedas en Magento 2

El módulo de CryptoLike agrega cripto al checkout de Magento 2 en tu tienda online y crea la factura de Magento solo cuando el pago se confirma en la blockchain. Tus clientes pagan en Bitcoin, USDT, Ethereum, Litecoin, TRON o USDC; tu equipo trabaja con los estados de pedido habituales, incluidos Aceptar y Denegar para los pagos que requieren una decisión.

#Requisitos

El módulo CryptoLike_Payment funciona en Magento 2.4.6 y posteriores con PHP 8.1 a 8.4 y el checkout de Luma. Está construido sobre Magento Payment Gateway y se probó con las clases reales de Magento 2.4, el estándar de código de Magento 2 y una ejecución real en Mage-OS 3.5, la distribución de Magento Open Source. El SDK de PHP de CryptoLike viene dentro del módulo, así que no necesitas otro paquete ni una clave de Marketplace.

#Qué hace el módulo

Al hacer clic en «Realizar pedido», el módulo crea un pago de CryptoLike para el pedido y lo deja en pending_payment. Después, los webhooks firmados lo mueven: un pago confirmado pasa a processing con una factura de Magento (cobrada fuera de línea; el ID de la transacción es el ID del pago de CryptoLike), y el dinero que requiere la decisión de una persona pasa a payment_review.

• Redirección o página integrada. Después de «Realizar pedido», el cliente va a la página de pago de CryptoLike o paga en la página de estado del pago del pedido.
• Aceptar o denegar en revisión. Los pagos tardíos, los pagos insuficientes después del plazo y los reversos muestran los botones Aceptar pago y Denegar pago de Magento.
• Secretos cifrados. El secreto de la API y el secreto del webhook se guardan con la clave de cifrado de Magento y nunca aparecen en config:show ni en app:config:dump.
• Un solo pago por pedido. Un doble clic, una recarga o «Crear un pago nuevo» devuelven el mismo pago abierto.
• Elección de moneda en la página de pago. El cliente elige la moneda allí; Monedas en la página de pago puede limitar la lista, y sin selección se ofrecen todas las monedas disponibles para facturas en tu cuenta.
• Una tarea cron, cryptolike_reconcile, vuelve a consultar los pagos abiertos cada 15 minutos.

#1. Instala el módulo

Con Composer (recomendado), coloca el archivo de Composer de esta página en un directorio del servidor, por ejemplo /var/www/packages, y ejecuta en la raíz de Magento:

composer config repositories.cryptolike artifact /var/www/packages
composer require cryptolike/module-payment:1.0.0
bin/magento module:enable CryptoLike_Payment
bin/magento setup:upgrade
bin/magento setup:di:compile
bin/magento cache:flush

Sin Composer, descomprime el archivo para app/code en la raíz de Magento (crea app/code/CryptoLike/Payment) y ejecuta los mismos comandos bin/magento. En modo de producción, despliega también el contenido estático.

#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 Tiendas → Configuración → Ventas → Métodos de pago → CryptoLike: pagos con cripto. Copia la URL del webhook que aparece ahí (https://your-shop/cryptolike/webhook/, una por vista de tienda), agrégala en el panel en Desarrolladores → Webhooks → Agregar endpoint con todos los eventos invoice.* y pega el secreto del endpoint en Secreto del webhook.

#3. Activa el método y haz una prueba

Pon Activar los pagos con cripto en Sí y haz clic en Guardar configuración. Después, Comprobar la conexión muestra «Conectado: N monedas disponibles». Antes de empezar a cobrar, haz 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 la línea de modo de prueba debajo del método y no se puede guardar una clave real en modo de prueba.

#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. Magento no puede reabrir un pedido cancelado, así que si llega dinero para uno, sigue en canceled con un comentario; los fondos quedan en tu saldo de CryptoLike para reembolsarlos o usarlos en un pedido nuevo.

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.

#Capturas de pantalla

#Solución de problemas

El registro está en var/log/cryptolike.log y nunca contiene secretos, firmas, cuerpos de webhooks ni datos de clientes.

#Para desarrolladores

El módulo sigue 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; fuera de la tienda predeterminada, el order_id de la API es <store_id>-<increment_id>), firmas de webhook verificadas sobre el cuerpo sin procesar, deduplicación por event_id y respuesta 200 solo después de guardar el pedido. 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 holded con un comentario sobre el monto que falta, y el cliente ve cuánto enviar a la misma dirección antes del plazo. Si completa el pago a tiempo, la retención se libera y el pedido pasa a processing con una factura. Después del plazo, el pedido pasa a payment_review para Aceptar o Denegar.

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

Si el pedido se canceló al vencer el pago, sigue en canceled, porque Magento no puede reabrirlo; un comentario indica qué llegó y los fondos quedan en tu saldo. Si prefieres mantener los pedidos abiertos, en «Cuando vence un pago» elige mantener el pedido pendiente de pago: así, un pago tardío pasa a payment_review con Aceptar y Denegar.

#¿Cómo funcionan los reembolsos?

Los reembolsos son manuales, porque una transferencia en la blockchain no se puede revertir. Deniega el pago en revisión o cancela el pedido y luego envía el reembolso como retiro desde el panel de CryptoLike a una dirección que te dé el cliente. La estimación muestra la comisión de la plataforma y la comisión de red; las comisiones vigentes están en la página de precios.

#¿Qué monedas puedo usar en la tienda?

Cada pago se crea en la moneda del pedido (USD, EUR, UAH, GBP o CAD), y CryptoLike la convierte a cripto con un tipo de cambio fijado hasta que el pago vence. La moneda debe estar habilitada para pagos en tu cuenta. Con varias tiendas, cada sitio web puede usar su propia cuenta de CryptoLike y sus propias monedas.

#¿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 la etiqueta «Modo de prueba» y el checkout muestra la línea de modo de prueba. No se puede guardar una clave real en modo de prueba ni una clave de prueba en modo real.

#¿El módulo funciona con Adobe Commerce?

El módulo es un módulo de pago estándar de Magento 2 y se probó en Magento Open Source 2.4 (la distribución Mage-OS). Adobe Commerce comparte el mismo checkout y el mismo framework de pagos, pero todavía no se ha probado ahí; primero ejecuta el módulo en una copia de tu tienda en modo de prueba.