Gastos de Pago (dfpaymentfees) — Guía completa

Presentación

DataFirefly Gastos de Pago permite aplicar gastos adicionales a cada método de pago de tu tienda PrestaShop 8 o 9. El objetivo es doble: repercutir el coste real de un medio de pago (comisiones de tarjeta, gestión del contra reembolso, tratamiento de cheques o transferencias) y orientar a tus clientes hacia los métodos de pago más ventajosos para tu tienda.

El módulo se basa en un motor de reglas: cada regla combina un importe fijo y/o un porcentaje, una base de cálculo, topes, un umbral de gratuidad y un conjunto de condiciones (grupo de clientes, país, divisa, importe del carrito). Los gastos se muestran al cliente durante el checkout y luego se añaden automáticamente al pedido al validarlo.

Instalación

1. En el back office de PrestaShop, ve a Módulos → Gestor de módulos → Subir un módulo.
2. Selecciona el archivo dfpaymentfees.zip descargado desde tu cuenta DataFirefly.
3. Haz clic en Instalar y luego en Configurar.
4. Vacía la caché de PrestaShop (Parámetros avanzados → Rendimiento → Vaciar caché).
5. Desde la página de configuración, haz clic en Gestionar las reglas de gastos para crear tu primera regla.

Parámetros generales

La página de configuración del módulo (Módulos → Gestor de módulos → Gastos de Pago → Configurar) contiene dos ajustes globales:

• Mostrar los gastos en el checkout — muestra el importe de los gastos junto a cada método de pago durante el pedido. Desactívalo si prefieres aplicar los gastos solo en el momento de la validación, sin anunciarlos en la lista de métodos de pago.
• Etiqueta de los gastos — etiqueta por defecto mostrada al cliente y en el pedido (por ejemplo «Gastos de pago»). Este campo es multiidioma y puede sobrescribirse en cada regla.

Crear una regla de gastos

Desde Gestionar las reglas de gastos, haz clic en Añadir una regla de gastos. El formulario se organiza en cuatro bloques: identificación, importe, topes y condiciones.

Identificación

• Activa — activa o desactiva la regla sin eliminarla.
• Etiqueta (cliente) — el texto mostrado al cliente en el checkout y en el pedido. Campo multiidioma y obligatorio.
• Método de pago — el módulo afectado (por ejemplo ps_wirepayment, ps_checkpayment, tu módulo de tarjeta…), o Todos los métodos de pago para una regla genérica.
• Prioridad — un número entero. Un valor más bajo se evalúa primero. Consulta «Orden de evaluación» más abajo.

Importe de los gastos

• Gasto fijo — un importe fijo añadido (por ejemplo 1.50).
• Gasto en porcentaje — un porcentaje aplicado a la base de cálculo (por ejemplo 2.5 para 2,5 %).
• Incluir los gastos de envío en la base % — si está activo, el porcentaje se aplica a los productos y a los gastos de envío; si no, solo a los productos.
• Base de cálculo con IVA — elige si el porcentaje se calcula sobre el total con IVA o sin IVA.

Ambos importes son acumulables. La fórmula aplicada es:

gasto = gasto_fijo + (base × gasto_porcentaje / 100)

Topes y gratuidad

• Gasto mínimo — si el cálculo da un importe inferior, se aplica este mínimo. 0 = sin mínimo.
• Gasto máximo — limita el importe de los gastos. 0 = sin máximo.
• Umbral de gratuidad — si el total con IVA del carrito alcanza este importe, no se aplica ningún gasto. 0 = desactivado.

Condiciones de aplicación

Cuatro familias de condiciones permiten segmentar con precisión cuándo se aplica la regla. Una lista vacía significa «sin restricción» en ese criterio.

• Grupos de clientes — la regla solo se aplica si el cliente pertenece a uno de los grupos seleccionados. Típicamente: aplicar gastos a los particulares y eximir a los profesionales.
• Países — basado en el país de la dirección de facturación del carrito.
• Divisas — la regla solo se aplica a las divisas seleccionadas.
• Importe mínimo / máximo del carrito — la regla solo se aplica si el total con IVA del carrito está dentro de este intervalo. 0 desactiva el límite correspondiente.

En multitienda, un campo adicional Tiendas permite asociar la regla a una o varias tiendas. Dejarlo vacío asocia la regla a todas las tiendas.

Orden de evaluación de las reglas

Para un método de pago dado, el módulo recupera todas las reglas activas que apuntan a ese módulo (o a «Todos»), ordenadas por prioridad ascendente y luego por identificador. Evalúa las condiciones de cada regla en ese orden y aplica la primera regla cuyas condiciones se cumplen todas. Las reglas siguientes se ignoran.

Caso particular del umbral de gratuidad: si una regla coincide pero el carrito alcanza su umbral de gratuidad, no se aplica ningún gasto — y el módulo no evalúa las reglas siguientes. La gratuidad es por tanto una decisión final, no un simple «pasar a la regla siguiente».

Gestión del IVA

Dos ajustes determinan el tratamiento fiscal de los gastos:

• Importes introducidos con IVA — indica si los importes que has introducido (gasto fijo, topes) ya incluyen el IVA.
• Regla de impuestos — la regla de impuestos de PrestaShop aplicada a los gastos. Selecciona Sin impuesto para gastos sin IVA.

El módulo calcula el tipo aplicable a partir de la regla de impuestos y de la dirección de facturación del cliente, y deduce el desglose:

• Si los importes se introducen con IVA: sin IVA = con IVA / (1 + tipo).
• Si los importes se introducen sin IVA: con IVA = sin IVA × (1 + tipo).

Ambos valores, junto con el tipo aplicado, se guardan en el pedido para tu contabilidad.

Ejemplo de cálculo

Regla: gasto fijo 1,00 € + 2 % del carrito, base con IVA productos + envío, tope máximo 5,00 €, importes introducidos con IVA, IVA 21 %.

• Carrito: 120,00 € con IVA de productos + 5,00 € con IVA de envío = base 125,00 €.
• Gastos brutos: 1,00 + (125,00 × 2 / 100) = 3,50 € con IVA.
• Por debajo del tope de 5,00 €: se mantiene tal cual.
• Desglose: sin IVA = 3,50 / 1,21 = 2,89 €, IVA = 0,61 €.

Visualización del lado del cliente

Cuando la opción Mostrar los gastos en el checkout está activada, el módulo calcula los gastos para cada método de pago disponible y los transmite al front office. En la página /order:

• El importe de los gastos se añade junto a la etiqueta de cada método de pago afectado.
• Un recordatorio aparece bajo la lista de métodos de pago para la opción seleccionada actualmente, y se actualiza en tiempo real cuando el cliente cambia de método de pago.

Esta visualización es puramente informativa: el importe realmente facturado se recalcula en el servidor al validar el pedido.

Aplicación en el pedido

Al validar el pedido (hook actionValidateOrder), el módulo recalcula los gastos para el método de pago realmente utilizado y luego:

1. Actualiza los totales del pedido (total_paid, total_paid_tax_incl, total_paid_tax_excl y total_paid_real si procede).
2. Actualiza los totales de la factura si ya existe una factura.
3. Actualiza el importe del pago registrado, para mantener la coherencia con el importe cobrado.
4. Guarda la línea de gastos (etiqueta, sin IVA, con IVA, tipo) en la tabla df_payment_fee_order.

La línea de gastos se muestra después en la página de confirmación del pedido, en el detalle del pedido del cliente, en la página del pedido del back office, y se añade al correo de confirmación.

Una protección evita el doble procesamiento: si un pedido ya tiene una línea de gastos, el módulo no hace nada.

Compatibilidad con las pasarelas de pago

• Pagos offline (transferencia, cheque, contra reembolso, pago en tienda): el funcionamiento es completo y sin reservas. El cliente ve los gastos, el pedido y la factura los incluyen, y tú cobras el importe total mostrado.
• Pasarelas con redirección o integradas (PayPal, Stripe, soluciones bancarias): el importe transmitido a la pasarela es el calculado por el módulo de pago a partir del carrito. Según tu pasarela y su configuración, ese importe puede no incluir los gastos. Verifica el comportamiento en un entorno de pruebas antes de la puesta en producción.

Para estas últimas, dos enfoques son habituales: reservar las reglas de gastos a los métodos de pago offline, o capturar/ajustar el importe del lado de la pasarela. Nuestro soporte puede asesorarte según la pasarela utilizada.

Multitienda y multiidioma

Multitienda — cada regla se asocia a una o varias tiendas mediante el campo Tiendas del formulario. Solo se evalúan las reglas asociadas a la tienda actual. Una regla guardada sin selección se asocia a todas las tiendas.

Multiidioma — la etiqueta de cada regla es traducible a todos los idiomas activos de la tienda. Si la etiqueta no está rellenada en el idioma del cliente, el módulo utiliza la etiqueta global definida en los parámetros del módulo.

Resolución de problemas

Los gastos no aparecen en el checkout

• Comprueba que la opción Mostrar los gastos en el checkout está activada en los parámetros del módulo.
• Comprueba que la regla está activa y que apunta al método de pago correspondiente (o a «Todos»).
• Comprueba que el contexto del cliente cumple todas las condiciones: grupo, país de facturación, divisa, importe del carrito.
• Asegúrate de que el carrito no alcanza el umbral de gratuidad de la regla.
• Vacía la caché de PrestaShop y fuerza la recarga del navegador (Ctrl+F5) para purgar el JavaScript antiguo.

Los gastos se muestran pero no se añaden al pedido

El cálculo en el checkout y el cálculo en la validación utilizan el nombre técnico del módulo de pago. Si tu módulo de pago registra una etiqueta distinta del nombre técnico, comprueba en la tabla df_payment_fee_order que se ha creado una fila para el pedido. Si no es así, crea una regla que apunte a Todos los métodos de pago para validar el funcionamiento y luego contacta con el soporte indicando el nombre del módulo de pago utilizado.

Una regla no se aplica nunca aunque parezca correcta

Probablemente una regla más prioritaria (valor de prioridad más bajo) coincide primero. Recuerda que solo se aplica la primera regla coincidente. Aumenta el valor de prioridad de las reglas genéricas o afina las condiciones de las reglas competidoras.

El importe del IVA parece incorrecto

Comprueba la coherencia entre el ajuste Importes introducidos con IVA y los valores que has introducido. Un importe introducido con IVA cuando el ajuste indica sin IVA (o al revés) desplaza el desglose. Comprueba también que la regla de impuestos seleccionada se aplica al país de facturación del cliente.

El checkout va lento o se bloquea

Asegúrate de usar la versión 1.0.0 o superior del módulo, vacía la caché de PrestaShop y fuerza la recarga del navegador (Ctrl+F5) para eliminar una versión de JavaScript en caché.

Desinstalación

Desinstala el módulo desde el Gestor de módulos. La desinstalación elimina la pestaña de administración, las variables de configuración y todas las tablas del módulo, incluido el historial de gastos aplicados a los pedidos. Los totales ya registrados en los pedidos existentes no se modifican.