VibeFox Helcim for WooCommerce — Ayuda
Requisitos
WordPress: 5.8 o posterior.
WooCommerce: 7.0 o posterior, instalado y activo. Sin WooCommerce, el plugin no se activará.
PHP: 8.0 o posterior.
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 mediante HTTPS. Nunca se almacenan ni se registran, pero pasan por tu servidor, por lo que tu tienda necesita un certificado SSL y tu alojamiento debe cumplir con PCI DSS (SAQ D).
Cuenta de Helcim: una cuenta de comerciante de Helcim en Canadá o Estados Unidos y un token de API con permisos de procesamiento de transacciones (consulta Configuración). Helcim procesa CAD y USD. Una cuenta de prueba (desarrollador) de Helcim es opcional para realizar pruebas.
Clave de licencia de VibeFox: comprada en vibefox.net. Una clave funciona en un dominio.
Instalación
1. En WordPress, ve a Plugins > Add New > Upload Plugin, selecciona el archivo ZIP del plugin y haz clic en Install Now. También puedes subir la carpeta wcp_helcim_gateway a /wp-content/plugins/ mediante FTP.
2. Haz clic en Activate.
3. En Helcim, abre All Tools > Integrations > API Access Configuration, crea un acceso de API con permisos de procesamiento de transacciones (compras, preautorizaciones, capturas, reembolsos) y copia su token.
4. Abre los ajustes: WooCommerce > Settings > Payments > Helcim > Manage, o haz clic en Settings debajo del nombre del plugin en la página de Plugins.
5. Introduce tu clave de licencia de VibeFox en el bloque de licencia situado en la parte superior de la página y haz clic en Activate.
6. Pega el token en Live API token, y el token de tu cuenta de prueba de Helcim en Test API token si tienes una.
7. Elige el Transaction type y las Account currencies, activa Enable / Disable y guarda los cambios. Para probar primero, activa Test mode y paga con tu cuenta de prueba; luego desactívalo.
Configuración
Todos los ajustes están en una sola página: WooCommerce > Settings > Payments > Helcim. Encima de los campos, la página te advierte cuando la moneda de la tienda no es una de las Account currencies y, mientras la pasarela esté activada, cuando el token de API del modo actual esté vacío. En ambos casos, la pasarela se oculta en la finalización de compra. En la lista de métodos de pago, la pasarela se marca como pendiente de configuración hasta que el modo actual tenga un token.
Enable / Disable: Enable Helcim Gateway activa o desactiva el método de pago. Por defecto: desactivado.
Title: el título del método de pago mostrado en la finalización de compra. Por defecto: Credit card (Helcim).
Description: la descripción del método de pago mostrada en la finalización de compra. Por defecto: 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. Otórgale permisos de procesamiento de transacciones para compras, preautorizaciones, capturas y reembolsos. Las cuentas de prueba de Helcim utilizan la misma dirección de API que las cuentas de producción, por lo que el modo de prueba simplemente utiliza el token de tu cuenta de prueba de Helcim.
Live API token: el token de API de tu cuenta de producción de Helcim. Se utiliza cuando el modo de prueba está desactivado.
Test mode: Use the Test API token (Helcim test account). Los pagos, capturas y reembolsos van a tu cuenta de prueba de Helcim, y los clientes ven un aviso de modo de prueba. Los reembolsos y capturas de un pedido siempre utilizan el token del modo en el que se pagó el pedido. Por defecto: desactivado.
Test API token: el token de API de tu cuenta de prueba (desarrollador) de Helcim. Se utiliza cuando el modo de prueba está activado.
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 pedido. La pasarela se oculta en la finalización de compra para otras monedas.
Avanzado
Debug log: Log API requests and responses en WooCommerce > Status > Logs, origen wcp_helcim_gateway. 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. Por defecto: desactivado.
Delete data on uninstall: Remove the gateway settings, its own options (wc_hlg_*) and its log files when the plugin is deleted. Por defecto: desactivado.
Finalizar compra
El cliente elige el método de pago (por defecto Credit card (Helcim)) e introduce Card Number, Expiry (MM/YY), CVC y Cardholder Name en tu finalización de compra. Junto al título se muestran los iconos de Visa, Mastercard, American Express y Discover. En el modo de prueba, el formulario muestra TEST MODE — payments go to a Helcim test account, no real charges are made. Antes del envío, el plugin comprueba la suma de comprobación del número de tarjeta, que la fecha de caducidad sea válida y no haya vencido, que el CVC tenga 3 o 4 dígitos y que el nombre esté completo.
Cuando se realiza el pedido, tu servidor envía la tarjeta a Helcim como una compra o una preautorización por el total del pedido en la moneda del pedido. 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 se muestra en Helcim con un número de factura compuesto por el número de pedido y un código corto. Helcim responde en la misma solicitud. El pedido se marca como pagado solo después de que Helcim aprueba la transacción y el importe y la moneda aprobados coinciden con el pedido. Luego, el cliente llega a la página de pedido recibido.
Solo se ejecuta un intento de pago por pedido a la vez, y un pedido que ya está pagado nunca se vuelve a cobrar. Cada intento utiliza una clave de idempotencia. Si Helcim no responde, el pedido permanece en Pendiente de pago y un reintento en un plazo de 5 minutos devuelve el resultado original de Helcim en lugar de cobrar la tarjeta dos veces.
Mensajes que el cliente puede ver: 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 el token de API falta o es rechazado; Your payment is already being processed. Please wait a moment and check your e-mail before trying again. cuando el formulario se envía dos veces. Los detalles técnicos van a las notas del pedido y al registro.
El método de pago funciona en la finalización de compra clásica, en el bloque de Finalizar compra (con los mismos campos de tarjeta) y en la página Pay for order. Es compatible con el almacenamiento de pedidos de alto rendimiento de WooCommerce (HPOS).
El plugin no utiliza HelcimPay.js ni Helcim.js, por lo que los datos de la tarjeta pasan por tu servidor. No tiene tarjetas guardadas, suscripciones, pagos bancarios o ACH, Apple Pay, Google Pay ni 3-D Secure, y no tiene webhooks de Helcim.
Pedidos y reembolsos
Estados del pedido
Pending payment: el pago fue rechazado o aún no se ha confirmado. Si Helcim no respondió, la nota del pedido te pide que verifiques la factura de Helcim antes de volver a cobrar al cliente.
Processing: se aprobó una compra o se capturó una preautorización. Los pedidos que solo contienen productos virtuales descargables pasan a Completado, el valor por defecto de WooCommerce. La nota del pedido muestra el ID de la transacción, el código de aprobación, el tipo de tarjeta, los últimos 4 dígitos y el modo. El ID de la transacción es el ID de la transacción de Helcim.
On hold (pre-authorization): los fondos solo están retenidos. Captúralos con la acción del pedido o libéralos con un reembolso total.
On hold after payment: Helcim aprobó una transacción, pero el importe, la moneda o el ID de transacción en su respuesta no coinciden con el pedido. La nota dice Helcim response verification FAILED. Comprueba la transacción en Helcim antes de procesar el pedido.
Captura
Abre el pedido (estado En espera), elige la acción del pedido Capture Helcim pre-authorization y haz clic en Update. Se captura el total actual del pedido, menos los reembolsos. Puede ser inferior al importe autorizado, pero no superior. La captura utiliza el token del modo en el que se pagó el pedido. Tras una captura correcta, el pedido pasa a Procesando y el ID de la transacción cambia a la transacción de captura. Si la captura falla, se muestra el motivo y se añade a las notas del pedido.
Reembolsos
Abre el pedido, haz clic en Refund, introduce el importe y haz clic en Refund via Credit card (Helcim) (el botón muestra tu Title). Se admiten reembolsos totales y parciales de una compra o de una preautorización capturada. Una preautorización no capturada solo se puede reembolsar en su totalidad: se libera la retención y no se cobra al cliente. El reembolso se envía en el modo en el que se pagó el pedido, por lo que el token de ese modo debe estar configurado. Solo cuenta cuando Helcim lo aprueba. Si Helcim lo rechaza, WooCommerce muestra el error y no se registra ningún reembolso. Un reembolso correcto se añade a las notas del pedido con el ID de transacción de reembolso de Helcim. Un reintento tras agotarse el tiempo de espera no reembolsa dos veces.
El plugin no recibe webhooks de Helcim. Las capturas, reembolsos y anulaciones realizados en el panel de Helcim no se reflejan en WooCommerce, por lo que debes realizarlos desde WooCommerce.
Clave de licencia
El plugin funciona con una clave de licencia de VibeFox de vibefox.net. El bloque de licencia está en la parte superior de WooCommerce > Settings > Payments > Helcim. Pega la clave en License key y haz clic en Activate. El bloque muestra el estado, por ejemplo, la fecha hasta la que la licencia está activa y tu dominio. Usa Check now para volver a comprobar el estado, Change key para introducir otra clave y Remove key para eliminarla de este sitio. El enlace Manage licenses and domains in your account abre tu cuenta de vibefox.net.
Una clave funciona en un dominio. Eliminar la clave de un sitio no libera su espacio de dominio. Libera el espacio en tu cuenta de vibefox.net.
Sin una clave activa, Helcim no se muestra a los clientes en la finalización de compra. Si se inicia un pago de todos modos, el cliente ve This payment method is not available. Please choose another one. Los gestores de la tienda que hayan iniciado sesión siguen viendo el método de pago, marcado como (unlicensed — visible to admins only), para que puedas configurar y probar el plugin antes de comprar una clave. Aparece un recordatorio en la página de Plugins y en las páginas de WooCommerce. Los pedidos existentes no se ven afectados: las capturas y los reembolsos siguen funcionando.
Cuando caduca una licencia, el plugin sigue funcionando, pero las actualizaciones y el soporte requieren una renovación. El estado se vuelve a comprobar automáticamente en segundo plano.
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 el modo de prueba) y que la moneda del carrito sea una de las Account currencies. En la página Pay for order, cuenta la moneda del pedido. La página de ajustes muestra una advertencia en ambos casos.
Helcim no respondió y el pedido permanece en Pendiente de pago: es posible que la tarjeta haya sido cobrada. Lee la nota del pedido y comprueba la factura en Helcim antes de volver a cobrar al cliente. Un reintento en un plazo 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 fue rechazado por Helcim. La nota del pedido indica que verifiques el token y sus permisos. Asegúrate de que el acceso de API tenga derechos de procesamiento de transacciones.
El pago falló con un motivo de Helcim: Helcim rechazó la solicitud, por ejemplo debido a la tarjeta o a los datos de facturación. La nota del pedido contiene los detalles.
El pedido está En espera tras el pago: lee la nota del pedido. El pedido fue preautorizado y espera la captura, o la respuesta de Helcim no coincidió con el pedido (falló la verificación de la respuesta).
No es posible realizar la captura: el importe a capturar debe ser mayor que 0 y no superior al importe autorizado, y el token del modo en el que se pagó el pedido debe estar configurado.
El reembolso falla: lee el mensaje. Una preautorización no capturada solo se puede reembolsar en su totalidad. Un mensaje sobre el modo significa que el token del modo en 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 en el que se pagaron, por lo que cambiar el modo más tarde no traslada sus capturas y reembolsos a la otra cuenta.
El bloque de licencia muestra un error: sigue el mensaje del bloque. Por ejemplo, si la clave ya se utiliza en otro dominio, libera un espacio en tu cuenta de vibefox.net y haz clic en Check now. Si la dirección del sitio cambió, haz clic en Check now para activar la clave para el nuevo dominio. Si no se puede contactar con el servidor de licencias, el plugin sigue funcionando con el último estado conocido.
Para desarrolladores: el filtro wc_hlg_supported_currencies modifica la lista de monedas y wc_hlg_card_brands modifica los iconos de tarjeta en la finalización de compra.
Desinstalación
Al desactivar el plugin se conservan todos los datos. Para eliminarlo, desactívalo y elimínalo en la página Plugins. La clave de licencia y el estado de la licencia de este plugin siempre se eliminan. Los ajustes de la pasarela, las opciones propias del plugin y los registros se eliminan solo si Delete data on uninstall estaba activado. De lo contrario, se conservan para una posterior reinstalación. Los datos de los pedidos forman parte del historial de pedidos y nunca se eliminan. Los pedidos existentes conservan sus notas de pago y sus ID de transacción.
Helcim es una marca comercial de su respectivo propietario. Este plugin no está afiliado a Helcim ni cuenta con su respaldo.