VibeFox Redsys for PrestaShop — Ayuda
Requisitos
PrestaShop: 8.0 a 9.x.
PHP: 8.0 o posterior. El módulo se niega a instalarse en versiones anteriores de PHP.
Cuenta de comercio Redsys: tu banco (el adquirente que te dio el TPV virtual de Redsys) te proporciona el código de comercio (FUC), el número de terminal y el acceso al panel de administración de Redsys, donde se muestra la clave secreta SHA-256 de cada entorno. La clave del entorno de pruebas es distinta de la real. La notificación online (HTTP) debe estar activa para tu terminal. Pregunta a tu banco si no estás seguro.
Moneda de la tienda: una de las monedas que admite el módulo (ver Configuración), y tu terminal de Redsys debe estar habilitado por el banco para ella. La mayoría de los terminales aceptan solo EUR.
Tienda accesible: Redsys debe poder llegar a tu tienda desde internet, sin inicio de sesión ni bloqueo de cortafuegos, para enviar las notificaciones de pago.
Clave de licencia de VibeFox: se compra en vibefox.net. Una clave funciona en un dominio.
Instalación
1. En el back office ve a Modules > Module Manager y haz clic en Upload a module. Elige el archivo ZIP del módulo.
2. Cuando termine la subida, haz clic en Configure, o busca VibeFox Redsys Gateway más tarde en la lista de módulos y haz clic en Configure.
3. Pega tu clave de licencia de VibeFox en License key, en el bloque de licencia de la parte superior de la página Configure, y haz clic en Activate (consulta Clave de licencia).
4. Introduce tu código de comercio, el terminal y la clave secreta de cada entorno (ver Configuración).
5. Activa Enable/Disable y haz clic en Save. Prueba un pago con Test Mode activado y luego desactiva Test Mode para aceptar pagos reales.
Al instalarse, el módulo crea el estado de pedido Redsys payment on hold. PrestaShop ofrece el nuevo módulo de pago para los países activos en ese momento, y para todas las monedas y grupos de clientes. Puedes cambiarlo en Payment > Preferences; los países que actives más tarde deben marcarse allí para el módulo.
Configuración
Todos los ajustes están en la página del módulo: Modules > Module Manager > VibeFox Redsys Gateway > Configure. Cada sección tiene su propio botón Save, que guarda toda la página. Encima de los campos, la página te avisa si el código de comercio falta o no está formado solo por dígitos, si una clave secreta no es una clave SHA-256 válida de Redsys, si la clave del modo actual está vacía (en ese caso el método de pago se oculta en la finalización de compra) y si la moneda de la tienda no es compatible. Mientras el modo de prueba está activado, muestra Test mode is active: payments go to the Redsys test environment (SIS-T), no real money is charged. Si Title está vacío, la página muestra Enter a title for the payment method. y no se guarda nada.
Redsys
Enable/Disable: Enable Redsys Gateway activa o desactiva el método de pago. Por defecto: desactivado.
Title: el nombre del método de pago que ven los clientes en la finalización de compra. También es el nombre del método de pago guardado en el pedido. Por defecto: Credit/Debit Card (Redsys). Obligatorio.
Description: el texto que se muestra debajo del método de pago en la finalización de compra. Por defecto: Pay securely with your credit or debit card via Redsys.
Cuenta de Redsys
Tu banco te proporciona el código de comercio, el terminal y el acceso al panel de administración de Redsys, donde se muestra la clave secreta SHA-256 de cada entorno. La sección incluye un enlace al panel de administración de Redsys.
Merchant Code (FUC): tu código de comercio de Redsys, de hasta 9 dígitos. Cualquier carácter que no sea un dígito se elimina al guardar.
Terminal Number: el número de terminal asignado por tu banco, de hasta 3 dígitos. Por defecto: 1. Un campo vacío se guarda como 1.
Secret Key (SHA-256) — live: la clave SHA-256 en Base64 del entorno real (de producción), normalmente de 32 caracteres. Se usa cuando el modo de prueba está desactivado.
Modo de prueba (SIS-T)
El entorno de pruebas de Redsys tiene su propia clave secreta. La sección muestra los datos públicos de prueba de Redsys: código de comercio 999008881, terminal 1, clave sq7HjrUOBfKmC576ILgskD5srU870gJ7, tarjeta 4548 8100 0000 0003, caducidad 12/49, CVV 123. En modo de prueba no se cobra dinero real.
Test Mode: los pagos y reembolsos van al entorno de pruebas de Redsys (SIS-T) y se firman con la clave de prueba. Por defecto: activado. Desactívalo para aceptar pagos reales. Mientras está activado, la finalización de compra muestra TEST MODE: Redsys test environment, no real money is charged. debajo del método de pago.
Secret Key (SHA-256) — test: la clave SHA-256 en Base64 del entorno de pruebas. Usa tu propia clave de prueba o la clave pública de prueba de arriba.
Las claves guardadas nunca se vuelven a mostrar. El campo queda vacío y muestra Saved — leave empty to keep it. Escribe un valor nuevo solo si quieres cambiarla.
Clear saved secrets: marca una clave y haz clic en Save para eliminarla. Un campo vacío conserva el valor guardado.
Página de pago y pedidos
Commerce Name: el nombre de la tienda que se muestra en la página de pago de Redsys, de como máximo 25 caracteres. Por defecto: el nombre de tu tienda, recortado a 25 caracteres.
Order Status After Payment: el estado del pedido que se asigna tras un pago correcto.
Las diferencias de importe o moneda, los pagos de prueba mientras la tienda está en modo real y los pagos de intentos cancelados siempre van a Redsys payment on hold.
Notificaciones de pago
Notification URL: Redsys informa de cada pago a esta dirección de tu tienda. Se muestra en esta sección y tiene el aspecto de https://your-shop/module/wcp_redsys_gateway/notify con URL amigables. El módulo la envía a Redsys con cada pago, así que no hay nada que copiar en el panel de Redsys. La notificación online (HTTP) debe estar activa para tu terminal. Pregunta a tu banco si no se crea ningún pedido tras un pago correcto. Las notificaciones sin firma válida se rechazan. Sin la notificación, no se crea ningún pedido.
Avanzado
Debug log: escribe los detalles de los pagos, notificaciones y reembolsos en logs/rdsg_debug.log.php dentro de la carpeta del módulo. El archivo no se puede abrir desde la web. Los errores siempre se registran, incluso con esta opción desactivada. Las claves, firmas y datos de tarjeta nunca se registran. Por defecto: desactivado.
Log: muestra el tamaño y las últimas entradas del registro. Haz clic en Clear log para vaciarlo.
Delete Data: cuando está activado, al desinstalar el módulo se eliminan los ajustes de la pasarela y el registro. Los registros de pagos de Redsys de los pedidos (necesarios para los reembolsos) y el estado de pedido Redsys payment on hold se conservan siempre. Por defecto: desactivado.
Monedas admitidas
EUR, USD, GBP, JPY, CHF, CAD, AUD, NZD, NOK, SEK, DKK, PLN, CZK, HUF, BGN, RON, ILS, INR, MYR, SGD, THB, SAR, ZAR, RUB, BRL, MXN, ARS, CLP, COP, PEN, CNY, TWD. El método de pago se oculta para los carritos en otras monedas.
Finalización de compra
En el paso de pago el cliente elige el método de pago (por defecto Credit/Debit Card (Redsys)) y confirma el pedido. El cliente ve Redirecting to Redsys for payment. Please wait... y pasa a la página de pago de Redsys de tu banco. Si el navegador no continúa por sí solo, el cliente hace clic en Pay via Redsys, o en Choose another payment method para volver atrás. En este punto todavía no existe ningún pedido.
En la página de Redsys el cliente paga con tarjeta con 3-D Secure, o con Bizum u otro método que tu banco haya habilitado para el terminal. La página usa el idioma del carrito (español, inglés, catalán, francés, alemán, italiano, portugués y más), o inglés para otros idiomas. El importe es el total del carrito en la unidad menor de la moneda del carrito, por ejemplo EUR 43,45 como 4345, y JPY o CLP sin decimales. El pago se describe como Cart con el número de carrito y el nombre de tu tienda.
Tras pagar, el cliente vuelve a tu tienda. El pedido se marca como pagado solo después de que Redsys lo confirme mediante la notificación firmada: la notificación crea el pedido, y el cliente ve la página estándar de confirmación de pedido con Your payment with Redsys has been received. Si el pedido pasó a Redsys payment on hold, la página muestra Your payment with Redsys has been received and is being reviewed by the store. Si la notificación aún no ha llegado, una página Payment confirmation muestra Redsys is confirming your payment. If you completed the payment, your order will be created in a few moments — please do not pay again. con los botones Check again y Back to checkout.
Si el cliente cancela o el pago es denegado, Redsys devuelve al cliente a la finalización de compra con The Redsys payment was not completed. You can try again or choose another payment method. El carrito se conserva y el cliente puede volver a pagar. Cada nuevo intento recibe un nuevo número de pedido de Redsys, y un pago hecho desde cualquiera de ellos, por ejemplo desde una segunda pestaña del navegador, sigue siendo reconocido.
Si el pago no se puede enviar a Redsys, el cliente se queda en la finalización de compra con un breve mensaje: Redsys payments are not configured correctly. Please choose another payment method or contact us., un aviso de que la moneda no se acepta, o The order total must be greater than zero.
La notificación funciona mientras la tienda está en modo de mantenimiento y no la bloquea la restricción por país de tu tienda.
El módulo acepta pagos únicos, autorizados y capturados de inmediato en la página de Redsys. No tiene formulario de tarjeta en tu propio sitio (InSite o iframe), ni tarjetas guardadas, pagos con un clic o tokenización, ni suscripciones o pagos recurrentes, ni preautorización con captura posterior, ni enlaces de pago para pedidos creados en el back office.
Pedidos y reembolsos
Estados del pedido
No order yet: el cliente fue enviado a Redsys y no ha pagado, el pago fue denegado o cancelado, o la notificación de Redsys todavía no ha llegado. Solo existe el carrito.
Payment accepted, Delivered or Redsys payment on hold: el pago fue confirmado. El estado sigue a Order Status After Payment. El pago se registra con el número de pedido de Redsys (Ds_Order) como ID de transacción, y una nota muestra el número de pedido de Redsys, el código de autorización y el código de respuesta, con la marca [TEST] en los pagos de prueba.
Redsys payment on hold after payment: Redsys informó de un importe o una moneda distintos del total del carrito (por ejemplo, el carrito se cambió en otra pestaña después de iniciar el pago), llegó un pago de prueba mientras la tienda está en modo real (no se cobró dinero real y no se registra ningún pago), o el cliente pagó tras cancelar ese pago en la página de Redsys. La nota lo explica. Comprueba el pago en el panel de administración de Redsys y luego tramita el pedido o reembolsa el pago.
Refunded: el pago fue reembolsado por completo a través del módulo.
Un pago denegado nunca modifica un pedido existente. Para los códigos de respuesta más frecuentes, el registro y las notas dan un motivo breve, como Insufficient funds, Card expired o Cancelled by the customer. Si llega un segundo pago distinto para un carrito que ya tiene pedido, el pedido no se modifica. Una nota te pide reembolsar el pago duplicado en el panel de administración de Redsys. Si Redsys indica que un pago sigue en curso, se añade una nota y el pedido espera el resultado final.
Bloque de pago de Redsys
La página del pedido muestra un bloque Redsys payment con el número de pedido de Redsys (Ds_Order), el código y la respuesta de autorización, el entorno (real o de prueba), el importe cobrado y reembolsado, una insignia Test mode para los pagos de prueba, una indicación de revisión para los pedidos en espera, el historial de reembolsos, las Redsys notes del pedido y todos los números de pedido de Redsys emitidos para el carrito.
Reembolsos
En el bloque Redsys payment introduce el importe (se rellena el importe aún no reembolsado), opcionalmente un motivo, y haz clic en Refund via Redsys. Confirma la pregunta Refund this amount through Redsys? This cannot be undone. Se admiten reembolsos totales y parciales. Necesitas el derecho a editar pedidos; no hace falta acceso a las páginas de módulos. Los reembolsos se hacen por el importe y en la moneda que Redsys cobró, así que tras una diferencia de importe o moneda puedes reembolsar hasta lo que el cliente realmente pagó, no el total del pedido. El reembolso se envía a través de la API REST de Redsys al entorno en el que se hizo el pago (prueba o real), firmado con la clave de ese entorno, y la firma de la respuesta se comprueba. Si Redsys no acepta el reembolso, el bloque muestra el error y no se registra ningún reembolso. Un reembolso correcto se añade al historial de reembolsos y a las notas con el número de pedido de Redsys y el motivo. Un reembolso total pone el pedido en Refunded. Un reembolso parcial no cambia el estado.
El módulo no crea facturas de abono. Los botones estándar de reembolso de PrestaShop en la página del pedido no devuelven dinero a través de Redsys.
Los reembolsos hechos en el panel de administración de Redsys no se registran como reembolsos del módulo. Cuando Redsys envía una notificación de ellos, se añade una nota al pedido. El estado del pedido no cambia automáticamente.
Clave de licencia
El módulo funciona con una clave de licencia de VibeFox de vibefox.net. El bloque de licencia License — VibeFox Redsys Gateway es el primer bloque de Modules > Module Manager > VibeFox Redsys Gateway > Configure, encima de los ajustes. Pega la clave en License key y haz clic en Activate. Después, el bloque muestra la clave enmascarada, el estado (por ejemplo, la fecha hasta la que la licencia está activa y tu dominio) y los botones Check now para volver a comprobar el estado, Change key para introducir otra clave y Remove key para eliminar la clave de esta tienda. Debajo aparecen la línea Product: presta-payment-redsys y el enlace Manage licenses and domains in your account, que abre tu cuenta de vibefox.net. Solo los empleados con el permiso Configure para el módulo pueden cambiar la clave. Los textos del bloque siguen el idioma del back office (se incluyen el inglés y el ruso).
Si la clave no es aceptada, el bloque indica el motivo, por ejemplo Key not found, This key belongs to another product, Domain limit reached o License expired on seguido de una fecha. Después de cambiar la dirección de la tienda, o tras liberar un hueco de dominio en tu cuenta, haz clic en Check now. Si no se puede contactar con el servidor de licencias, el módulo sigue funcionando con el último estado conocido.
Una clave funciona en un dominio: el dominio de la tienda principal, también en una configuración multitienda. Quitar la clave de la tienda no libera su hueco de dominio. Libera el hueco en tu cuenta de vibefox.net.
Sin una clave activa, Redsys no se muestra a los clientes en la finalización de compra. Si de todos modos se inicia un pago, el cliente ve This payment method is not available. Please choose another one. La tienda de PrestaShop no sabe que has iniciado sesión en el back office, así que el método de pago también queda oculto para ti: puedes configurar el módulo antes de comprar una clave, pero no probarlo en la finalización de compra. Aparece un recordatorio en Modules > Module Manager, en la pestaña Alerts. Los pedidos existentes no se ven afectados: los pagos ya iniciados se siguen confirmando y los reembolsos funcionan.
Cuando una licencia caduca, el módulo sigue funcionando, pero las actualizaciones y el soporte requieren una renovación. El estado se vuelve a comprobar automáticamente mientras trabajas en el back office: una vez al día durante los primeros 14 días tras introducir la clave, y después una vez a la semana. No hace falta ninguna tarea cron. Desinstalar o restablecer el módulo elimina siempre la clave de licencia y el estado de la licencia.
Solución de problemas
Redsys no aparece en la finalización de compra: comprueba que la licencia está activa, que Enable/Disable está activado, que el código de comercio y el terminal están rellenados y que el modo actual tiene una clave válida: Secret Key (SHA-256) — test en modo de prueba, Secret Key (SHA-256) — live en modo real. Comprueba que la moneda del carrito está en la lista de monedas admitidas. La página de ajustes muestra un aviso para cada uno de estos problemas. En Payment > Preferences comprueba que el módulo está permitido para la moneda del carrito, el país del cliente y el grupo del cliente.
El pago se realizó, pero no se creó ningún pedido: la notificación de Redsys no llegó a tu tienda. Pide a tu banco que compruebe que la notificación online (HTTP) está activa para tu terminal. Comprueba que la dirección que aparece en Notification URL es accesible desde internet, sin inicio de sesión ni bloqueo de cortafuegos. Activa Debug log y revisa el campo Log en la página del módulo.
Notification answers Forbidden: la firma no coincide con la clave secreta del entorno en el que se inició el pago, o el código de comercio de la notificación no es el tuyo. Comprueba que las claves secretas y el código de comercio de los ajustes son los de tu terminal.
Notification answers Order not found: la notificación estaba bien firmada, pero ningún carrito de esta tienda usa ese número de pedido de Redsys.
Notification answers Busy: otra notificación estaba procesando el carrito en ese mismo momento, o no se pudo crear el pedido (por ejemplo, el módulo está desactivado). Redsys reintenta la notificación. El registro muestra el motivo.
Notification answers Bad request: la solicitud no tenía parámetros de Redsys o estaban mal formados. No llegó de Redsys en el formato esperado.
Order is Redsys payment on hold after payment: lee las notas del bloque Redsys payment (ver Estados del pedido) y luego tramita el pedido o reembolsa el pago.
Test payments do not confirm orders in live mode: un pago de prueba nunca paga un pedido mientras Test Mode está desactivado. En su lugar, el pedido se pone en espera con una nota. Usa el modo de prueba con la clave de prueba para los pagos de prueba.
Refund fails: lee el error. Redsys refund: the merchant code or the TEST secret key is not configured. (o LIVE) significa que falta la clave del entorno del pago. Los códigos de error de Redsys se explican en el mensaje, por ejemplo SIS0057 (el importe supera lo que queda del pago), SIS0056 (no se encontró el pago original: otro entorno o terminal), SIS0042 (error de firma; comprueba la clave de este entorno), SIS0026 (código de comercio o terminal desconocido) y SIS0027 (moneda no configurada para el terminal). Si no se puede contactar con Redsys, el reembolso no se hace. Inténtalo más tarde.
Tu terminal acepta una moneda que no está en la lista: los desarrolladores pueden cambiar la lista de monedas con el hook actionRdsgCurrencyCodes. Añade una moneda solo si tu banco la ha habilitado para el terminal.
Desinstalación
Ve a Modules > Module Manager, abre el menú junto a VibeFox Redsys Gateway y elige Uninstall. La clave de licencia y el estado de la licencia de este módulo siempre se eliminan. Si Delete Data está activado, se eliminan los ajustes de la pasarela y el registro. Si está desactivado, todos los ajustes se conservan para una reinstalación posterior. Los registros de pagos y reembolsos de Redsys y el estado de pedido Redsys payment on hold se conservan siempre, así que los pedidos pagados antes se pueden reembolsar tras una reinstalación. Los pedidos existentes conservan sus notas de pago y sus ID de transacción.
Redsys es una marca registrada de su respectivo titular. Este módulo no está afiliado a Redsys ni cuenta con su aprobación.