🎨 Sysprovider Code
Sysprovider LogoWiki
🇪🇸Hosting español para ecommerce

Cómo crear un módulo de pago en PrestaShop para principiantes

Actualizado el 6 de marzo de 2026

¿Qué es un módulo de pago en PrestaShop y por qué necesitas uno?

Si tienes una tienda online con PrestaShop, ya sabrás que el corazón de tu negocio son los pagos. Sin un sistema de cobro eficiente, tus clientes no pueden completar sus compras y tú no recibes el dinero. Un módulo de pago PrestaShop es un componente de software que se conecta con una pasarela de pago externa (como PayPal, Stripe, Redsys, etc.) para procesar las transacciones de forma segura.

Para un principiante, la idea de crear módulo PrestaShop puede sonar a algo muy complejo, reservado solo para programadores expertos. Sin embargo, con las herramientas adecuadas y una explicación clara, es totalmente posible dar tus primeros pasos en el desarrollo PrestaShop y construir un módulo básico que funcione.

Este artículo está diseñado para ti, que no tienes experiencia técnica previa en programación. Te guiaré paso a paso, con un lenguaje sencillo y ejemplos prácticos, para que entiendas la arquitectura de un módulo de pago y puedas crear uno funcional desde cero. Al final, tendrás una base sólida para personalizar y ampliar tu módulo según las necesidades de tu tienda.

Antes de empezar: ¿Qué necesitas para crear un módulo de pago?

Antes de lanzarnos a escribir código, es importante que tengas a mano las herramientas correctas. No necesitas nada caro ni complicado, pero sí algunos requisitos básicos.

1. Un entorno de desarrollo local o un hosting con PrestaShop instalado

Para crear módulo PrestaShop, lo ideal es trabajar en un entorno de pruebas. Puedes instalar PrestaShop en tu ordenador usando herramientas como XAMPP o WAMP, o bien, si prefieres trabajar directamente en un servidor, necesitarás un hosting con soporte para PHP y MySQL.

[INFO] Si usas un servidor propio gestionado con Syspanel, recuerda que el acceso a la interfaz de administración se realiza a través del puerto 2106. Esto es útil para gestionar tus bases de datos y archivos de forma cómoda.

2. Un editor de código

No necesitas un IDE complejo. Un editor de texto simple como Visual Studio Code, Sublime Text o incluso el Bloc de notas de Windows (si estás muy desesperado) te servirá. Eso sí, te recomiendo uno con resaltado de sintaxis para que sea más fácil identificar errores.

3. Conocimientos básicos de PHP y estructura de carpetas

No te asustes. No necesitas ser un gurú de PHP. Con saber qué es una variable, una función y cómo se estructura un archivo .php, es suficiente para empezar. A lo largo de la guía, te iré explicando cada parte del código.

4. Documentación de tu pasarela de pago

Para que tu módulo se conecte a un proveedor de pagos real, necesitarás las credenciales y la documentación técnica de ese proveedor. Para este tutorial, usaremos un ejemplo ficticio que simula una pasarela, así podrás entender el flujo sin necesidad de registrarte en nada.

Estructura básica de un módulo de pago en PrestaShop

PrestaShop tiene una arquitectura modular muy clara. Cada módulo es una carpeta dentro del directorio /modules de tu instalación. Dentro de esa carpeta, debe haber al menos un archivo principal con el mismo nombre que la carpeta y con la extensión .php.

Por ejemplo, si nuestro módulo se llama mipagofacil, la estructura sería:

/módulos
   /mipagofacil
       mipagofacil.php

Además, es recomendable incluir un archivo logo.png (para que se muestre en el panel de administración) y un archivo config.xml (aunque en versiones modernas de PrestaShop, este último se genera automáticamente).

El archivo principal del módulo

El archivo mipagofacil.php es el corazón del módulo. Aquí definimos la clase principal que extiende la clase base PaymentModule. Esta clase hereda todas las funcionalidades que PrestaShop necesita para gestionar un módulo de pago.

Vamos a ver un ejemplo básico de cómo empezar:

<?php
if (!defined('_PS_VERSION_')) {
    exit;
}

class MiPagoFacil extends PaymentModule
{
    public function __construct()
    {
        $this->name = 'mipagofacil';
        $this->tab = 'payments_gateways';
        $this->version = '1.0.0';
        $this->author = 'Tu Nombre';
        $this->need_instance = 0;
        $this->ps_versions_compliancy = [
            'min' => '1.7',
            'max' => _PS_VERSION_
        ];
        $this->bootstrap = true;

        parent::__construct();

        $this->displayName = $this->l('Módulo de Pago Fácil');
        $this->description = $this->l('Acepta pagos de forma sencilla con este módulo de ejemplo.');
        $this->confirmUninstall = $this->l('¿Estás seguro de que quieres desinstalar este módulo?');

        // Configuración por defecto
        if (!Configuration::get('MIPAGOFACIL_TITLE')) {
            Configuration::updateValue('MIPAGOFACIL_TITLE', 'Pagar con MiPagoFacil');
        }
    }

    public function install()
    {
        return parent::install() &&
            $this->registerHook('paymentOptions') &&
            $this->registerHook('paymentReturn');
    }

    public function uninstall()
    {
        return parent::uninstall() &&
            Configuration::deleteByName('MIPAGOFACIL_TITLE');
    }
}

Fíjate en los siguientes puntos clave:

  • $this->name: Debe coincidir con el nombre de la carpeta y del archivo.
  • $this->tab: Indica la categoría del módulo en el panel de administración. Para pagos, usamos payments_gateways.
  • install(): Este método se ejecuta al instalar el módulo. Aquí registramos los hooks necesarios.
  • uninstall(): Se ejecuta al desinstalar y limpia los datos guardados.

Los hooks: ¿Qué son y cómo funcionan?

Los hooks son puntos de enganche en el código de PrestaShop que permiten que tu módulo se ejecute en momentos específicos. Para un módulo de pago, los hooks más importantes son:

  • paymentOptions: Se utiliza para mostrar las opciones de pago disponibles al cliente en el momento de finalizar la compra.
  • paymentReturn: Se ejecuta después de que el cliente ha realizado el pago y se muestra un mensaje de confirmación.

Implementando el hook paymentOptions

Este hook es el que muestra el botón o la opción de pago en el checkout. Vamos a implementarlo en nuestro módulo:

public function hookPaymentOptions($params)
{
    if (!$this->active) {
        return;
    }

    // Creamos una nueva opción de pago
    $option = new PrestaShop\PrestaShop\Core\Payment\PaymentOption();
    $option->setModuleName($this->name)
           ->setCallToActionText($this->l('Pagar con MiPagoFacil'))
           ->setAction($this->context->link->getModuleLink($this->name, 'payment', [], true))
           ->setAdditionalInformation($this->l('Serás redirigido a la pasarela de pago segura.'));

    return [$option];
}

Aquí creamos un objeto PaymentOption y lo configuramos con el texto del botón y la URL a la que se enviará al cliente. La URL apunta a un controlador llamado payment que crearemos más adelante.

Implementando el hook paymentReturn

Después del pago, este hook muestra una página de confirmación:

public function hookPaymentReturn($params)
{
    if (!$this->active) {
        return;
    }

    $this->smarty->assign([
        'status' => 'ok',
        'id_order' => $params['order']->id,
        'reference' => $params['order']->reference,
    ]);

    return $this->display(__FILE__, 'views/templates/front/payment_return.tpl');
}

Este hook utiliza una plantilla Smarty que crearemos en la carpeta views/templates/front/.

Creando el controlador de pago

El controlador es el archivo que procesa la solicitud de pago cuando el cliente hace clic en el botón. Este archivo debe ubicarse en controllers/front/payment.php dentro de la carpeta de tu módulo.

Aquí tienes un ejemplo de cómo podría ser:

<?php
class MiPagoFacilPaymentModuleFrontController extends ModuleFrontController
{
    public $ssl = true;

    public function postProcess()
    {
        $cart = $this->context->cart;

        if ($cart->id_customer == 0 || $cart->id_address_delivery == 0 || $cart->id_address_invoice == 0 || !$this->module->active) {
            Tools::redirect('index.php?controller=order');
        }

        // Aquí iría la lógica para redirigir a la pasarela de pago
        // Por ejemplo, construir una URL con los parámetros necesarios
        $url_pasarela = 'https://www.mipasarela.com/pago?monto=' . $cart->getOrderTotal(true, Cart::BOTH) . '&referencia=' . $cart->id;

        Tools::redirect($url_pasarela);
    }
}

En un caso real, aquí enviarías al cliente a la pasarela de pago con los datos de la compra. Después de que el pago se complete, la pasarela te redirigiría de vuelta a una página de confirmación.

Plantillas Smarty: El front-end de tu módulo

PrestaShop utiliza el motor de plantillas Smarty para separar la lógica de la presentación. Necesitamos dos plantillas principales:

  1. payment_return.tpl: Se muestra después del pago.
  2. payment.tpl: Opcional, si quieres mostrar información adicional antes de redirigir.

Vamos a ver un ejemplo de payment_return.tpl:

{if $status == 'ok'}
    <div class="alert alert-success">
        <h3>{l s='¡Pago realizado con éxito!' mod='mipagofacil'}</h3>
        <p>{l s='Tu pedido con referencia' mod='mipagofacil'} {$reference} {l s='ha sido procesado correctamente.' mod='mipagofacil'}</p>
    </div>
{else}
    <div class="alert alert-danger">
        <h3>{l s='Ha ocurrido un error con el pago.' mod='mipagofacil'}</h3>
        <p>{l s='Por favor, intenta de nuevo o contacta con nosotros.' mod='mipagofacil'}</p>
    </div>
{/if}

Recuerda que las plantillas deben estar en views/templates/front/ dentro de la carpeta del módulo.

Configuración del módulo en el panel de administración

Para que tu módulo sea fácil de configurar, podemos añadir un formulario de opciones. Esto se hace en el método getContent() de la clase principal. Aquí tienes un ejemplo sencillo:

public function getContent()
{
    $output = '';

    if (Tools::isSubmit('submit' . $this->name)) {
        $title = Tools::getValue('MIPAGOFACIL_TITLE');
        Configuration::updateValue('MIPAGOFACIL_TITLE', $title);
        $output .= $this->displayConfirmation($this->l('Configuración actualizada'));
    }

    return $output . $this->renderForm();
}

private function renderForm()
{
    $fields_form = [
        'form' => [
            'legend' => [
                'title' => $this->l('Configuración'),
                'icon' => 'icon-cog',
            ],
            'input' => [
                [
                    'type' => 'text',
                    'label' => $this->l('Título del módulo'),
                    'name' => 'MIPAGOFACIL_TITLE',
                    'required' => true,
                ],
            ],
            'submit' => [
                'title' => $this->l('Guardar'),
            ],
        ],
    ];

    $helper = new HelperForm();
    $helper->module = $this;
    $helper->name_controller = $this->name;
    $helper->token = Tools::getAdminTokenLite('AdminModules');
    $helper->currentIndex = AdminController::$currentIndex . '&configure=' . $this->name;
    $helper->title = $this->displayName;
    $helper->submit_action = 'submit' . $this->name;
    $helper->default_form_language = (int) Configuration::get('PS_LANG_DEFAULT');
    $helper->fields_value['MIPAGOFACIL_TITLE'] = Configuration::get('MIPAGOFACIL_TITLE');

    return $helper->generateForm([$fields_form]);
}

Este código añade una pantalla de configuración en el panel de administración donde puedes cambiar el título que se muestra al cliente.

Errores comunes y cómo solucionarlos

Cuando empiezas en el desarrollo PrestaShop, es normal encontrarte con errores. Aquí tienes algunos de los más comunes y cómo resolverlos:

1. El módulo no aparece en la lista de módulos

  • Verifica que el nombre de la carpeta, el nombre del archivo y el valor de $this->name sean exactamente iguales.
  • Asegúrate de que el archivo principal no tenga errores de sintaxis. Puedes probarlo abriendo el archivo directamente en tu navegador (aunque mostrará un error si no se accede desde PrestaShop, te dirá si hay problemas de sintaxis).

2. El botón de pago no aparece en el checkout

  • Comprueba que el hook paymentOptions está bien registrado en el método install().
  • Revisa que el módulo está activado en el panel de administración.
  • Asegúrate de que tu carrito cumple los requisitos mínimos (por ejemplo, que el cliente esté logueado).

3. Error de "Clase no encontrada"

  • Esto suele pasar cuando el nombre de la clase no coincide con el nombre del archivo. PrestaShop busca una clase con el nombre del módulo en formato CamelCase. Por ejemplo, mipagofacil se convierte en MiPagoFacil.

4. Problemas con la redirección a la pasarela

  • Verifica que la URL de la pasarela es correcta y accesible.
  • Asegúrate de que los parámetros enviados son los que espera la pasarela.

[WARNING] Nunca guardes credenciales de pago en el código del módulo. Utiliza siempre las opciones de configuración de PrestaShop para almacenarlas de forma segura en la base de datos.

Consejos avanzados para llevar tu módulo al siguiente nivel

Una vez que tengas tu módulo básico funcionando, puedes ampliarlo con funcionalidades más avanzadas:

1. Soporte multiidioma

PrestaShop tiene un sistema de traducción integrado. Para usarlo, debes crear archivos de traducción en la carpeta translations/ de tu módulo. El método $this->l() que usamos antes ya facilita esto.

2. Gestión de estados de pedido

Puedes crear estados de pedido personalizados para tu módulo. Por ejemplo, un estado "Pago pendiente" o "Pago rechazado". Esto se hace en el método install():

$estado = new OrderState();
$estado->name = array_fill(0, 10, 'Pago pendiente');
$estado->template = 'payment_pending';
$estado->send_email = 0;
$estado->module_name = $this->name;
$estado->color = '#FF8C00';
$estado->hidden = false;
$estado->unremovable = true;
$estado->add();

Luego puedes guardar el ID del estado en la configuración para usarlo cuando se confirme un pago.

3. Webhooks y notificaciones

Las pasarelas de pago modernas envían notificaciones automáticas (webhooks) cuando se confirma un pago. Debes crear un controlador que reciba estas notificaciones y actualice el estado del pedido en consecuencia.

class MiPagoFacilWebhookModuleFrontController extends ModuleFrontController
{
    public function postProcess()
    {
        // Recibir la notificación
        $input = json_decode(file_get_contents('php://input'), true);

        // Validar la firma y actualizar el pedido
        // ...
    }
}

[TIP] Siempre valida la firma de las notificaciones para evitar fraudes. Nunca confíes en una notificación sin

¿Necesitas ayuda?Son dos de nuestros técnicos, Agustín y Mikel, y están disponibles para resolver cualquier problema.

Hablar con ellos ahora
Agustín y Mikel