DataFirefly Subscriptions — Guía completa (PrestaShop 8 y 9)

Presentación

DataFirefly Subscriptions convierte su tienda PrestaShop 8 o 9 en una máquina de ingresos recurrentes. El módulo se basa en una arquitectura « card on file »: el cliente paga una sola vez en el checkout mediante una opción de pago nativa, su tarjeta se guarda de forma segura en Stripe, y después un cron diario cobra automáticamente la tarjeta en cada vencimiento y crea un pedido PrestaShop real por el importe exacto, gastos de envío incluidos.

Puntos clave de la arquitectura:

• Un único motor de facturación — ningún objeto Subscription en Stripe, todo lo dirige su tienda. Los cargos dobles son estructuralmente imposibles.
• Importes exactos — cada renovación reconstruye un carrito real y calcula el total con el motor de precios de PrestaShop (descuentos, impuestos, envío).
• 3DS/SCA gestionado — la autenticación reforzada se gestiona en el pago inicial; las renovaciones usan el mecanismo off-session conforme a SCA.
• Ningún dato bancario en PrestaShop — el cumplimiento PCI-DSS lo asume Stripe.

Instalación

1. Descargue el ZIP del módulo desde su cuenta de cliente DataFirefly.
2. En su back office de PrestaShop: Módulos → Gestor de módulos → Subir un módulo, y seleccione el ZIP.
3. El módulo crea automáticamente sus tablas, sus pestañas de administración (Suscripciones, Planes, Logs, Dashboard) y registra sus hooks.
4. Haga clic en Configurar para abrir la página de configuración.

Configuración de Stripe

Claves API

En la configuración del módulo, introduzca sus claves de Stripe. El módulo gestiona dos juegos de claves distintos:

• Modo test: clave pública pk_test_... y clave secreta sk_test_... — para validar el recorrido completo sin cargos reales (tarjeta de prueba 4242 4242 4242 4242).
• Modo live: clave pública pk_live_... y clave secreta sk_live_... — para producción.

Encontrará estas claves en su dashboard de Stripe: Desarrolladores → Claves API. Cambie entre test y live con el interruptor «Modo» del módulo.

Webhook

El webhook solo sirve para los eventos excepcionales (la facturación la dirige el cron, no Stripe). En su dashboard de Stripe: Desarrolladores → Webhooks → Añadir un endpoint, con la URL mostrada en la configuración del módulo (de la forma https://sutienda.com/module/dfsubscription/webhook), y suscríbase a estos tres eventos:

• payment_method.detached — tarjeta eliminada en Stripe: la suscripción pasa a «pago fallido» para avisarle antes del vencimiento.
• charge.dispute.created — disputa (chargeback): registrada en la suscripción correspondiente.
• charge.refunded — reembolso: registrado en la suscripción correspondiente.

Copie después el secreto de firma (whsec_...) proporcionado por Stripe en el campo correspondiente de la configuración.

Configuración del cron

El cron es el motor de las renovaciones: cada día detecta las suscripciones vencidas, cobra las tarjetas guardadas y crea los pedidos. La URL protegida por token se muestra en la configuración y en el dashboard del módulo, de la forma:

https://sutienda.com/module/dfsubscription/cron?token=SU_TOKEN

Cree una tarea cron diaria en su hosting (cPanel, Plesk, crontab) que llame a esta URL. Ejemplo de crontab para una ejecución diaria a las 6:00:

0 6 * * * curl -s "https://sutienda.com/module/dfsubscription/cron?token=SU_TOKEN" > /dev/null 2>&1

Crear planes de suscripción

Los planes se gestionan directamente desde la ficha de producto del back office: Catálogo → Productos → su producto → pestaña Módulos / DataFirefly Subscriptions. Para cada plan, defina:

• Frecuencia de facturación — semanal, quincenal, mensual, trimestral, semestral o anual.
• Frecuencia de entrega — igual que la facturación, semanal, quincenal o mensual. Ejemplo: facturación mensual + entrega semanal = caja semanal con pago mensual.
• Descuento (%) — la reducción concedida a los suscriptores respecto al precio de compra única. Se muestra en la ficha de producto y se aplica también a cada renovación.
• Permanencia mínima — número de ciclos antes de que la cancelación sea posible (0 = cancelación libre).
• Ciclos máximos — para suscripciones de duración limitada (0 = ilimitado).
• Días de prueba — periodo de prueba antes de la primera facturación.

Un producto puede ofrecer varios planes (p. ej. mensual -10 % y anual -20 %): el cliente elige en el bloque «Suscríbete y ahorra» de la ficha de producto.

Recorrido del cliente

Ficha de producto

Un bloque desplegable presenta los planes disponibles con sus precios rebajados. El cliente selecciona su plan (la selección se guarda en base de datos, fiable incluso si cambia de dispositivo) y añade al carrito normalmente.

Checkout y pago

En el paso de pago, la opción «Pagar con tarjeta y activar mi suscripción» aparece si el carrito contiene únicamente productos en suscripción y el cliente ha iniciado sesión. El formulario de tarjeta seguro de Stripe se muestra directamente en la página:

1. El cliente introduce su tarjeta; el 3D Secure se activa automáticamente si su banco lo exige.
2. El pago cubre el total exacto del carrito, envío incluido.
3. La tarjeta se guarda en Stripe para los ciclos siguientes (card on file, con consentimiento conforme a SCA).
4. El módulo verifica de nuevo en el servidor el estado y el importe del pago antes de crear el pedido — nunca se confía en el navegador.

Renovaciones

En cada ejecución del cron, para cada suscripción vencida:

1. El módulo reconstruye un carrito PrestaShop real: producto, combinación, dirección y transportista originales.
2. El descuento del plan se aplica mediante una regla de carrito automática de un solo uso.
3. El total exacto lo calcula el motor de precios nativo — impuestos y envío incluidos si la opción «Envío en las renovaciones» está activada (lo está por defecto).
4. La tarjeta guardada se cobra fuera de sesión por exactamente ese importe.
5. Se crea un pedido PrestaShop estándar, con el estado de pedido de su elección (configurable, p. ej. un estado dedicado «Renovación»).
6. El cliente recibe el email de confirmación de renovación; el evento queda registrado.

Cada pedido de renovación es visible en Pedidos como cualquier venta, con su transacción Stripe asociada — sus exportaciones contables y su gestión de stock funcionan sin cambios.

Dunning: gestión de los fallos de pago

Cuando un cobro de renovación falla (tarjeta caducada, límite, rechazo bancario):

1. La suscripción pasa al estado «pago fallido» y el cliente recibe inmediatamente un email de recordatorio invitándole a actualizar su tarjeta.
2. El cron reintenta automáticamente el pago — por defecto 3 intentos cada 3 días, ambos valores configurables.
3. Tras el número configurado de fallos consecutivos, la suscripción se cancela automáticamente y se informa al cliente.

Cada intento y su resultado quedan registrados en los logs de la suscripción. En la práctica, el dunning recupera del 50 al 70 % de los pagos que se habrían perdido.

Área de cliente «Mis suscripciones»

Accesible desde la cuenta del cliente, esta área lista las suscripciones con su estado, la próxima fecha de facturación y de entrega. Según sus ajustes, el cliente puede:

• Pausar / reanudar — las fechas se recalculan al reanudar.
• Saltar el próximo ciclo — la facturación y la entrega se posponen juntas un periodo.
• Cancelar — libremente, o solo tras la permanencia mínima del plan. Al cancelar, la tarjeta guardada se desvincula automáticamente en Stripe y se envía un email de confirmación.

Cada acción requiere una confirmación y sigue el patrón POST-redirect-GET: sin doble envío posible, con mensajes de confirmación nativos de PrestaShop.

Back office

• Dashboard — MRR, suscripciones activas, tasa de churn, pagos fallidos, URLs de cron y webhook listas para copiar.
• Suscripciones — lista filtrable por estado, frecuencia y cliente; vista detallada con el historial de pedidos generados y los logs, y enlaces directos al pedido y a la ficha del cliente.
• Planes — vista general de todos los planes existentes (la creación se hace desde la ficha de producto).
• Logs — todos los eventos con marca de tiempo: creaciones, renovaciones, fallos, reintentos, pausas, cancelaciones, webhooks recibidos.

FAQ técnica y solución de problemas

La opción de pago no aparece en el checkout

• Compruebe que el carrito contiene solo productos con un plan seleccionado y que el cliente ha iniciado sesión.
• Compruebe que las claves Stripe del modo activo están configuradas.
• Si acaba de migrar desde una versión 1.x: reinstale el módulo o relance la actualización — las restricciones de divisas/países/transportistas las añaden los scripts de migración 2.x y son indispensables para que aparezca la opción.

Las renovaciones no se ejecutan

• Compruebe que la tarea cron está programada y que su URL contiene el token correcto (pruebe la URL en un navegador: debe responder con un resumen JSON).
• Consulte la pestaña Logs: cada ejecución del cron deja una traza.

Un pago 3DS se queda «pendiente»

Si el cliente cierra la página durante la autenticación 3D Secure, no hay ningún cobro y no se crea ningún pedido. Puede simplemente volver a pedir; el pago anterior expirará por sí solo en Stripe.

¿Cómo probar el recorrido completo?

1. Ponga el módulo en modo test e introduzca las claves pk_test/sk_test.
2. Cree un plan en un producto y haga un pedido con la tarjeta 4242 4242 4242 4242 (o 4000 0027 6000 3184 para forzar un desafío 3DS).
3. En la base de datos, adelante la fecha next_billing_date de la suscripción a ayer y llame a la URL del cron: debe aparecer un pedido de renovación.
4. Para probar el dunning, use la tarjeta 4000 0000 0000 0341 (fallo en el cobro off-session).