VibeFox Cardcom for PrestaShop — Ayuda
Requisitos
PrestaShop: 8.0 a 9.x.
PHP: 8.0 o posterior. El módulo no se instala en versiones anteriores de PHP.
HTTPS: tu tienda debe ser accesible desde internet por HTTPS, para que Cardcom pueda enviar la notificación de pago.
Moneda: la moneda del carrito debe ser ILS, USD, EUR o GBP. Para cualquier otra moneda, el método de pago se oculta en el proceso de compra.
Cuenta de Cardcom: para los pagos reales necesitas una cuenta de comerciante de Cardcom con número de terminal, nombre de usuario de API y contraseña de API. Los pagos solo necesitan el número de terminal y el nombre de usuario de API. La contraseña de API se usa solo para los reembolsos desde PrestaShop. El modo de prueba funciona sin cuenta de Cardcom.
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 más tarde VibeFox Cardcom Payment Gateway en la lista de módulos y haz clic en Configure.
3. Introduce 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 (ver Clave de licencia).
4. Activa Enable/Disable, deja Test Mode activado y haz clic en Save. Haz un pedido de prueba con la tarjeta 4580 0000 0000 0000, cualquier fecha de caducidad futura y CVV 123.
5. Para los pagos reales, desactiva Test Mode, introduce el Terminal Number, el API Username y la API Password que te dio Cardcom y haz clic en Save.
Al instalar, el módulo crea el estado de pedido Cardcom payment on hold. PrestaShop ofrece un nuevo módulo de pago para todas las monedas, países y grupos de clientes. Puedes limitarlos en Payment > Preferences.
Configuración
Todos los ajustes están en la página del módulo: Modules > Module Manager > VibeFox Cardcom Payment Gateway > Configure. Cada sección tiene su propio botón Save, que guarda toda la página. Encima de los campos, la página muestra una advertencia mientras el modo de prueba está activado. En modo real avisa si faltan el número de terminal o el nombre de usuario de API (en ese caso Cardcom se oculta en el proceso de compra), si los campos del modo real contienen el terminal de prueba público 1000 / CardTest1994 (Cardcom también se oculta, porque no se cobraría dinero real), y recuerda que sin la contraseña de API no son posibles los reembolsos desde PrestaShop. También avisa si la moneda predeterminada de tu tienda no es compatible. Si guardas el modo real con credenciales vacías o de prueba, aparece un mensaje de error que indica que la pasarela permanece oculta en el proceso de compra hasta que introduzcas tu propio número de terminal y nombre de usuario de API.
Cardcom
Enable/Disable: Enable Cardcom Payment 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 el proceso de compra. También es el nombre del método de pago guardado en el pedido. Por defecto: Credit Card (Cardcom). Obligatorio.
Description: el texto que se muestra debajo del método de pago en el proceso de compra. Por defecto: Pay securely with your credit card via Cardcom.
Modo de prueba
El modo de prueba usa el terminal de prueba público de Cardcom 1000 (usuario de API CardTest1994). No se cobra dinero real y no hace falta una cuenta de Cardcom. Tarjeta de prueba: 4580 0000 0000 0000, cualquier fecha de caducidad futura y CVV 123. En modo de prueba, el proceso de compra también muestra una línea con esta tarjeta de prueba.
Test Mode: activa el modo de prueba (terminal 1000, sin dinero real). Por defecto: activado. Desactívalo para aceptar pagos reales con las credenciales reales de abajo. Los reembolsos siempre se envían con las credenciales del modo en que se pagó el pedido.
Credenciales reales
El número de terminal, el nombre de usuario de API y la contraseña de API te los proporciona Cardcom con tu cuenta de comerciante: en el panel de Cardcom, en los ajustes de API, o a través del soporte de Cardcom. Estos campos solo se usan en modo real.
Terminal Number: tu número de terminal de Cardcom. Solo puede contener dígitos. Si introduces otra cosa, se muestra un error y se mantiene el valor anterior.
API Username: tu nombre de usuario de API de Cardcom (ApiName) para este terminal. Los espacios se eliminan al guardar.
API Password: tu contraseña de API de Cardcom. Solo se necesita para los reembolsos desde PrestaShop. La contraseña guardada no se vuelve a mostrar: el campo queda vacío y muestra Saved — leave empty to keep it. Escribe un valor nuevo solo si quieres cambiarla.
Clear the saved API password: marca la casilla y haz clic en Save para eliminar la contraseña. Un campo vacío mantiene el valor guardado.
Página de pago
Notification URL: Cardcom envía las notificaciones de pago (IndicatorUrl) a esta dirección. Con URLs amigables tiene este aspecto: https://your-shop/module/wcp_cardcom_payment_gateway/webhook, posiblemente con un código de idioma como /en/. La dirección se pasa a Cardcom automáticamente con cada pago, junto con el ID del carrito, así que no hay nada que configurar en Cardcom. Debe ser accesible desde internet por HTTPS.
Operation: lo que hace Cardcom en la página de pago.
Max Installments: el número máximo de cuotas (pagos) que el cliente puede elegir en la página de Cardcom, de 1 a 36. 1 significa sin cuotas. Por defecto: 1.
Success Order Status: el estado del pedido tras un pago confirmado. El pedido se crea directamente en este estado.
Los pagos que no coinciden con el pedido siempre pasan a Cardcom payment on hold.
Avanzado
Debug log: registra las peticiones a la API y las notificaciones en logs/cardcom_p_debug.log.php de la carpeta del módulo. El archivo no se puede abrir desde la web. Los errores siempre se registran. Nunca se escriben credenciales, tokens de tarjeta ni datos del titular. Por defecto: desactivado.
Log: muestra el tamaño y las entradas más recientes del registro. Haz clic en Clear log para vaciarlo.
Delete on Uninstall: cuando está activado, al desinstalar el módulo se eliminan de forma permanente los ajustes y los registros. Los pedidos, las transacciones y los reembolsos de Cardcom y el estado de pedido Cardcom payment on hold siempre se conservan, así que los pedidos antiguos se pueden reembolsar tras una reinstalación. Por defecto: desactivado.
Finalizar compra
En el paso de pago, el cliente elige el método de pago (por defecto Credit Card (Cardcom)) y ve la nota You will be redirected to the secure Cardcom payment page. Tras confirmar, el módulo crea una página de pago de Cardcom por el total del carrito en la moneda del carrito y envía al cliente allí. En este punto todavía no existe ningún pedido. La página se abre en hebreo si el idioma del cliente es el hebreo, y en inglés en los demás casos. Los productos del carrito se envían a Cardcom como nombre del producto. El cliente introduce los datos de la tarjeta y, si las cuotas están permitidas, elige el número de pagos.
Después de pagar, el cliente vuelve a tu tienda. El pedido se marca como pagado solo cuando Cardcom lo confirma. Cardcom llama a la dirección de notificación, y el módulo solo toma de esa llamada el código de la página de pago. Comprueba que ese código lo emitió tu tienda para ese carrito y luego pide a Cardcom, de servidor a servidor, el resultado real. Si la notificación llega tarde, la misma comprobación se ejecuta cuando el cliente vuelve. Entonces se crea el pedido y el cliente ve la página de confirmación de pedido estándar con Your payment with Cardcom has been received. Si Cardcom todavía no ha confirmado el pago cuando el cliente vuelve, aparece una página de Payment confirmation con Your payment is being confirmed by Cardcom. You will receive an e-mail as soon as it is confirmed. y un botón Check again; la notificación crea el pedido en cuanto llega.
Si el pago no se completa o Cardcom lo rechaza, el cliente vuelve al proceso de compra con The card payment was not completed. Please try again or choose a different payment method. No se crea ningún pedido y el carrito se conserva. El cliente puede volver a intentarlo: cada intento obtiene una nueva página de pago de Cardcom. Un pago hecho en una página de pago anterior del mismo carrito sigue reconociéndose, y un rechazo en una página anterior no afecta a un intento nuevo.
Si Cardcom no puede abrir la página de pago, el cliente se queda en el proceso de compra con un mensaje breve, por ejemplo Could not connect to Cardcom. Please try again in a moment., o con un mensaje de que Cardcom no pudo abrir la página de pago, junto con el código de Cardcom, y puede elegir otro método de pago.
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 con tarjeta solo en la página de Cardcom. No tiene tarjetas guardadas ni pagos con un clic, ni suscripciones, no cobra tokens guardados, no tiene ajustes de factura o recibo de Cardcom, ni Bit, Apple Pay, Google Pay o PayPal a través de Cardcom, ni modo iframe ni cargos con captura posterior.
Pedidos y reembolsos
Estados del pedido
No order yet: el cliente fue enviado a Cardcom y no ha pagado, el pago fue rechazado o Cardcom todavía no ha confirmado el pago. Solo existe el carrito.
Payment accepted, Delivered or Cardcom payment on hold: el pago fue confirmado. El estado sigue a Success Order Status. El pago se registra con el número de operación (deal) de Cardcom como ID de transacción. Un mensaje privado del pedido muestra la transacción de Cardcom y, cuando Cardcom los informa, los últimos cuatro dígitos de la tarjeta, el número de factura y el número de cuotas. Los pagos de prueba se marcan con Test mode — no real money was charged.
Cardcom payment on hold after payment: Cardcom confirmó un pago que no coincide con el pedido, por ejemplo porque el carrito se cambió después de abrir la página de pago, o porque se cobró otro importe o moneda. El mensaje lo explica y el bloque de Cardcom lo muestra en Needs review. El pago se registra por el importe que cobró Cardcom cuando la moneda coincide con la del pedido. Compara el pago en el panel de Cardcom con el pedido y después completa el pedido o reembolsa el pago.
Refunded: el pago se reembolsó por completo a través del módulo.
Si llega un segundo pago correcto para un carrito que ya tiene un pedido (por ejemplo, si el cliente pagó en dos pestañas del navegador), el pedido no cambia. Un mensaje avisa de que es posible que se le haya cobrado dos veces al cliente y te pide que lo reembolses desde el panel de Cardcom.
Bloque de pago de Cardcom
La página del pedido muestra un bloque Cardcom payment con la transacción, el código de la página de pago, el estado, la tarjeta, las cuotas, la factura, el token de tarjeta (con Charge + Save token), el importe cobrado, el total del pedido y el importe reembolsado, una insignia Test mode para los pagos de prueba y el historial de reembolsos.
Reembolsos
En el bloque Cardcom payment introduce el importe (se rellena el importe que aún no se ha reembolsado), opcionalmente un motivo, y haz clic en Refund via Cardcom. Confirma la pregunta Refund this amount through Cardcom? This cannot be undone. Se admiten reembolsos totales y parciales, y se pueden hacer varios reembolsos parciales para un mismo pedido. 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 la moneda que cobró Cardcom, así que tras una diferencia de importe o moneda puedes reembolsar hasta lo que el cliente pagó realmente, no el total del pedido. El reembolso se envía con las credenciales del modo en que se pagó el pedido: los pedidos de prueba se reembolsan en el terminal de prueba de Cardcom incluso después de cambiar al modo real, y los pedidos reales siempre usan tus credenciales reales. Los reembolsos reales necesitan API Username y API Password. Si Cardcom 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 los mensajes del pedido, con la transacción de reembolso de Cardcom y el motivo. Un reembolso total pone el pedido en Refunded. Un reembolso parcial no cambia el estado.
El módulo no crea notas de abono. Los botones de reembolso estándar de PrestaShop de la página del pedido no devuelven dinero a través de Cardcom. Los reembolsos hechos en el panel de Cardcom no se comunican a la tienda.
Clave de licencia
El módulo funciona con una clave de licencia de VibeFox de vibefox.net. El bloque de licencia License — VibeFox Cardcom Payment Gateway es el primer bloque de Modules > Module Manager > VibeFox Cardcom Payment Gateway > Configure, por encima de los ajustes. Introduce 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-cardcom y el enlace Manage licenses and domains in your account, que abre tu cuenta de vibefox.net. Solo los empleados con el permiso Configure del módulo pueden cambiar la clave. Los textos del bloque siguen el idioma del back office (se incluyen inglés y ruso).
Si la clave no se acepta, 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 después de liberar una plaza 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. Eliminar la clave de la tienda no libera su plaza de dominio. Libera la plaza en tu cuenta de vibefox.net.
Sin una clave activa, Cardcom no se muestra a los clientes en el proceso de compra. Si se inicia un pago de todas formas, el cliente ve This payment method is not available. Please choose another one. La tienda 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 el proceso de compra. En Modules > Module Manager, en la pestaña Alerts, aparece un recordatorio. 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 necesitan 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
Cardcom no aparece en el proceso de compra: comprueba que la licencia está activa, que Enable/Disable está activado y que la moneda del carrito es ILS, USD, EUR o GBP. En modo real comprueba que Terminal Number y API Username están rellenados con tus propias credenciales, no con el terminal de prueba 1000 / CardTest1994. La página de ajustes muestra una advertencia cuando falta algo. 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 completó, pero no se creó ningún pedido: Cardcom no pudo llegar a tu tienda, por ejemplo por un cortafuegos, una protección con contraseña o un sitio de desarrollo local. La dirección de notificación debe ser accesible desde internet por HTTPS. El pedido también se crea cuando el cliente vuelve a la tienda después de pagar. Activa Debug log y mira el campo Log de la página del módulo.
La notificación responde Missing or invalid lowprofilecode or Unknown lowprofilecode for this order: la llamada no incluía un código de página de pago emitido por tu tienda para ese carrito. No se cambia nada.
La notificación responde Gateway not configured or Indicator check failed: faltan las credenciales del modo en que se creó la página de pago, o no se pudo contactar con Cardcom para la comprobación. No se cambia nada; el pago se vuelve a comprobar cuando el cliente vuelve a la tienda.
La notificación responde Busy, retry: otra petición estaba confirmando el carrito en ese mismo momento, o no se pudo crear el pedido (por ejemplo, porque el módulo está desactivado). Activa Debug log para ver el motivo.
La notificación responde ReturnValue mismatch or Terminal mismatch: Cardcom informó de un pago de otro carrito o de otro terminal. No se cambia nada. Comprueba que Terminal Number es el terminal de tu cuenta.
El cliente ve Payment error: this currency is not supported by Cardcom.: la moneda del carrito no es ILS, USD, EUR ni GBP.
El cliente ve Card payment is temporarily unavailable. Please choose another payment method.: el modo real está activado, pero falta el número de terminal o el nombre de usuario de API, o los campos del modo real contienen el terminal de prueba público.
El cliente ve un error al elegir Cardcom: activa Debug log y mira el campo Log. Allí se escriben los problemas de conexión y los códigos de error de Cardcom.
Order is Cardcom payment on hold after payment: lee el mensaje del pedido o Needs review en el bloque Cardcom payment. El importe o la moneda pagados no coincidían con el pedido. Completa el pedido o reembolsa el pago.
El reembolso falla con API username and API password are required for refunds: introduce la API Password (y el API Username) en los ajustes y vuelve a intentarlo.
El reembolso falla con Could not connect to Cardcom: comprueba el panel de Cardcom antes de volver a intentarlo, porque el reembolso puede haberse hecho o no.
Para desarrolladores, el README recoge el hook actionCardcomSupportedCurrencies, que amplía la lista de monedas (añade solo las monedas activadas en tu terminal de Cardcom), y actionCardcomLowProfileParams, que cambia los parámetros de la página de pago.
Desinstalación
Ve a Modules > Module Manager, abre el menú junto a VibeFox Cardcom Payment Gateway y elige Uninstall. La clave de licencia y el estado de licencia de este módulo siempre se eliminan. Si Delete on Uninstall está activado, se eliminan los ajustes y los registros. Si está desactivado, se conservan todos los ajustes para una reinstalación posterior. Las transacciones y reembolsos de Cardcom y el estado de pedido Cardcom payment on hold siempre se conservan, así que los pedidos pagados antes se pueden reembolsar tras una reinstalación. Los pedidos existentes conservan sus mensajes de pago y sus ID de transacción.
Cardcom es una marca registrada de su respectivo titular. Este módulo no está afiliado a Cardcom ni cuenta con su respaldo.