Módulo MakePay para Magento

Resumen

El módulo oficial MakePay para Magento agrega un método de checkout cripto alojado a tiendas Magento Open Source y Adobe Commerce 2.4.x. Magento crea el pedido, MakePay crea el enlace de pago alojado y los webhooks firmados actualizan el pedido cuando cambia el estado de pago.

Usa Connect MakePay para configuración normal. Las credenciales manuales con clave API siguen disponibles como fallback.

Antes de empezar

• Magento Open Source o Adobe Commerce 2.4.x
• PHP 8.1 o superior
• Acceso administrador a Stores > Configuration > Sales > Payment Methods
• Una empresa MakePay donde puedas gestionar ajustes de pago

Instalar el módulo

Descarga el ZIP más reciente:

https://plugins.makecrypto.io/downloads/magento/latest.zip

Extrae el paquete para que el módulo quede ubicado en:

app/code/MakePay/Payment

Habilítalo desde la raíz de Magento:

bin/magento module:enable MakePay_Payment
bin/magento setup:upgrade
bin/magento cache:clean

Conectar MakePay

Abre Stores > Configuration > Sales > Payment Methods > MakePay y selecciona Connect MakePay. El módulo:

1. Abre MakeCrypto en una pestaña del navegador.
2. Te pide iniciar sesión y elegir la empresa que recibirá los pagos.
3. Muestra los permisos que necesita el módulo Magento.
4. Te devuelve a Magento tras aprobar.
5. Guarda la conexión de tienda en la configuración cifrada de Magento.
6. Configura el callback de webhook MakePay y el secreto de webhook.

Configurar MakePay

Después de conectar, conserva Connection Method en el modo conectado predeterminado. Habilita el método de pago y revisa:

• Payment Method Name
• Checkout Experience
• Settlement Currency
• Payment Link Expiration
• Estados de pedido pendiente, pagado, fallido, cancelado y reembolsado

El fallback manual requiere ID de empresa MakePay, ID de clave API, secreto de clave API y secreto de webhook.

Flujo de checkout

Cuando un cliente elige MakePay, Magento coloca el pedido en pending payment y luego abre la experiencia de checkout MakePay seleccionada. La redirección alojada es la opción recomendada; el checkout embebido muestra una página segura con iframe MakePay y un enlace alojado de fallback.

El payload del enlace de pago incluye:

Campo	Propósito
source=magento	Identifica la integración
orderId=magento_order_<id>	Mapea actividad MakePay de vuelta a Magento
incrementId	Número de pedido Magento legible
magentoOrderAdminUrl	Permite que MakeCrypto enlace administradores al pedido Magento
moduleVersion	Versión instalada del módulo MakePay
magentoVersion	Versión runtime de Magento o Adobe Commerce

Estados del pedido

El endpoint de webhook es /makepay/webhook/index. Verifica la cabecera X-MakePay-Signature antes de actualizar un pedido.

Estado MakePay	Estado Magento
paid, completed, confirmed, succeeded	Processing
failed, expired	Canceled
cancelled, canceled	Canceled
refunded	Closed
Otros estados	Pending payment

Cada webhook escribe un comentario privado de historial de pedido con el estado de pago, URL pública de checkout MakePay, URL de dashboard MakeCrypto e identificadores MakePay disponibles.

Notas de seguridad

El módulo guarda detalles de conexión en la configuración cifrada de Magento. Limita el acceso administrador de Magento a operadores confiables y desconecta la tienda en MakeCrypto si una cuenta administradora o backup del servidor queda expuesto.

La conexión solicita estos permisos:

• company:read
• makepay:payment-links:read
• makepay:payment-links:write
• makepay:customers:read
• makepay:customers:write
• makepay:settings:read
• makepay:settings:write

Solución de problemas

Si Connect MakePay no puede iniciar, confirma que la URL base de Magento sea HTTPS y accesible públicamente. Si las redirecciones de checkout fallan, confirma que el módulo esté habilitado y que MakePay tenga una conexión guardada o credenciales manuales válidas. Si los pedidos no se actualizan, compara la URL de callback de webhook en ajustes MakePay con la URL Magento /makepay/webhook/index y rota el secreto de webhook.