VibeFox Helcim for OpenCart — Ayuda

Requisitos

OpenCart: 3.0.x (probado con 3.0.5.0) o 4.0.2 o posterior (probado con 4.1.0.3).

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. Nunca se almacenan ni se registran, pero pasan por tu servidor, así que tu tienda necesita un certificado SSL para la finalización de compra y tu alojamiento debe cumplir PCI DSS (SAQ D).

Moneda: Helcim procesa CAD y USD. El método de pago solo se muestra cuando la moneda de la finalización de compra es una de las Account currencies configuradas en la extensión.

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 Configuration). Una cuenta de prueba (developer) de Helcim es opcional para hacer pruebas.

Clave de licencia de VibeFox: se compra en vibefox.net. Una clave funciona en un solo dominio.

Instalación

El archivo de descarga es un único archivo zip con los paquetes para ambas versiones de OpenCart. Descomprímelo en tu ordenador. Contiene README.txt, el paquete de OpenCart 3 wcp_helcim_gateway-oc3-(version).ocmod.zip y el paquete de OpenCart 4 wcp_helcim_gateway.ocmod.zip. Instala solo el paquete de tu versión de OpenCart. La clave de licencia es la misma para ambas versiones.

OpenCart 3

1. En la administración, ve a Extensions > Installer, haz clic en Upload y elige el archivo wcp_helcim_gateway-oc3-(version).ocmod.zip. La extensión no tiene modificaciones OCMOD, así que no hace falta actualizar Extensions > Modifications. En lugar del instalador, puedes copiar el contenido de la carpeta upload de este paquete en la carpeta raíz de tu tienda.

2. Ve a Extensions > Extensions y elige el tipo Payments. Busca VibeFox Helcim Gateway y haz clic en Install (el botón verde +). Tu usuario de administración necesita el derecho para modificar la lista de extensiones de pago.

3. Haz clic en Edit (el botón del lápiz) para abrir la página de ajustes. Pega tu clave de licencia de VibeFox en License key, en el bloque de licencia de la parte superior de la página, y haz clic en Activate (véase License key).

4. En Helcim, abre All Tools > Integrations > API Access Configuration, crea un acceso a la API con derechos de procesamiento de transacciones (compras, preautorizaciones, capturas y 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.

OpenCart 4

1. En la administración, ve a Extensions > Installer, haz clic en Upload y elige el archivo wcp_helcim_gateway.ocmod.zip. No cambies el nombre del archivo: OpenCart 4 toma el código de la extensión del nombre del archivo, y un paquete renombrado no funciona.

2. El paquete aparece en la lista de extensiones instaladas en la misma página. Haz clic en Install (el botón verde +) junto a él.

3. Ve a Extensions > Extensions y elige el tipo Payments. Busca VibeFox Helcim Gateway, haz clic en Install (el botón verde +) y luego en Edit (el botón del lápiz).

4. Introduce la clave de licencia, los tokens de API y los ajustes de pago como en los pasos 3 a 6 para OpenCart 3. La página de ajustes y sus campos son iguales en ambas versiones.

Una instalación nueva empieza con el método de pago desactivado y el modo de prueba desactivado.

Configuración

Todos los ajustes están en la página de la extensión: Extensions > Extensions > Payments > VibeFox Helcim Gateway > Edit. Las secciones aparecen a la izquierda; el botón Save situado debajo de la lista guarda toda la página. Encima de los ajustes, la página te avisa si la moneda predeterminada de tu tienda no está entre las Account currencies (en ese caso, Helcim solo se ofrece para pedidos en una moneda permitida) y, mientras el método de pago esté activado, si el token de API del modo actual está vacío (el método de pago entonces se oculta en la finalización de compra). Sin el derecho para modificar la extensión, la página muestra los ajustes pero no puede guardarlos.

Al guardar, Title no puede estar vacío (máximo 128 caracteres), Sort Order debe ser un número entero, Total debe ser un número igual o mayor que 0, y cada estado de pedido debe existir. Si algo está mal, no se guarda nada y la página muestra los errores.

Helcim

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

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 que se guarda en el pedido. Predeterminado: Credit card (Helcim). Obligatorio.

Description: el texto que se muestra al cliente en el paso Confirm Order, encima del formulario de la tarjeta. Predeterminado: Pay securely with your credit card.

Sort Order: la posición del método de pago en la finalización de compra. Déjalo vacío o introduce un número entero.

Geo Zone: muestra el formulario de la tarjeta solo para direcciones de pago de la zona geográfica seleccionada. Predeterminado: All zones. Las zonas geográficas se configuran en System > Localisation > Geo Zones.

Total: el importe total del pedido, en la moneda predeterminada de la tienda, que debe alcanzar un pedido para que se ofrezca el método de pago. Déjalo vacío para ofrecerlo con cualquier importe.

Credenciales de API

En Helcim, ve a All Tools > Integrations > API Access Configuration, crea un acceso a la 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. La sección incluye un enlace a la documentación de la API 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 se envían 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 en el que se pagó el pedido. Predeterminado: desactivado.

Test API token: el token de API de tu cuenta de prueba (developer) 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. Para eliminar un token guardado, marca Clear the saved token on save debajo del campo y haz clic en Save.

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. El método de pago se oculta en la finalización de compra para otras monedas.

Pedidos

El pedido se crea en el paso Confirm Order sin estado (un pedido ausente) y recibe un estado solo después de que Helcim haya aprobado la tarjeta. Cada campo muestra tus estados de pedido de OpenCart.

Order Status After Payment: se cobró la tarjeta (compra, o captura de una preautorización). Predeterminado: En proceso.

Authorized Status: preautorización: los fondos solo están retenidos, todavía no cobrados. Captúralos con Capture payment en la pestaña del pedido. Predeterminado: Pendiente, porque OpenCart no tiene el estado On hold.

On Hold (Review) Status: la respuesta de Helcim no coincide con el pedido (aprobación parcial, otra moneda, sin ID de transacción, o el total del pedido difiere del cobro). Verifica la transacción en Helcim antes de procesar el pedido; una nota explica por qué. Predeterminado: Pendiente. Puedes crear tus propios estados en System > Localisation > Order Statuses para distinguir los pedidos autorizados de los pedidos en revisión.

Canceled Status: una preautorización sin capturar se liberó desde la pestaña del pedido (no se cobró al cliente). Predeterminado: Cancelado.

Refunded Status: se aplica cuando el pago se reembolsa por completo desde la pestaña del pedido. Predeterminado: Reembolsado.

Avanzado

Debug log: escribe las solicitudes y respuestas de la API en wc_hlg_debug.log.php, en la carpeta de registros de OpenCart (storage/logs). 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 fecha de 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: desactivado.

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 la extensión se eliminan los ajustes de la pasarela y sus archivos de registro. Las transacciones y reembolsos de Helcim siempre se conservan, así que los pedidos pagados antes se pueden capturar y reembolsar después de volver a instalar. Predeterminado: desactivado.

Importar / Exportar

Export: Download JSON guarda los ajustes en un archivo JSON. Los tokens de API no se exportan.

Import: pega un JSON exportado previamente y haz clic en Import para restaurar los ajustes. Los tokens de API guardados se conservan.

Finalización de compra

En el paso Payment Method, el cliente elige el método de pago (predeterminado Credit card (Helcim)). En el paso Confirm Order, el cliente ve un icono de tarjeta, tu descripción y el formulario con Card Number, Expiry (MM/YY), CVC y Cardholder Name. En modo de prueba, el formulario muestra TEST MODE — payments go to a Helcim test account, no real charges are made. OpenCart crea el pedido en este paso, todavía sin estado. Cuando el cliente hace clic en Confirm Order, la extensión comprueba la suma de control del número de tarjeta, que la fecha de caducidad es válida y no está vencida, que el CVC tiene 3 o 4 dígitos y que el nombre está rellenado. Los errores se muestran encima del formulario y no se envía nada a Helcim.

En OpenCart 4, el cliente elige el método de pago con el botón Choose del bloque del método de pago, en la ventana Payment method options. El formulario de la tarjeta aparece entonces en el bloque de confirmación del pedido, al final de la página de finalización de compra, encima del botón Confirm Order. De forma predeterminada, OpenCart 4 no pide una dirección de pago; en ese caso, la extensión envía a Helcim la dirección de envío para la verificación de la dirección, junto con el nombre del titular.

Después, tu servidor envía la tarjeta a Helcim como compra o preautorización por el importe del pedido en la moneda del pedido. El nombre del titular, la dirección de pago, 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 pedido, -OC y un código corto. Helcim responde en la misma solicitud. El pedido recibe su estado solo después de que Helcim apruebe la transacción, de la forma habitual de OpenCart, con los correos de pedido habituales y la actualización del stock. El carrito se vacía de inmediato y el cliente llega a la página de pedido completado de OpenCart.

Solo se ejecuta un intento de pago por carrito a la vez, y un carrito que ya está pagado nunca se vuelve a cobrar, aunque OpenCart haya creado mientras tanto un nuevo pedido para él (OpenCart 3 crea un pedido nuevo cada vez que se muestra el paso Confirm Order; en OpenCart 4, un pedido anterior o una segunda pestaña del navegador todavía pueden tener el mismo carrito). OpenCart 4 mantiene un único pedido para la compra y lo actualiza, así que tras una tarjeta rechazada el cliente paga el mismo pedido. Si ese pedido se cerró entretanto (por ejemplo, lo cancelaste), o ya está pagado y el carrito contiene ahora una compra nueva, Confirm Order devuelve al cliente a la página de finalización de compra con Your previous order is already closed (cancelled or refunded by the store) or paid for another cart. Please confirm the order again: the cart will be paid with a new order. encima, y el siguiente Confirm Order paga un pedido nuevo del carrito. Un cambio en el carrito, incluida una cantidad nueva, cuenta como un carrito nuevo que necesita su propio pago. Cada intento usa una clave de idempotencia. Si Helcim no responde, el pedido queda sin estado, y un reintento en menos de 5 minutos devuelve el resultado original de Helcim en lugar de cobrar la tarjeta dos veces. Si el pago fue aprobado pero no se pudo establecer el estado del pedido, el siguiente intento del mismo carrito lo establece sin volver a cobrar la tarjeta.

Mensajes que el cliente puede ver encima del formulario: 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 es rechazado; Your payment is already being processed. Please wait a moment and check your e-mail before trying again. en 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 establecer el estado del pedido. El cliente permanece en el paso Confirm Order con el mismo carrito. Los detalles técnicos se escriben en el registro.

La extensión 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 de pedido

Sin estado (pedido ausente): la tarjeta fue rechazada, Helcim no respondió o el cliente aún no ha pagado. Los rechazos y errores se escriben en el registro y se añaden como notas. En Sales > Orders, estos pedidos solo se muestran con el filtro Order Status en Missing Orders.

Order Status After Payment (predeterminado Processing): se aprobó una compra o se capturó una preautorización. Una nota 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.

Authorized Status (predeterminado Pending): se aprobó una preautorización. Los fondos solo están retenidos. Captúralos o libéralos con un reembolso completo.

On Hold (Review) Status (predeterminado Pending): Helcim aprobó una transacción, pero el importe, la moneda o el ID de transacción de su respuesta no coinciden con el pedido, por ejemplo tras una aprobación parcial o si el total del pedido cambió durante el pago. La nota dice Helcim response verification FAILED. Verifica la transacción en Helcim antes de procesar el pedido.

Refunded Status (predeterminado Refunded): el pago se reembolsó por completo a través de la extensión.

Canceled Status (predeterminado Canceled): una preautorización sin capturar fue liberada. No se cobró al cliente.

Las notas son entradas del History del pedido que el cliente no ve.

Pestaña VibeFox Helcim Gateway

En Sales > Orders, abre un pedido pagado con Helcim. En la parte inferior de la página del pedido, junto a History y Additional, la pestaña VibeFox Helcim Gateway muestra el Transaction ID (y el ID de la preautorización tras una captura) con una etiqueta Test mode para los pagos de prueba, el Transaction type y el estado de la captura, la Invoice, la Card y el código de aprobación, los importes Approved / order / refunded, el botón de captura y el formulario de reembolso, el historial de reembolsos y las Helcim notes del pedido. La pestaña se muestra a los usuarios que tienen acceso a la extensión; las capturas y los reembolsos requieren el derecho para modificarla (se configura en System > Users > User Groups).

Captura

En el caso de una preautorización sin capturar, haz clic en Capture payment en la pestaña (el botón muestra el importe) 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 autorizado, pero nunca mayor. La captura usa el token del modo en el que se pagó el pedido. Tras una captura correcta, el pedido recibe Order Status After Payment. Si la captura falla, la pestaña muestra el motivo y lo añade a las notas.

Reembolsos

En la pestaña, introduce el Amount (se rellena el importe que aún no se ha reembolsado), opcionalmente un Reason (optional), 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 realmente cobró; por eso, tras una aprobación parcial no puedes reembolsar más de lo que pagó el cliente. En una preautorización sin capturar, el botón es Release pre-authorization: solo se puede liberar el importe completo, la retención se elimina y el pedido recibe Canceled Status.

El reembolso se envía en el modo en el que se pagó el pedido, así que el token de ese modo debe estar configurado. Solo cuenta cuando Helcim lo aprueba. Si Helcim lo rechaza, la pestaña 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 ID de la transacción de reembolso de Helcim. Un reembolso completo asigna al pedido el estado Refunded Status sin notificar al cliente y sin devolver productos al stock, como un cambio de estado manual. Un reembolso parcial no cambia el estado. Un reintento tras un tiempo de espera no reembolsa dos veces.

Las devoluciones de productos en Sales > Returns no devuelven dinero a través de Helcim. La extensión no recibe webhooks de Helcim: las capturas, reembolsos y anulaciones hechos en el panel de Helcim no se reflejan en OpenCart, así que hazlos desde la página del pedido.

Clave de licencia

La extensión funciona con una clave de licencia de VibeFox obtenida en vibefox.net. El bloque de licencia License — VibeFox Helcim Gateway es el primer bloque de Extensions > Extensions > Payments > VibeFox Helcim Gateway > Edit, 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: opencart-payment-helcim y el enlace Manage licenses and domains in your account, que abre tu cuenta de vibefox.net. Solo los usuarios administradores con el permiso Modify para la extensión pueden cambiar la clave. Los textos del bloque siguen el idioma de la administración (se incluyen inglés y 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. Tras 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 el servidor de licencias no está disponible, la extensión sigue funcionando con el último estado conocido.

Una clave funciona en un solo dominio: la dirección de la tienda de la configuración de OpenCart. 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 se inicia un pago de todos modos, el cliente ve This payment method is not available. Please choose another one. Un usuario administrador que haya iniciado sesión en la administración en el mismo navegador sigue viendo el método de pago en la tienda, marcado como (unlicensed — visible to admins only), para que puedas configurar y probar la extensión antes de comprar una clave. En OpenCart 4 esta vista previa no está disponible: la tienda no detecta el inicio de sesión del administrador, así que sin una clave activa el método de pago queda oculto para todos. Después de abrir la página Edit una vez, aparece un recordatorio en el Dashboard de la administración. Ciérralo con × para ocultarlo durante 7 días. Los pedidos existentes no se ven afectados: los pagos ya realizados se mantienen, y las capturas y reembolsos siguen funcionando.

Cuando una licencia caduca, la extensión sigue funcionando, pero las actualizaciones y el soporte requieren una renovación. El estado se vuelve a comprobar automáticamente cuando abres el Dashboard o la página Edit de la administración: 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 ningún cron job. Desinstalar la extensión siempre 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 tiene su token de API (Live API token, o Test API token en modo de prueba) y que la moneda de la finalización de compra está entre las Account currencies. La página de ajustes muestra un aviso cuando falta el token o cuando la moneda de la tienda no está permitida. Comprueba también que la dirección de pago está en la Geo Zone seleccionada y que el pedido alcanza el Total definido en los ajustes.

El cliente vio We could not confirm your payment: Helcim no respondió, así que la tarjeta podría haberse cobrado. La nota del pedido y el registro indican la factura de Helcim. Comprueba esa factura en Helcim antes de volver a cobrar al cliente. Un reintento en menos de 5 minutos devuelve el resultado original y no cobra dos veces.

Los clientes ven This payment method is temporarily unavailable: Helcim rechazó el token de API. La nota del pedido indica que hay que revisar el token y sus permisos. Asegúrate de que el acceso a la API tiene derechos de procesamiento de transacciones.

Los clientes ven This payment method is not available. Please reload the checkout page.: la sesión de la finalización de compra ya no coincide con el pedido, el método de pago se desactivó entretanto, o el token o la moneda ya no son válidos. El cliente recarga la finalización de compra.

El pago falló con un motivo de Helcim: Helcim rechazó la solicitud, por ejemplo por la tarjeta o los datos de facturación. La nota del pedido y el registro contienen los detalles.

El cliente vio Your payment was received, but the order could not be completed: Helcim aprobó el pago, pero OpenCart no pudo establecer el estado del pedido. El registro indica el motivo. Cuando el cliente envía de nuevo el mismo carrito, el estado se establece a partir del pago aprobado sin un segundo cobro.

El pedido está en estado de revisión: lee las notas de la pestaña VibeFox Helcim Gateway. La respuesta de Helcim no coincidió con el pedido (falló la verificación de la respuesta). Comprueba la transacción en Helcim y después procesa el pedido o reembolsa el pago.

La captura no es posible: 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 sin capturar solo se puede liberar por completo. 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. You do not have permission to capture or refund (modify this extension). significa que tu grupo de usuarios no tiene derecho para modificar la extensión.

Pagos de prueba: el modo de prueba envía los pagos, capturas y reembolsos a tu cuenta de prueba de Helcim. Los pedidos conservan el modo en 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 Extensions > Extensions, elige el tipo Payments y haz clic en Uninstall (el botón rojo −) junto a VibeFox Helcim Gateway. La clave de licencia y el estado de la licencia de esta extensión siempre se eliminan. OpenCart siempre elimina los ajustes propios de la extensión: Enable / Disable, Sort Order, Geo Zone, Total y los estados de pedido de la sección Orders, que vuelven a sus valores predeterminados al reinstalar. En OpenCart 4, también se elimina el evento de OpenCart de la extensión, que muestra el mensaje encima de la página de finalización de compra. Si Delete data on uninstall está activado, se eliminan los demás ajustes de la pasarela (título, descripción, tokens de API, modo de prueba, tipo de transacción, monedas de la cuenta, interruptor del registro de depuración) y el registro. Si está desactivado, se conservan para una reinstalación posterior. Las transacciones y reembolsos de Helcim siempre se conservan, así que los pedidos pagados antes se pueden capturar y reembolsar después de reinstalar. Los pedidos existentes conservan sus notas de pago.

En OpenCart 4, para eliminar también los archivos de la extensión, ve a Extensions > Installer tras la desinstalación y haz clic en Uninstall (el botón naranja −) junto a VibeFox Helcim Gateway en la lista de extensiones instaladas, y después en Delete (el botón rojo de papelera) para eliminar el paquete subido.

Helcim es una marca comercial de su respectivo titular. Esta extensión no está afiliada a Helcim ni cuenta con su aprobación.