Plugins de e-commerce
Extensión de OpenCart
Instala y configura la extensión oficial de OpenCart con OAuth nativo, checkout alojado MakePay y webhooks firmados.
Resumen
MakePay para OpenCart permite que merchants acepten pagos cripto mediante checkout alojado MakePay sin recopilar detalles de pago dentro de OpenCart. La extensión aparece como método de pago de OpenCart, crea un enlace de pago MakePay para cada pedido, redirige al comprador a MakePay y acepta webhooks firmados para actualizar el estado del pedido en OpenCart.
Antes de empezar
- OpenCart 4.x
- PHP 8.0 o superior
- HTTPS en el frontend de la tienda
- Una empresa MakeCrypto con MakePay habilitado
- Un usuario MakeCrypto que pueda conectar la empresa receptora
- Opcional: una integración API MakePay para fallback con clave API manual
OpenCart guarda los ajustes de extensión en su base de datos. Limita el acceso al admin de OpenCart a operadores confiables porque los detalles de conexión, secretos de webhook y credenciales opcionales de fallback se guardan en los ajustes de la extensión de pago.
Configurar MakeCrypto
Completa la configuración de merchant antes de conectar OpenCart.
- Abre Home > Merchant > Payment settings y confirma que MakePay esté habilitado.
- Abre Home > Integrations > API Integrations.
- Confirma que el usuario que conecta OpenCart pueda gestionar integraciones para esa empresa.
- Fallback opcional: crea o selecciona una integración API y copia ID de empresa, ID de clave API y secreto.
Instalar la extensión
La fuente recomendada es el listado oficial en OpenCart Marketplace:
Abrir en OpenCart Extension Explorer
Para instalación manual, descarga directamente el paquete OpenCart más reciente:
Descargar ZIP OCMOD manual
Luego instálalo en OpenCart:
- En el admin de OpenCart, abre Extensions > Installer.
- Sube
makepay.ocmod.zip. - Abre Extensions > Extensions y elige Payments.
- Busca MakePay y haz clic en instalar.
- Abre Edit para configurar el método de pago.
La raíz del paquete contiene install.json, admin/ y catalog/, siguiendo el formato del instalador de extensiones de OpenCart 4.
Conectar MakePay
En Extensions > Payments > MakePay, usa Connect MakePay. La extensión:
- Abre MakeCrypto en una pestaña del navegador.
- Te pide iniciar sesión y elegir la empresa que recibirá pagos.
- Muestra los permisos que necesita la extensión OpenCart.
- Te devuelve a OpenCart tras aprobar.
- Guarda la conexión de tienda y el ID de empresa.
- Configura la URL de callback de webhook MakePay y el secreto de webhook.
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
La redirect URI tiene esta forma:
https://your-store.example/index.php?route=extension/makepay/payment/makepay.oauth
Configurar MakePay
En Extensions > Payments > MakePay, configura:
| Campo | Valor |
|---|---|
| Status | Enabled |
| Payment method name | Etiqueta de checkout visible al comprador |
| Connection method | Connect MakePay, o fallback con clave API manual |
| MakePay company ID | Rellenado tras conexión, o introducido manualmente para fallback |
| API key ID | ID de integración API solo para fallback |
| API key secret | Secreto de integración API solo para fallback |
| Webhook secret | Configurado durante conexión o introducido manualmente para fallback |
| API base URL | https://www.makecrypto.io |
| Settlement currency | Activo de liquidación predeterminado, por ejemplo USDT |
| Payment link expiration | Por ejemplo 12h |
| Checkout experience | Redirección alojada, o checkout embebido con iframe seguro y fallback alojado |
El nombre predeterminado del método de pago es:
Crypto Payment in USDT, BTC, ETH, LTC, DOGE and others
Configurar webhooks
Copia la URL de webhook mostrada en la página de ajustes MakePay de OpenCart. Tiene esta forma:
https://your-store.example/index.php?route=extension/makepay/payment/makepay.webhook
Connect MakePay configura este callback automáticamente. Para fallback con clave API manual, agrégalo a los ajustes de webhook de MakePay con el mismo secreto de webhook introducido en OpenCart.
La extensión verifica X-MakePay-Signature antes de actualizar un pedido. La firma usa el formato HMAC con timestamp:
t=1760000000,v1=<hex-hmac>
Flujo de checkout
Cuando el comprador selecciona MakePay:
- OpenCart valida el pedido activo y método de pago seleccionado.
- La extensión llama la API partner de MakePay para crear un enlace de pago.
- El pedido pasa al estado pendiente configurado.
- El comprador abre la experiencia de checkout MakePay seleccionada.
- Un webhook firmado actualiza el pedido de OpenCart después de cambios de estado de pago.
El enlace de pago incluye metadata:
| Metadata | Propósito |
|---|---|
source=opencart | Identifica la integración |
orderId | ID de pedido OpenCart |
storeId | ID de tienda OpenCart |
storeName | Nombre de tienda |
storeUrl | URL del frontend de tienda |
opencartOrderId | ID de pedido OpenCart para dashboard y webhooks |
opencartOrderAdminUrl | URL admin usada por la acción Show order de MakeCrypto |
storeOrderAdminUrl | Fallback genérico de URL admin de pedido |
moduleVersion | Versión de extensión MakePay OpenCart |
opencartVersion | Versión runtime de OpenCart |
Estados del pedido
Configura el mapeo de estados en los ajustes de la extensión.
| Estado MakePay | Estado OpenCart |
|---|---|
paid, completed, confirmed, succeeded | Estado pagado |
failed, expired, chargeback | Estado fallido |
cancelled, canceled | Estado cancelado |
refunded | Estado reembolsado |
| Cualquier estado en progreso | Estado pendiente |
La extensión agrega un comentario de historial de pedido con estado MakePay, UID o ID de pago, importe, activo y URL de checkout alojado cuando estén presentes en el payload de webhook. La entrada inicial del historial de checkout también incluye la URL pública de pago y el enlace del dashboard MakeCrypto cuando la respuesta API lo proporciona.
Notas de seguridad
- Usa HTTPS para checkout y URLs de webhook.
- Restringe acceso al admin de OpenCart porque los detalles de conexión y credenciales opcionales se guardan en ajustes OpenCart.
- Revoca la app conectada de OpenCart desde MakeCrypto si una cuenta admin de OpenCart queda comprometida.
- Rota la clave API MakePay si se exponen credenciales de fallback manual.
- Mantén el secreto de webhook distinto del secreto de clave API.
- Trata fallos inesperados de firma de webhook como posible desajuste de credenciales o intento de spoofing.
Solución de problemas
Si el método de pago no es visible, confirma que MakePay esté habilitado, que el total del carrito cumpla el mínimo configurado y que la dirección del cliente coincida con la geo zone configurada.
Si Connect MakePay falla, confirma que la URL de tienda OpenCart sea HTTPS y que el navegador vuelva a la callback URL mostrada arriba.
Si checkout no redirige, confirma que la tienda esté conectada. Para fallback manual, confirma ID de empresa, ID de clave API, secreto de clave API, URL base de API y permisos de la integración MakePay.
Si los pedidos no se actualizan después del pago, confirma que la URL de webhook sea accesible públicamente sobre HTTPS y que el secreto de webhook en MakePay coincida con el secreto guardado en OpenCart.
Si OpenCart informa un error de instalador, confirma que el archivo descargado termine en .ocmod.zip y contenga install.json, admin/ y catalog/ en la raíz del ZIP.