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

Integración de pagos cripto en PrestaShop

Actualizado el 1 de abril de 2026

La adopción de criptomonedas en el comercio electrónico ha pasado de ser una tendencia de nicho a una necesidad competitiva. Integrar pagos cripto PrestaShop ya no es solo un diferenciador, sino una estrategia para reducir costos de transacción, eliminar contracargos (chargebacks) y atraer a un perfil de cliente global y digitalmente nativo.

PrestaShop, al ser una plataforma de código abierto, ofrece una flexibilidad excepcional para implementar una pasarela cripto. Sin embargo, la integración no es trivial: implica decisiones sobre custodia, volatilidad, cumplimiento regulatorio (KYC/AML) y experiencia de usuario.

Este artículo es una guía técnica exhaustiva para desarrolladores y administradores de tiendas PrestaShop que buscan implementar pagos con Bitcoin, Ethereum y otras criptomonedas de manera segura y eficiente.

Arquitectura de una Pasarela Cripto en PrestaShop

Antes de escribir código, es crucial entender los dos modelos principales de integración. La elección impacta directamente en la seguridad, la latencia y los costos operativos.

Modelo 1: Procesador de Terceros (No Custodial Simplificado)

Es la opción más rápida y segura para la mayoría de los comercios. El proveedor externo maneja la liquidación a fiat o la custodia de las criptos.

  • Ventajas: No necesitas manejar claves privadas. Conversión automática a EUR/USD elimina el riesgo de volatilidad. Cumplimiento AML/KYC delegado.
  • Desventajas: Comisiones más altas (1-2% + tarifa de red). Dependencia de un tercero para la operación.
  • Proveedores populares: Coinbase Commerce, BitPay, CoinGate, NowPayments.

Modelo 2: Integración Directa (Autocustodia On-Chain)

Aquí tu servidor interactúa directamente con la blockchain. Es técnicamente más complejo pero te da control total.

  • Ventajas: Sin comisiones de procesador. Control total de los fondos. Sin riesgo de censura.
  • Desventajas: Responsabilidad total de la seguridad de las claves. Debes lidiar con la volatilidad (o usar un oráculo externo). Necesitas un nodo completo o un servicio de API como BlockCypher o Infura.
  • Implementación: Creación de direcciones HD (BIP32/BIP39), monitoreo de transacciones no gastadas (UTXOs en Bitcoin), manejo de confirmaciones.

[WARNING] El Modelo 2 (Autocustodia) no es recomendado para principiantes. Un error en el manejo de claves puede resultar en la pérdida permanente de fondos. Siempre usa una billetera multisig o un HSM si escalas.

Elección del Módulo Base

PrestaShop carece de una pasarela cripto nativa. Debes optar por:

  1. Módulos de pago oficiales: Muchos procesadores ofrecen módulos gratuitos o de pago en el Addons Marketplace (ej. Coinbase Commerce, BitPay).
  2. Desarrollo a medida: Usando la clase PaymentModule y hooks como paymentOptions y paymentReturn. Creas un módulo que se comunica con la API del procesador o con tu nodo.

Paso a Paso: Integración con un Procesador (Modelo 1)

Usaremos como ejemplo la integración con CoinPayments (o similar) para ilustrar el flujo. Este es el método más común y recomendado para tiendas en producción.

1. Instalación y Configuración del Módulo

  • Descarga el módulo de tu procesador (ej. coinpayments.zip).
  • Ve a Módulos → Administrador de módulos → Subir un módulo.
  • Instala y configura las claves API (Merchant ID, IPN Secret, API Key).
# Ejemplo de configuración en el backoffice del módulo
Merchant ID: a1b2c3d4e5f6...
IPN Secret: MiClaveSuperSecreta
API Key: abcdef123456...
Currency Conversion: EUR (para evitar volatilidad)

2. Lógica del Checkout (Hook paymentOptions)

En tu módulo personalizado, implementas el hook para mostrar la opción de pago.

// En tu archivo principal del módulo: mi_modulocripto.php
public function hookPaymentOptions($params)
{
    if (!$this->active) {
        return;
    }

    $paymentOption = new PrestaShop\PrestaShop\Core\Payment\PaymentOption();
    $paymentOption->setCallToActionText('Pagar con Bitcoin o Ethereum')
                  ->setAction($this->context->link->getModuleLink($this->name, 'validation', [], true))
                  ->setLogo(Media::getMediaPath(_PS_MODULE_DIR_.$this->name.'/logo.png'))
                  ->setAdditionalInformation('<p>Serás redirigido a nuestra pasarela de pago segura.</p>');

    return [$paymentOption];
}

3. Procesamiento del Pago (Controlador validation)

El cliente es redirigido a tu controlador. Aquí creas la transacción en el procesador.

// controllers/front/validation.php
public function postProcess()
{
    $cart = $this->context->cart;
    $total = $cart->getOrderTotal(true, Cart::BOTH);
    $currency = new Currency($cart->id_currency);

    // Llamada a la API del procesador
    $api = new CoinPaymentsAPI();
    $response = $api->createTransaction([
        'amount' => $total,
        'currency1' => $currency->iso_code, // EUR
        'currency2' => 'BTC', // Moneda de pago
        'buyer_email' => $this->context->customer->email,
        'item_name' => 'Pedido #'.$cart->id,
        'ipn_url' => $this->context->link->getModuleLink($this->name, 'ipn', [], true),
    ]);

    if ($response['error'] == 'ok') {
        // Guardar en la DB el ID de la transacción y el estado pendiente
        $this->module->validateOrder(
            $cart->id,
            Configuration::get('PS_OS_PAYMENT_PENDING'), // Estado personalizado
            $total,
            $this->module->displayName,
            null,
            ['transaction_id' => $response['result']['txn_id']],
            (int)$currency->id,
            false,
            $cart->secure_key
        );
        Tools::redirect($response['result']['checkout_url']); // Redirigir al checkout del procesador
    } else {
        $this->errors[] = 'Error al crear el pago: ' . $response['error'];
        $this->redirectWithNotifications($this->context->link->getPageLink('order'));
    }
}

4. Manejo del IPN (Instant Payment Notification)

El procesador te notifica cuando el pago es confirmado en la blockchain.

// controllers/front/ipn.php
public function postProcess()
{
    // Verificar HMAC o IPN Secret
    if ($this->validateIPN($_POST)) {
        $txn_id = $_POST['txn_id'];
        $status = (int)$_POST['status']; // 0=pending, 1=success, -1=failed

        // Buscar el pedido por transaction_id en la tabla ps_order_payment
        $orderPayment = OrderPayment::getByTransactionId($txn_id);
        $order = new Order($orderPayment->id_order);

        if ($status >= 100) { // Confirmado
            $order->setCurrentState(Configuration::get('PS_OS_PAYMENT'));
            $order->save();
        } elseif ($status < 0) {
            $order->setCurrentState(Configuration::get('PS_OS_CANCELED'));
        }
    }
}

Integración Directa con Bitcoin Core (Modelo 2 Avanzado)

Para equipos con experiencia en blockchain, la integración directa usando Bitcoin Core como backend ofrece el máximo control.

Requisitos Técnicos

  • Servidor dedicado o VPS con Bitcoin Core sincronizado (archivo bitcoin.conf).
  • Conexión RPC desde PrestaShop al nodo.
  • Librería PHP como bitwasp/bitcoin para manejo de claves HD.

Configuración del Nodo

# ~/.bitcoin/bitcoin.conf
server=1
rpcuser=prestashop_user
rpcpassword=SuperSecreta123
rpcallowip=127.0.0.1
txindex=1
wallet=prestashop_wallet

Generación de Direcciones por Pedido

Usando el wallet de Bitcoin Core, generamos una dirección única para cada pedido. Esto evita la reutilización de direcciones y mejora la privacidad.

// En el hook paymentOptions o en la validación
private function generateAddressForOrder($orderId)
{
    $bitcoin = new BitcoinClient('http://prestashop_user:SuperSecreta123@127.0.0.1:8332');
    // Usando BIP44 para derivar direcciones
    $address = $bitcoin->getnewaddress('pedido_'.$orderId, 'p2sh-segwit');
    return $address;
}

Monitoreo de Transacciones (Polling vs Webhook)

La forma más robusta es usar listtransactions o listsinceblock para detectar pagos entrantes.

// Cron job ejecutado cada 2 minutos
public function checkPendingPayments()
{
    $bitcoin = new BitcoinClient(...);
    $transactions = $bitcoin->listtransactions('*', 100, 0, true); // Watchonly

    foreach ($transactions as $tx) {
        if ($tx['category'] == 'receive' && $tx['confirmations'] >= 3) {
            // Extraer orderId de la etiqueta de la dirección
            preg_match('/pedido_(\d+)/', $tx['label'], $matches);
            if ($matches) {
                $order = new Order((int)$matches[1]);
                if ($order->current_state == Configuration::get('PS_OS_PAYMENT_PENDING')) {
                    $order->setCurrentState(Configuration::get('PS_OS_PAYMENT'));
                }
            }
        }
    }
}

[INFO] En Bitcoin, se recomienda esperar 3 confirmaciones para transacciones pequeñas y 6 confirmaciones para montos altos. En Ethereum, 12 bloques (aprox. 3 minutos) son suficientes.

Optimización y Seguridad Avanzada

Mitigación de Volatilidad

Si no conviertes a fiat automáticamente, debes protegerte contra caídas bruscas del precio.

  • Fijación de tipo de cambio: Al momento del checkout, congela el precio en BTC/USDT durante 15-30 minutos.
  • Sobrecargo dinámico: Añade un 2-5% al precio en cripto para cubrir fluctuaciones.
  • Stablecoins: Prioriza USDC, DAI o USDT sobre Bitcoin o Ethereum para pagos.

Gestión de Claves Privadas (HSM)

Para autocustodia, nunca almacenes claves en texto plano en la base de datos.

# Usa variables de entorno en .env
CRYPTO_MASTER_SEED="mnemonic phrase twelve words..."
CRYPTO_HD_PATH="m/44'/0'/0'/0/"

Mejor aún, usa un HSM en la nube como AWS CloudHSM o un servicio como Fireblocks para firmar transacciones.

Manejo de Reembolsos

Los pagos cripto son irreversibles. Si necesitas reembolsar, debes enviar una nueva transacción.

public function processRefund($orderId, $amountBTC)
{
    $order = new Order($orderId);
    $bitcoin = new BitcoinClient(...);
    // Obtener la dirección del cliente desde la transacción original
    $tx = $bitcoin->gettransaction($order->transaction_id);
    $customerAddress = $tx['details'][0]['address'];

    $txid = $bitcoin->sendtoaddress($customerAddress, $amountBTC);
    // Registrar la transacción de reembolso
}

Cumplimiento Normativo y Fiscalidad

Integrar pagos cripto PrestaShop implica obligaciones legales.

  • KYC/AML: Si tu procesador externo no lo hace, debes implementar verificación de identidad para montos altos (ej. > 10.000 EUR). PrestaShop no tiene esto nativo; necesitas un módulo como KYC Module.
  • Facturación: En la UE, el tratamiento fiscal de las criptos varía. Algunos países exigen emitir factura en EUR (conversión al momento de la venta) y declarar la ganancia patrimonial si retienes las criptos. Consulta con un asesor fiscal.
  • Registro de Transacciones: Guarda en la base de datos: dirección de envío, hash de transacción, tipo de cambio, fees de red, y timestamp del bloque.

Resolución de Problemas Comunes

El pago no se confirma automáticamente

  • Causa: El IPN no llega al servidor (firewall bloqueando puerto 443, SSL caducado, o URL de IPN incorrecta).
  • Solución: Revisa los logs del servidor web. Prueba con un servicio como webhook.site para depurar.

El cliente paga pero el pedido queda en "Pendiente"

  • Causa: La transacción tiene pocas confirmaciones o el cron job no se ejecuta.
  • Solución: Aumenta la frecuencia del cron. Si usas Bitcoin, verifica que txindex=1 esté activo en el nodo.

Error de límite de API del procesador

  • Causa: Muchas solicitudes simultáneas.
  • Solución: Implementa colas de trabajo (RabbitMQ o Redis) para las llamadas API. Cachea las cotizaciones de precios durante 30 segundos.

Conclusión y Próximos Pasos

La integración de pagos cripto PrestaShop es un proyecto que combina comercio electrónico, finanzas descentralizadas y seguridad informática. Ya sea usando un procesador externo (recomendado para el 90% de los casos) o una integración directa con Bitcoin o Ethereum, la clave está en:

  1. Elegir el modelo correcto según tu tolerancia al riesgo y recursos técnicos.
  2. Automatizar la gestión de estados mediante IPN y crons.
  3. Proteger las claves con HSM o procesadores de custodia.
  4. Cumplir con la regulación local para evitar problemas fiscales.

Para equipos que quieran ir más allá, explorar Lightning Network (para pagos instantáneos y de bajo costo en Bitcoin) o Layer 2 de Ethereum (Optimism, Arbitrum) será el siguiente paso natural. La infraestructura está madura; solo falta implementarla con cabeza.

[TIP] Antes de lanzar en producción, realiza pruebas exhaustivas en la testnet de Bitcoin (testnet3) o en la red de pruebas de Ethereum (Sepolia). La mayoría de los procesadores ofrecen entornos sandbox.

¿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