VibeFox Transbank for OpenCart — Ayuda

Requisitos

OpenCart: 3.0.x (probado con la versión 3.0.5.0) o 4.0.2 y posteriores (probado con la versión 4.1.0.3).

PHP: 8.0 o posterior.

Moneda: peso chileno (CLP). Añádela en System > Localisation > Currencies si tu tienda no la tiene, con 0 decimales: Webpay Plus cobra solo pesos enteros. Para pedidos en otra moneda no se muestra el método de pago.

Cuenta de Transbank: para los pagos reales necesitas un comercio estándar de Webpay Plus (captura inmediata) con su Commerce Code de producción y su API Key Secret. Transbank te entrega el Commerce Code cuando se aprueba tu afiliación, y el API Key Secret después del proceso de validación de la integración (consulta la documentación para desarrolladores de Transbank). Para las pruebas no se necesitan credenciales. No se admiten los códigos de comercio de Webpay Plus Mall, Oneclick ni de captura diferida.

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

Instalación

La descarga es un único archivo zip con los paquetes de ambas versiones de OpenCart. Descomprímelo en tu ordenador. Contiene README.txt, el paquete de OpenCart 3 wcp_transbank_gateway-oc3-(version).ocmod.zip y el paquete de OpenCart 4 wcp_transbank_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 el panel de administración ve a Extensions > Installer, haz clic en Upload y elige el archivo wcp_transbank_gateway-oc3-(version).ocmod.zip. La extensión no tiene modificaciones OCMOD, por lo que Extensions > Modifications no necesita actualizarse. En lugar del instalador, también 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 Transbank Gateway y haz clic en Install (el botón verde +). Tu usuario de administrador necesita el permiso 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 configuración. 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 (consulta Clave de licencia).

4. Activa Enable / Disable y haz clic en Save. Prueba un pago en CLP con Integration (test) mode activado, usando las tarjetas de prueba de la documentación para desarrolladores de Transbank.

5. Para pasar a producción, introduce tu Production Commerce Code y tu Production API Key Secret, desactiva Integration (test) mode y haz clic en Save.

OpenCart 4

1. En el panel de administración ve a Extensions > Installer, haz clic en Upload y elige el archivo wcp_transbank_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 Transbank Gateway, haz clic en Install (el botón verde +) y después en Edit (el botón del lápiz).

4. Introduce la clave de licencia y los ajustes como en los pasos 3 a 5 de OpenCart 3. La página de ajustes y sus campos son iguales en ambas versiones. Solo la URL de retorno es distinta (ver URL de retorno).

No es necesario configurar ninguna URL de retorno ni webhook en Transbank. La extensión envía su URL de retorno con cada transacción. Una instalación nueva empieza con el método de pago desactivado y con el modo de integración activado.

Configuración

Todos los ajustes están en la página de la extensión: Extensions > Extensions > Payments > VibeFox Transbank Gateway > Edit. Las secciones aparecen a la izquierda; el botón Save situado debajo de la lista guarda la página completa. Encima de los ajustes, la página te avisa cuando está seleccionada la producción y falta el Commerce Code o la API Key de producción, o no son válidos (en ese caso Webpay se oculta en la finalización de compra), cuando la moneda predeterminada de la tienda no es CLP (el método de pago se oculta para otras monedas) y cuando CLP tiene decimales (los totales se redondean a pesos enteros). Mientras el modo de integración está activado, la página indica que los pagos van al entorno de integración de Transbank con el código de comercio de prueba público y que no se cobra dinero real. Sin el permiso para modificar la extensión, la página muestra los ajustes pero no permite guardarlos.

Al guardar, Title no puede estar vacío ni tener más de 128 caracteres, Sort Order debe ser un número entero (se permiten valores negativos), Total debe ser un número igual o mayor que 0 y los estados de pedido deben existir; de lo contrario, no se guarda nada y la página muestra el error.

Transbank Webpay Plus

Enable / Disable: Enable Transbank Webpay Plus payments activa o desactiva el método de pago. Predeterminado: off.

Title: el nombre del método de pago que ve el cliente en la finalización de compra. También es el nombre del método de pago guardado en el pedido. Predeterminado: Webpay Plus. Obligatorio, máximo 128 caracteres.

Description: el texto que ve el cliente en el paso Confirm Order, encima del botón de confirmar. Predeterminado: Pay with credit, debit or prepaid card via Webpay.

Sort Order: la posición de Webpay entre los métodos de pago de la finalización de compra. Déjalo vacío o introduce un número entero (se permiten valores negativos).

Geo Zone: ofrece Webpay solo a las 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 total de la finalización de compra, en la moneda predeterminada de la tienda, que debe alcanzar un pedido para que se ofrezca Webpay. Déjalo vacío para ofrecer Webpay con cualquier total.

Entorno y credenciales

El texto de la sección enlaza con la documentación para desarrolladores de Transbank y explica cuándo Transbank te entrega las credenciales de producción.

Integration (test) mode: los pagos van al entorno de integración de Transbank con su código de comercio de prueba público (597055555532), que se usa automáticamente. No se usan las credenciales de producción de abajo y no se cobra dinero real. Predeterminado: on. Desactívalo para pasar a producción. Mientras esté activado, los clientes ven TEST MODE — entorno de integración. Sin cargos reales. en el paso Confirm Order.

Production Commerce Code: tu código de comercio de producción (Tbk-Api-Key-Id): 12 dígitos, que empiezan por 5970. Si el tuyo tiene 8 dígitos, introdúcelo tal cual; el prefijo 5970 se añade al guardar. Se eliminan los espacios y otros caracteres. Los códigos de comercio de prueba públicos de Transbank no funcionan en producción: con cualquiera de ellos, Webpay sigue oculto en la finalización de compra.

Production API Key Secret: el Tbk-Api-Key-Secret de tu comercio de producción. Mantenlo en secreto. Se eliminan los espacios al guardar. Una clave guardada no vuelve a mostrarse: el campo queda vacío y muestra Saved — leave empty to keep it. Escribe un valor nuevo solo si quieres cambiarla. Para eliminar la clave guardada, marca Clear saved API key y haz clic en Save.

Integration (test) mode decide adónde van los nuevos pagos. Cada pago recuerda su entorno: la confirmación y los reembolsos de un pago siempre van al entorno (integración o producción) y con las credenciales con las que se creó, aunque cambies el modo después.

URL de retorno

Return from Webpay: la dirección a la que Transbank devuelve al cliente, que se muestra como referencia. En OpenCart 3 tiene este aspecto: https://your-store/index.php?route=extension/payment/wcp_transbank_gateway/back, y en OpenCart 4: https://your-store/index.php?route=extension/wcp_transbank_gateway/payment/wcp_transbank_gateway.back. No hay que configurar nada en Transbank: la extensión envía esta URL con cada transacción (Transbank no tiene webhook: el pago se confirma cuando el cliente regresa). Debe ser accesible desde internet; el modo de mantenimiento no la bloquea (en OpenCart 4 la extensión añade una acción de inicio para ello).

Pedidos

OpenCart crea el pedido en el paso Confirm Order sin estado (un pedido «missing order»). El pedido recibe un estado solo después de que la tienda confirme la transacción con Transbank (commit) cuando el cliente regresa desde Webpay. Cada campo siguiente muestra los estados de pedido de tu OpenCart.

Order Status After Payment: el estado que se asigna tras un pago de Webpay aprobado y verificado. Predeterminado: Processing.

Transbank Payment On Hold Status: Transbank autorizó un pago que no coincide con el pedido (importe, buy order, session id): el pedido queda retenido para revisión manual y una nota explica el motivo. Predeterminado: Pending, porque OpenCart no tiene el estado On hold. Puedes crear tu propio estado en System > Localisation > Order Statuses y seleccionarlo aquí.

Refunded Status: se asigna cuando el pago se reembolsa por completo desde la página del pedido. Predeterminado: Refunded.

Avanzado

Debug log: registra las solicitudes a la API y las respuestas en wc_tbk_debug.log.php, en la carpeta de logs de OpenCart (storage/logs). El archivo no se puede abrir desde la web. Los errores siempre se registran, aunque esta opción esté desactivada. No se registran datos de tarjetas, claves API ni tokens completos. 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 la extensión se eliminan los ajustes de la pasarela y el registro. Los datos de pedidos y pagos siempre se conservan. Predeterminado: off.

Importar / Exportar

Export: Download JSON guarda los ajustes en un archivo JSON. La API Key Secret no se exporta.

Import: pega el JSON exportado anteriormente y haz clic en Import para restaurar los ajustes. La clave API guardada se conserva.

Finalización de compra

En el paso Payment Method el cliente elige el método de pago (por defecto Webpay Plus). En el paso Confirm Order el cliente ve tu descripción y la nota You will be redirected to Webpay (Transbank) to complete the payment. OpenCart crea el pedido en este paso, todavía sin estado. Cuando el cliente hace clic en Confirm Order, la extensión crea una transacción de Transbank por el total del pedido en pesos enteros (un total con decimales se redondea al peso más cercano) y el cliente pasa directamente al formulario de Webpay, donde paga con tarjeta de crédito, débito o prepago. 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, y hace clic en Confirm Order al final de la página de finalización de compra.

Cuando el cliente regresa, la extensión confirma (commit) la transacción con Transbank de servidor a servidor. El pedido se marca como pagado solo después de que Transbank lo confirme: la respuesta debe ser aprobada, y el importe, el buy order y la sesión deben coincidir con lo que la tienda envió para este intento. Después, el pedido recibe su estado de la forma estándar de OpenCart, con los correos electrónicos habituales del pedido y la actualización de existencias, y el cliente ve la página de éxito del pedido de OpenCart con Your Webpay payment has been received. En el caso de un pedido en revisión, la página muestra Your Webpay payment was received and is being reviewed by the store.

Si falla la llamada de confirmación, por ejemplo por un tiempo de espera (timeout), la extensión pregunta a Transbank el estado de la transacción. Si aun así no se puede conocer el estado, el pedido queda sin estado y el cliente vuelve a la finalización de compra con We could not confirm your Webpay payment with Transbank. Please try again in a moment; if your card was charged, contact us before paying again. Si otra solicitud está confirmando el mismo carrito en ese momento, o si Transbank aprobó el pago pero el estado del pedido todavía no se pudo asignar, el cliente ve una página Payment confirmation con Your Webpay payment is being confirmed. Please do not pay again — check again in a moment. y los botones Check again y Back to checkout. Entonces el estado se asigna a partir de la respuesta guardada, sin una segunda confirmación.

Si el cliente cancela en Webpay, o el formulario de Webpay caduca o informa de un error, no se cobra nada. El cliente vuelve a la finalización de compra con un mensaje, por ejemplo You cancelled the Webpay payment. Nothing was charged — you can try again or choose another payment method. Una tarjeta rechazada muestra Your Webpay payment was rejected and nothing was charged. Please try again or choose another payment method. El carrito se conserva y cada nuevo intento es una nueva transacción de Webpay. En OpenCart 4 estos mensajes se muestran encima de la página de finalización de compra.

OpenCart 3 crea un pedido nuevo cada vez que se muestra el paso Confirm Order. OpenCart 4 conserva un único pedido para la finalización de compra y lo actualiza, así que después de un pago cancelado o rechazado el cliente paga el mismo pedido con una nueva transacción de Webpay. Si el pedido cambió después de iniciar el pago (su moneda o su total ya no coinciden con la transacción), la transacción no se confirma, por lo que Transbank no la cobra, y el cliente ve Your order changed after the Webpay payment was started. The payment was not confirmed, so it was not charged — please pay again. Si el pedido ya tiene un estado, o si otro pedido del mismo carrito ya está pagado, un retorno tardío tampoco se confirma: el cliente pasa a la página de éxito del pedido pagado, o ve This order can no longer be paid (it was cancelled or already paid). Your Webpay payment was not confirmed, so it was not charged.

En OpenCart 4, si el pedido de la finalización de compra recibió un estado sin un pago de Webpay o la tienda lo cerró entretanto, el siguiente Confirm Order devuelve al cliente a la finalización de compra con el mismo mensaje, y el carrito se paga con un pedido nuevo. Si el pedido de la finalización de compra ya está pagado pero el carrito ha cambiado desde entonces, incluida una nueva cantidad, el cliente vuelve a la finalización de compra y el nuevo carrito se paga con un pedido nuevo.

Si Webpay no puede iniciar el pago, el cliente permanece en el paso Confirm Order con un mensaje breve, por ejemplo Could not connect to Webpay. Please try again in a moment. o Webpay could not start the payment. Please try again or choose another payment method. El motivo técnico se escribe en el registro.

Transbank no tiene webhook de pago: el resultado se procesa cuando el cliente vuelve desde Webpay. Si el cliente cierra el navegador en Webpay y nunca regresa, la transacción no se confirma y el pedido queda sin estado; según Transbank, las transacciones no confirmadas no se liquidan. La extensión no admite Webpay Plus Mall, tarjetas guardadas de Oneclick, suscripciones, captura diferida ni conversión de moneda.

Pedidos y reembolsos

Estados de pedido

Sin estado (missing order): el cliente fue enviado a Webpay y no ha pagado, ha cancelado, ha dejado caducar el formulario, la tarjeta fue rechazada o el pago todavía no se pudo confirmar. En Sales > Orders estos pedidos solo se muestran con el filtro Order Status en Missing Orders.

Order Status After Payment (predeterminadoProcessing): Transbank aprobó el pago. Una nota muestra el código de autorización, las últimas cuatro cifras de la tarjeta, el buy order, el importe, el tipo de pago y el número de cuotas.

Transbank Payment On Hold Status (predeterminadoPending): Transbank autorizó un pago que no coincide con el pedido (importe, buy order o sesión). La nota enumera las diferencias. Revisa el portal de Transbank y completa el pedido o reembolsa el pago.

Refunded Status (predeterminadoRefunded): el pago se reembolsó por completo mediante la extensión.

Si Webpay devuelve un pago de un pedido que ya tiene estado, o de un carrito que otro pedido ya ha pagado, el pago no se confirma y una nota te pide que revises el portal de Transbank si el cliente informa de un cargo. También se anotan las cancelaciones, los formularios caducados, los errores de formulario y las tarjetas rechazadas. Las notas son entradas del History del pedido que el cliente no ve.

Pestaña VibeFox Transbank Gateway

En Sales > Orders abre un pedido pagado con Webpay. En la parte inferior de la página del pedido, junto a History y Additional, la pestaña VibeFox Transbank Gateway muestra el Buy order y su entorno (una etiqueta Integration para los pagos de prueba), el Status del pago, el Authorization code, el Card / payment type con el número de cuotas, Charged / refunded, el formulario de reembolso, el historial de reembolsos, los Webpay attempts of the order y las Transbank notes. La pestaña se muestra a los usuarios que tienen acceso a la extensión.

Reembolsos

En la pestaña introduce el Amount en CLP (se rellena el importe que aún no se ha reembolsado), opcionalmente un Reason (optional), y haz clic en Refund via Transbank. Confirma la pregunta Refund this amount via Transbank? Se admiten reembolsos totales y parciales en pesos enteros. Necesitas el permiso para modificar la extensión (se configura en System > Users > User Groups). Un importe parcial con decimales se rechaza con Webpay refunds are in whole Chilean pesos. Please enter an amount without decimals. El último resto de un total con decimales se redondea igual que el cobro. Los reembolsos se hacen hasta el importe que Transbank cobró. El reembolso va al entorno en el que se hizo el pago, así que para un pago de producción deben estar configuradas las credenciales de producción.

Transbank responde con una reversión (REVERSED) o una anulación (NULLIFIED). Un reembolso correcto se añade al historial de reembolsos y a las notas con el importe, el tipo, el código de autorización y el saldo que queda en Transbank. Un reembolso total asigna el Refunded Status sin notificar al cliente y sin devolver productos al stock, igual que un cambio manual de estado. Un reembolso parcial no cambia el estado. Si Transbank no acepta el reembolso, la pestaña muestra el error y no se registra ningún reembolso.

Las devoluciones de productos en Sales > Returns no devuelven dinero a través de Transbank. Los reembolsos hechos en el portal de Transbank no se importan a OpenCart.

Clave de licencia

La extensión funciona con una clave de licencia de VibeFox de vibefox.net. El bloque de licencia License — VibeFox Transbank Gateway es el primer bloque de Extensions > Extensions > Payments > VibeFox Transbank 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 están la línea Product: opencart-payment-transbank 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 del panel de administración (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 el servidor de licencias no responde, la extensión sigue funcionando con el último estado conocido.

Una clave funciona en un 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. Libérala en tu cuenta de vibefox.net.

Sin una clave activa, Webpay Plus 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. Un usuario administrador que haya iniciado sesión en el panel de 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 ve el inicio de sesión del panel de administración, 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 del panel. Ciérralo con × para ocultarlo durante 7 días. Los pedidos existentes no se ven afectados: los pagos ya iniciados siguen confirmándose cuando el cliente regresa de Webpay, y los reembolsos desde la página del pedido funcionan.

Cuando una licencia caduca, la extensión sigue funcionando, pero las actualizaciones y el soporte requieren renovarla. El estado se vuelve a comprobar automáticamente al abrir el Dashboard o la página Edit del panel: una vez al día durante los primeros 14 días después de introducir la clave y, después, una vez por semana. No se necesita tarea cron. Desinstalar la extensión elimina siempre la clave de licencia y su estado.

Solución de problemas

Webpay Plus no aparece en la finalización de compra: comprueba que la licencia esté activa, que Enable / Disable esté activado, que el cliente pague en CLP y que, con el modo de integración desactivado, estén guardados un Production Commerce Code válido (12 dígitos, que empiezan por 5970) y una Production API Key Secret. Comprueba también que la dirección de pago esté en la Geo Zone seleccionada y que el pedido alcance el Total de la configuración. La página de ajustes muestra un aviso si faltan credenciales o si la moneda de la tienda no es CLP.

El pago se realizó, pero el pedido se queda sin estado: Transbank no tiene webhook, así que el pedido recibe su estado solo cuando el cliente regresa de Webpay. Si el cliente cerró el navegador en Webpay, la transacción no se confirmó y, según Transbank, no se liquida. Activa Debug log, revisa el campo Log y comprueba la transacción en el portal de Transbank.

El cliente ve We could not confirm your Webpay payment with Transbank: la llamada de confirmación falló y no se pudo comprobar el estado. El pedido no cambió y el motivo está en el registro. El cliente puede volver a intentarlo en un momento. Si el portal de Transbank muestra la transacción como autorizada, contacta con el cliente antes de que vuelva a pagar.

El cliente ve Your order changed after the Webpay payment was started: el total o la moneda del pedido no coincidían con la transacción. No se cobró nada; el cliente vuelve a pagar.

El cliente ve un error después de Confirm Order: activa Debug log y revisa el campo Log de la página de la extensión. Webpay payments are not available at the moment normalmente indica credenciales de producción incorrectas. Could not connect to Webpay significa que no se pudo contactar con Transbank. Transbank Webpay only supports payments in CLP (Chilean Peso) significa que el pedido está en otra moneda. This payment method is not available. Please reload the checkout page. significa que la sesión de finalización de compra ya no coincide con el pedido: el cliente debe recargar la página de finalización de compra.

Los totales y los reembolsos difieren en unos pocos pesos: la moneda CLP tiene decimales. Webpay cobra pesos enteros, así que los totales se redondean. Pon los decimales de CLP en 0 en System > Localisation > Currencies.

El pedido está en el estado de revisión después del pago: lee las notas de la pestaña VibeFox Transbank Gateway (consulta Estados de pedido) y, después, completa el pedido o reembolsa el pago.

El reembolso falla con The production Commerce Code / API Key are missing: el pago se hizo en producción y las credenciales de producción no están guardadas. Introdúcelas e inténtalo de nuevo.

El reembolso falla con Transbank refused the refund or Transbank did not approve the refund: Transbank no lo aceptó; el mensaje muestra el motivo o el tipo y el código de respuesta que devolvió. No se reembolsó nada. Revisa la transacción en el portal de Transbank.

El reembolso falla con Another request is processing this order: el pedido se estaba reembolsando o confirmando en ese mismo momento. Inténtalo de nuevo en un momento.

Desinstalación

Ve a Extensions > Extensions, elige el tipo Payments y haz clic en Uninstall (el botón rojo −) junto a VibeFox Transbank Gateway. La clave de licencia y el estado de licencia de esta extensión siempre se eliminan. OpenCart siempre elimina sus propios ajustes 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 en una reinstalación. También se elimina el evento de OpenCart de la extensión (en OpenCart 4, sus eventos y su acción de inicio, que deja pasar el retorno desde Webpay en modo de mantenimiento). Si Delete data on uninstall está activado, se eliminan los demás ajustes de la pasarela (título, descripción, modo de integración, credenciales, interruptor del registro de depuración) y el registro. Si está desactivado, se conservan para una reinstalación posterior. Las transacciones y los reembolsos de Webpay de los pedidos siempre se conservan, así que los pedidos pagados antes pueden reembolsarse tras una reinstalación. 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 después de desinstalarla, haz clic en Uninstall (el botón naranja −) junto a VibeFox Transbank Gateway en la lista de extensiones instaladas y después en Delete (el botón rojo de papelera) para eliminar el paquete subido.

Transbank y Webpay son marcas comerciales de sus respectivos titulares. Esta extensión no está afiliada a Transbank ni avalada por Transbank.