# Pagos con criptomonedas en Magento 2

> Recibe Bitcoin, USDT, Ethereum, Litecoin y TRON en tu tienda online con Magento 2.4.6+. Instala el módulo y pega la clave; el pedido sigue el estado del pago.

Source: https://cryptolike.net/es/integrations/magento
Updated: 2026-10-11

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.

| Aspecto | Compatibilidad |
|---|---|
| Magento | 2.4.6 y posteriores (Magento Open Source) |
| PHP | 8.1 – 8.4 |
| Checkout | Luma |
| Instalación | Paquete de Composer o archivo para `app/code` |
| Varias tiendas | Configuración por sitio web; cada sitio web puede usar su propia cuenta de CryptoLike |

## 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:

```bash
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

| Pago | Pedido de Magento (estado) | Lo que ve el cliente |
|---|---|---|
| Creado en «Realizar pedido» | `pending_payment` | «Esperando el pago.» y la página de pago |
| Transferencia detectada | Sin cambios, comentario con el ID de la transacción | «Pago detectado. Esperando confirmación.» |
| Confirmado | `processing` y una factura; un pedido virtual pasa a `complete` | «Pago confirmado.» |
| Pago insuficiente, antes del plazo | `holded`, comentario con el monto que falta | Cuánto falta, a la misma dirección, y el plazo |
| Un pago complementario lo completa | Sale de retención, `processing` y una factura | «Pago confirmado.» |
| Pago tardío o parcial después del plazo, segundo pago, reverso, monto del pedido modificado | `payment_review` con un comentario sobre la decisión | Un mensaje según el caso, por ejemplo «Pago recibido. La tienda lo está revisando y te contactará.» |
| Vencido | `canceled` (el inventario se libera) o sin cambios (según la configuración) | «El pago venció. Crea un pago nuevo.» |

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](https://cryptolike.net/es/use-cases/online-stores).
## Capturas de pantalla

![El método de CryptoLike en el checkout de Luma de Magento](https://cryptolike.net/integrations/media/magento/2-checkout.png)

![La página de estado del pago después de un pago cripto confirmado en Magento](https://cryptolike.net/integrations/media/magento/3-status-paid.png)

## Solución de problemas

| Lo que ves | Qué hacer |
|---|---|
| El método no aparece en el checkout | Actívalo; guarda el ID de la clave, el secreto y el secreto del webhook de ese sitio web; usa una clave cuyo prefijo coincida con el modo; ejecuta `bin/magento cache:flush`. |
| Los pedidos siguen en Pendiente de pago después del pago | «Último webhook verificado» está vacío en la configuración: el webhook no llega a la tienda. Revisa el acceso por `https://`, deja pasar `POST /cryptolike/webhook/` por el WAF o el CDN sin desafío y desactiva el modo de mantenimiento. El cron de Magento debe estar activo para la revisión cada 15 minutos. |
| «Falló la conexión: auth.…» | `auth.invalid_key` o `auth.invalid_signature`: el ID de la clave o el secreto son incorrectos. `auth.ip_not_allowed`: la lista de IP permitidas de la clave no incluye tu servidor. `auth.test_key`: una clave `ck_test_` con la URL de la API predeterminada; el modo de prueba también necesita la URL de la API de prueba. |
| La página integrada no carga | Agrega la dirección de la tienda en el panel en **Configuración → Integración → Orígenes permitidos** y permite el host de pago en tu CSP personalizada. |

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](https://cryptolike.net/docs/webhooks) 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](https://cryptolike.net/es/pricing).

### ¿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.