VibeFox Helcim 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 y PCI DSS: los datos de la tarjeta se introducen en tu finalización de compra y se envían desde tu servidor a Helcim por HTTPS. Nunca se guardan ni se registran, pero pasan por tu servidor, así que tu tienda necesita un certificado SSL y tu alojamiento debe cumplir PCI DSS (SAQ D).

Cuenta de Helcim: una cuenta de comerciante de Helcim en Canadá o Estados Unidos y un token de API con derechos de procesamiento de transacciones (véase Configuración). Helcim procesa CAD y USD. Una cuenta de prueba (de desarrollador) de Helcim es opcional para las pruebas.

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 Helcim 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 (ver Clave de licencia).

4. En Helcim, abre All Tools > Integrations > API Access Configuration, crea un acceso de API con derechos de procesamiento de transacciones (compras, preautorizaciones, capturas, reembolsos) y copia su token.

5. Pega el token en Live API token, y el token de tu cuenta de prueba de Helcim en Test API token si tienes una.

6. Elige el Transaction type y las Account currencies, activa Enable / Disable y haz clic en Save. Para probar primero, activa Test mode y paga con tu cuenta de prueba; después, desactívalo.

Al instalar, el módulo crea dos estados de pedido, Helcim payment authorized y Helcim payment on hold. PrestaShop habilita el 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 Helcim 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 la moneda predeterminada de tu tienda no está entre las Account currencies y, mientras el método de pago esté activado, si el token de API del modo actual está vacío. En ese caso, el método de pago se oculta en la finalización de compra.

Helcim

Enable / Disable: Enable Helcim Gateway activa o desactiva el método de pago. Predeterminado: off.

Title: el título del método de pago que se muestra en la finalización de compra. También es el nombre del método de pago guardado en el pedido. Predeterminado: Credit card (Helcim). Obligatorio.

Description: la descripción del método de pago que se muestra en la finalización de compra. Predeterminado: Pay securely with your credit card.

Credenciales de API

En Helcim, ve a All Tools > Integrations > API Access Configuration, crea un acceso de API y copia su token. Dale derechos de procesamiento de transacciones para compras, preautorizaciones, capturas y reembolsos. Las cuentas de prueba de Helcim usan la misma dirección de API que las cuentas reales, así que el modo de prueba simplemente usa el token de tu cuenta de prueba de Helcim.

Live API token: el token de API de tu cuenta real de Helcim. Se usa cuando el modo de prueba está desactivado.

Test mode: usa el Test API token (cuenta de prueba de Helcim). Los pagos, capturas y reembolsos van a tu cuenta de prueba de Helcim, y los clientes ven un aviso de modo de prueba. Las capturas y los reembolsos de un pedido siempre usan el token del modo con el que se pagó el pedido. Predeterminado: off.

Test API token: el token de API de tu cuenta de prueba (de desarrollador) de Helcim. Se usa cuando el modo de prueba está activado.

Los tokens guardados 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 cambiarlo.

Clear saved tokens: marca un token y haz clic en Save para eliminarlo. Un campo vacío mantiene el valor guardado.

Pago

Transaction type: cómo se cobra la tarjeta.

Account currencies: las monedas que tu cuenta de Helcim puede procesar. Los pedidos siempre se cobran en la moneda del carrito. El método de pago se oculta en la finalización de compra para otras monedas.

Avanzado

Debug log: escribe las solicitudes y respuestas de la API en logs/wc_hlg_debug.log.php de la carpeta del módulo. El archivo no se puede abrir desde la web. Los números de tarjeta se reducen a los últimos 4 dígitos. El CVC, la caducidad, los tokens, los nombres, las direcciones, los correos electrónicos y las direcciones IP nunca se registran. Los errores (pagos rechazados o fallidos, errores de la API, capturas y reembolsos fallidos) siempre se registran, incluso cuando esta opción está desactivada. Predeterminado: off.

Log: muestra el tamaño y las últimas entradas del registro. Haz clic en Clear log para vaciarlo.

Delete data on uninstall: si está activado, al desinstalar el módulo se eliminan los ajustes de la pasarela y sus archivos de registro. Las transacciones, reembolsos y estados de pedido de Helcim siempre se conservan, así que los pedidos pagados antes aún pueden capturarse y reembolsarse tras volver a instalar. Predeterminado: off.

Finalización de compra

En el paso de pago, el cliente elige el método de pago (por defecto Credit card (Helcim), con un icono de tarjeta) e introduce Card Number, Expiry (MM/YY), CVC y Cardholder Name en el formulario situado debajo. En modo de prueba, el formulario muestra TEST MODE — payments go to a Helcim test account, no real charges are made. Cuando el cliente realiza el pedido, el módulo comprueba la suma de control del número de tarjeta, que la fecha de caducidad sea válida y no esté vencida, que el CVC tenga 3 o 4 dígitos y que el nombre esté rellenado. Los errores se muestran en la finalización de compra y no se envía nada a Helcim.

Tu servidor envía entonces la tarjeta a Helcim como compra o preautorización por el total del carrito, en la moneda del carrito. La dirección de facturación, el teléfono y el correo electrónico se envían para la verificación de la dirección. El pago aparece en Helcim con un número de factura formado por el número de carrito, -PS y un código corto. Helcim responde en la misma solicitud. El pedido se crea solo después de que Helcim apruebe la transacción, y el cliente llega a la página estándar de confirmación del pedido. Antes de eso no existe ningún pedido.

Solo se ejecuta un intento de pago por carrito a la vez, y un carrito que ya tiene un pedido nunca vuelve a cobrarse. Cada intento usa una clave de idempotencia. Si Helcim no responde, no se crea ningún pedido, y un reintento dentro de 5 minutos devuelve el resultado original de Helcim en lugar de cobrar la tarjeta dos veces. Si el pago fue aprobado pero el pedido no pudo crearse, el siguiente intento del mismo carrito crea el pedido sin volver a cobrar la tarjeta.

Mensajes que el cliente puede ver en la finalización de compra: Your card was declined. Please check the card details or use another card. cuando Helcim rechaza el pago; Payment failed: con el motivo de Helcim para otras solicitudes rechazadas; We could not confirm your payment with the card processor. Please try again in a minute; if the problem persists, contact us before using another card. cuando Helcim no responde; This payment method is temporarily unavailable. Please choose another payment method. cuando falta el token de API o Helcim lo rechaza; Your payment is already being processed. Please wait a moment and check your e-mail before trying again. ante un doble envío; Your payment was received, but the order could not be completed automatically. Please contact us — do not pay again. cuando el pago fue aprobado pero no se pudo crear el pedido. El carrito se conserva. Los detalles técnicos se envían al registro.

El módulo no usa HelcimPay.js ni Helcim.js, así que los datos de la tarjeta pasan por tu servidor. No tiene tarjetas guardadas, suscripciones, pagos ACH o bancarios, Apple Pay, Google Pay ni 3-D Secure, ni webhooks de Helcim.

Pedidos y reembolsos

Estados del pedido

No order: la tarjeta fue rechazada, Helcim no respondió o el cliente aún no ha pagado. Solo existe el carrito. Los rechazos y errores se escriben en el registro.

Payment accepted: se aprobó una compra, o se capturó una preautorización. El pago se registra con el ID de transacción de Helcim, y una nota muestra el ID de transacción, el código de aprobación, el tipo de tarjeta, los últimos 4 dígitos y el modo.

Helcim payment authorized: se aprobó una preautorización. Los fondos solo están retenidos. Captúralos o libéralos con un reembolso total.

Helcim payment on hold: Helcim aprobó una transacción, pero el importe, la moneda o el ID de transacción de su respuesta no coinciden con el carrito, por ejemplo tras una aprobación parcial o si el carrito cambió durante el pago. La nota dice Helcim response verification FAILED. En una compra, el pago se registra con el importe que Helcim cobró realmente. Comprueba la transacción en Helcim antes de enviar el pedido.

Refunded: el pago fue reembolsado por completo a través del módulo.

Canceled: una preautorización no capturada fue liberada. No se cobró al cliente.

Si se aprueba una segunda transacción para un carrito que ya tiene un pedido, el pedido no cambia. Una nota te pide que la compruebes y la anules o reembolses en Helcim.

Bloque de pago de Helcim

La página del pedido muestra un bloque Helcim payment con el ID de transacción (y el ID de la preautorización tras una captura), el tipo de transacción y el estado de la captura, el número de factura, la tarjeta y el código de aprobación, el importe aprobado, el total del pedido y el importe reembolsado, una etiqueta Test mode para los pagos de prueba, el historial de reembolsos y las Helcim notes del pedido. Capturar y reembolsar requiere el permiso para editar pedidos.

Captura

Para un pedido en Helcim payment authorized, haz clic en Capture payment en el bloque y confirma Capture the pre-authorized amount through Helcim? Se captura el total actual del pedido, menos los reembolsos. Puede ser menor que el importe preautorizado, pero no mayor. La captura usa el token del modo con el que se pagó el pedido. Tras una captura exitosa, el pedido pasa a Pago aceptado, y el pago se registra con el ID de transacción de la captura. Si la captura falla, el bloque muestra el motivo y lo añade a las notas.

Reembolsos

En el bloque, introduce el importe (se rellena el importe aún no reembolsado), opcionalmente un motivo, y haz clic en Refund via Helcim. Confirma Refund this amount through Helcim? This cannot be undone. Se admiten reembolsos totales y parciales de una compra o de una preautorización capturada, hasta el importe que Helcim cobró realmente; así, tras una aprobación parcial, no puedes reembolsar más de lo que pagó el cliente. Para una preautorización no capturada el botón es Release pre-authorization: solo se puede liberar el importe total, se elimina la retención y el pedido pasa a Cancelado.

El reembolso se envía en el modo con el que se pagó el pedido, así que ese token debe estar configurado. Solo cuenta si Helcim lo aprueba. Si Helcim lo rechaza, el bloque muestra el error y no se registra ningún reembolso. Un reembolso exitoso se añade al historial de reembolsos y a las notas con el ID de transacción del reembolso de Helcim. Un reembolso total pone el pedido en Refunded. Un reembolso parcial no cambia el estado. Un reintento tras un tiempo de espera no reembolsa dos veces.

El módulo no crea notas de crédito. Los botones de reembolso estándar de PrestaShop en la página del pedido no devuelven dinero a través de Helcim. El módulo no recibe webhooks de Helcim: las capturas, reembolsos y anulaciones realizados en el panel de Helcim no se reflejan en PrestaShop, así que hazlos desde la página del pedido.

Clave de licencia

El módulo funciona con una clave de licencia de VibeFox de vibefox.net. El bloque de licencia License — VibeFox Helcim Gateway es el primer bloque de Modules > Module Manager > VibeFox Helcim Gateway > Configure, por 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-helcim 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 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, Helcim 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 se oculta 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 realizados se conservan, y las capturas y los reembolsos siguen funcionando.

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 por semana. No se necesita ninguna tarea cron. Al desinstalar o restablecer el módulo, siempre se elimina la clave de licencia y el estado de la licencia.

Solución de problemas

Helcim no aparece en la finalización de compra: comprueba que la licencia esté activa, que Enable / Disable esté activado, que el modo actual tenga su token de API (Live API token, o Test API token en modo de prueba) y que la moneda del carrito sea una de las Account currencies. La página de ajustes muestra una advertencia cuando falta el token o la moneda de la tienda no está permitida. En Payment > Preferences, comprueba que el módulo esté permitido para la moneda del carrito, el país del cliente y el grupo de clientes.

El cliente vio «We could not confirm your payment»: Helcim no respondió, así que la tarjeta podría haber sido cobrada. Mira el campo Log: el error indica el carrito y la factura de Helcim. Comprueba esa factura en Helcim antes de volver a cobrar al cliente. Un reintento dentro de 5 minutos devuelve el resultado original y no cobra dos veces.

Los clientes ven «This payment method is temporarily unavailable»: el token de API del modo actual está vacío o Helcim lo rechazó. El registro indica que compruebes el token y sus permisos. Asegúrate de que el acceso de API tenga derechos de procesamiento de transacciones.

Pago fallido por un motivo de Helcim: Helcim rechazó la solicitud, por ejemplo por la tarjeta o por los datos de facturación. El registro tiene los detalles.

El cliente vio «Your payment was received, but the order could not be completed»: Helcim aprobó el pago, pero PrestaShop no pudo crear el pedido (por ejemplo, porque el módulo estaba desactivado). El registro indica el motivo. Cuando el cliente envía de nuevo el mismo carrito, el pedido se crea a partir del pago aprobado sin un segundo cobro.

Pedido en Helcim payment on hold: lee las notas del bloque de Helcim. La respuesta de Helcim no coincidió con el carrito (la verificación de la respuesta falló). Comprueba la transacción en Helcim y después envía el pedido o reembolsa el pago.

No es posible capturar: el importe a capturar debe ser mayor que 0 y no superior al importe preautorizado, y el token del modo con el que se pagó el pedido debe estar configurado.

El reembolso falla: lee el mensaje. Una preautorización no capturada solo se puede liberar por completo. Un mensaje sobre el modo significa que el token del modo con el que se pagó el pedido está vacío. Un reembolso rechazado no se registra.

Pagos de prueba: el modo de prueba envía pagos, capturas y reembolsos a tu cuenta de prueba de Helcim. Los pedidos conservan el modo con el que se pagaron, así que cambiar el modo más tarde no traslada sus capturas y reembolsos a la otra cuenta.

Desinstalación

Ve a Modules > Module Manager, abre el menú junto a VibeFox Helcim Gateway y elige Uninstall. La clave de licencia y el estado de la licencia de este módulo siempre se eliminan. Si Delete data on uninstall 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. Las transacciones y reembolsos de Helcim y los estados de pedido Helcim payment authorized y Helcim payment on hold siempre se conservan, así que los pedidos pagados antes aún pueden capturarse y reembolsarse tras volver a instalar. Los pedidos existentes conservan sus notas de pago y sus ID de transacción.

Helcim es una marca comercial de su respectivo titular. Este módulo no está afiliado ni respaldado por Helcim.