VibeFox Transbank 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.

Moneda: peso chileno (CLP). Webpay Plus cobra solo pesos enteros, así que pon la precisión de la moneda CLP en 0 en International > Localization > Currencies. Para carritos en otra moneda, el método de pago no se muestra.

Cuenta de Transbank: para 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 la 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. Los códigos de comercio de Webpay Plus Mall, Oneclick y de captura diferida no son compatibles.

Clave de licencia de VibeFox: se compra en vibefox.net. Una clave funciona en un solo 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 Transbank 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 (consulta Clave de licencia).

4. Activa Enable / Disable y haz clic en Save. Prueba un pago 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.

No hay que configurar en Transbank ninguna URL de retorno ni webhook. El módulo envía su URL de retorno con cada transacción.

Al instalarse, el módulo crea el estado de pedido Transbank payment on hold. PrestaShop activa el nuevo módulo de pago para todas las monedas, países y grupos de clientes. Puedes limitarlos en Payment > Preferences; la moneda CLP debe seguir permitida para el módulo.

Configuración

Todos los ajustes están en la página del módulo: Modules > Module Manager > VibeFox Transbank Gateway > Configure. Cada sección tiene su propio botón Save, que guarda la página completa. Encima de los campos, la página te avisa cuando se selecciona producción pero falta el Commerce Code o la API Key de producción, o no son válidos (en ese caso Webpay se oculta en la 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.

Transbank Webpay Plus

Enable / Disable: Enable Transbank Webpay Plus payments activa o desactiva el método de pago. Por defecto: desactivado.

Title: el nombre del método de pago que ven los clientes en la compra. También es el nombre del método de pago guardado en el pedido. Por defecto: Webpay Plus. Obligatorio: si guardas con el título vacío, aparece Enter a title for the payment method.

Description: el texto que se muestra debajo del método de pago en la compra. Por defecto: Pay with credit, debit or prepaid card via Webpay.

Environment and credentials

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 rellena automáticamente. No se usan las credenciales de producción de abajo y no se cobra dinero real. Por defecto: activado. Desactívalo para pasar a producción. Mientras esté activado, los clientes ven TEST MODE: entorno de integración. Sin cargos reales. encima de la descripción del método de pago.

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 módulo añade el prefijo 5970 al guardar. Los espacios y otros caracteres se eliminan. Los códigos de comercio de prueba públicos de Transbank no se aceptan en producción.

Production API Key Secret: el Tbk-Api-Key-Secret de tu comercio de producción. Guárdalo en secreto. Los espacios se eliminan al guardar. Una clave 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 saved API key: marca Production API Key Secret y haz clic en Save para eliminar la clave guardada. Un campo vacío mantiene el valor guardado.

URL de retorno

Return from Webpay: la dirección a la que Transbank devuelve al cliente, que se muestra solo como referencia. No hay que configurar nada en Transbank: el módulo envía esta URL con cada transacción. Debe ser accesible para los clientes; el modo de mantenimiento no la bloquea.

Avanzado

Debug log: registra las peticiones a la API y los retornos en logs/wc_tbk_debug.log.php, dentro de la carpeta del módulo. El archivo no se puede abrir desde la web. Los errores y avisos siempre se registran, aunque esta opción esté desactivada. No se registran datos de tarjeta, claves de API ni tokens completos. Por defecto: 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 el módulo se eliminan los ajustes de la pasarela y el registro. Los datos de los pedidos se conservan. Por defecto: desactivado.

Prueba y producción

Integration (test) mode decide adónde van los pagos nuevos. 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 más tarde.

Finalizar compra

En el paso de pago el cliente elige el método de pago (por defecto Webpay Plus, con el logotipo de Webpay) y confirma. El módulo crea una transacción de Transbank por el total del carrito en pesos enteros (un total con decimales se redondea al peso más cercano) y envía al cliente a una página breve Redirecting to Webpay. Please wait..., que lo reenvía al formulario de Webpay. Sin JavaScript, el cliente hace clic en Proceed to Webpay. En Webpay el cliente paga con tarjeta de crédito, débito o prepago. En este punto todavía no existe ningún pedido.

Cuando el cliente vuelve, el módulo 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, la orden de compra y la sesión deben coincidir con lo que la tienda envió para este intento. Entonces se crea el pedido y el cliente ve la página estándar de confirmación de pedido con Your Webpay payment has been received. Para un pedido en espera, la página muestra Your Webpay payment was received and is being reviewed by the shop.

Si la llamada de confirmación falla, por ejemplo por un tiempo de espera agotado, el módulo pide a Transbank el estado de la transacción. Si aun así no se puede saber, no se crea ningún pedido y el cliente ve 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 petición está confirmando el mismo carrito en ese momento, o Transbank aprobó el pago pero el pedido todavía no se pudo crear, 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 un botón Check again. Entonces el pedido se crea a partir de la respuesta guardada, sin una segunda confirmación.

Si el cliente cancela en Webpay, o el formulario de Webpay caduca o da un error, no se cobra nada. El cliente vuelve a la 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.

Si el carrito cambió después de iniciar el pago (por ejemplo, en otra pestaña, o porque un cupón del carrito dejó de ser válido y PrestaShop lo eliminó), la transacción no se confirma, así que Transbank no la cobra. El cliente ve Your cart changed after the Webpay payment was started. The payment was not confirmed, so it was not charged — please pay again. Si el carrito ya tiene un pedido (pagado con otro intento o con otro método de pago), un retorno tardío tampoco se confirma y el cliente 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. si ese pedido no está pagado.

Si Webpay no puede iniciar el pago, el cliente se queda en la compra con un mensaje breve, por ejemplo Could not connect to Webpay. Please try again in a moment. o Webpay payments are not available at the moment. Please choose another payment method. El motivo técnico se escribe en el registro.

El retorno desde Webpay funciona mientras la tienda está en modo de mantenimiento y no lo bloquea la restricción de países de tu tienda.

Transbank no tiene webhook de pago: el resultado se procesa cuando el cliente vuelve de Webpay. Si el cliente cierra el navegador en Webpay y nunca vuelve, la transacción no se confirma y no se crea ningún pedido; según Transbank, las transacciones no confirmadas no se liquidan. El módulo no incluye Webpay Plus Mall, tarjetas guardadas de Oneclick, suscripciones, captura diferida ni conversión de moneda.

Pedidos y reembolsos

Estados del pedido

No order yet: el cliente fue enviado a Webpay y no ha pagado, canceló, dejó caducar el formulario, la tarjeta fue rechazada o el pago todavía no se pudo confirmar. Solo existe el carrito.

Payment accepted: Transbank aprobó el pago. El pago se registra con el token de Webpay como ID de transacción, y una nota muestra el código de autorización, los últimos cuatro dígitos de la tarjeta, la orden de compra, el importe, el tipo de pago y el número de cuotas.

Transbank payment on hold: Transbank autorizó un pago que no coincide con el pedido (importe, orden de compra o sesión), o un cupón del carrito dejó de ser válido después de que Transbank aprobara el pago y PrestaShop lo eliminó. El pago se registra con el importe que Transbank cobró, y la nota enumera las diferencias. Revisa el portal de Transbank y completa el pedido o reembolsa el pago.

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

Si Webpay devuelve un pago de un carrito que ya tiene un pedido, el pago no se confirma y una nota en ese pedido te pide revisar el portal de Transbank si el cliente informa de un cargo. Los pedidos existentes no se ven afectados por los intentos posteriores.

Bloque Transbank Webpay Plus

La página del pedido muestra un bloque Transbank Webpay Plus con la orden de compra y su entorno, el estado del pago, el código de autorización, la tarjeta y el tipo de pago con el número de cuotas, el importe cobrado y reembolsado, una insignia Integration para los pagos de prueba, el historial de reembolsos, los Webpay attempts of the cart y las Transbank notes del pedido.

Reembolsos

En el bloque Transbank Webpay Plus introduce el importe en CLP (se rellena el importe que aún no se ha reembolsado), opcionalmente un motivo, 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 editar pedidos; no hace falta acceso a las páginas de Módulos. Un importe parcial con decimales se rechaza con Webpay refunds are in whole Chilean pesos. Please enter an amount without decimals. El resto de un total de pedido con decimales se redondea igual que el cobro. Los reembolsos llegan hasta el importe que Transbank cobró, así que después de una discrepancia puedes reembolsar lo que el cliente realmente pagó. 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 reversa (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 pone el pedido en Refunded. Un reembolso parcial no cambia el estado. Si Transbank no acepta el reembolso, el bloque muestra el error y no se registra ningún reembolso.

El módulo no crea notas de crédito. Los botones de reembolso estándar de PrestaShop de la página del pedido no devuelven dinero a través de Transbank. Los reembolsos hechos en el portal de Transbank no se importan a PrestaShop.

Clave de licencia

El módulo funciona con una clave de licencia de VibeFox de vibefox.net. El bloque de licencia License — VibeFox Transbank Gateway es el primer bloque de Modules > Module Manager > VibeFox Transbank Gateway > Configure, 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 quitar la clave de esta tienda. Debajo aparecen la línea Product: presta-payment-transbank 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 tras liberar un 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 solo dominio: el dominio de la tienda principal, también en una configuración multitienda. Quitar la clave de la tienda no libera su dominio. Libéralo en tu cuenta de vibefox.net.

Sin una clave activa, Webpay Plus no se muestra a los clientes en la compra. Si se inicia un pago de todos modos, 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 se oculta para ti: puedes configurar el módulo antes de comprar una clave, pero no probarlo en la compra. Aparece un recordatorio en Modules > Module Manager, en la pestaña Alerts. Los pedidos existentes no se ven afectados: los pagos ya iniciados se siguen confirmando cuando el cliente vuelve de Webpay, y los reembolsos desde la página del pedido funcionan.

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 ningún cron job. Desinstalar o restablecer el módulo elimina siempre la clave de licencia y el estado de la licencia.

Solución de problemas

Webpay Plus no aparece en la compra: comprueba que la licencia esté activa, que Enable / Disable esté activado, que la moneda del carrito sea 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. La página de ajustes muestra un aviso por cada condición que falte. En Payment > Preferences comprueba que el módulo esté permitido para CLP, el país del cliente y el grupo del cliente.

El pago se realizó, pero no se creó ningún pedido: Transbank no tiene webhook, así que el pedido se crea solo cuando el cliente vuelve 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, mira 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. No se creó ningún pedido 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 cart changed after the Webpay payment was started: el total del carrito era distinto al de la transacción, por ejemplo por un cambio en otra pestaña o un cupón caducado. No se cobró nada; el cliente paga el nuevo total.

El cliente ve un error al elegir Webpay Plus: activa Debug log y mira el campo Log de la página del módulo. Webpay payments are not available at the moment suele significar 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 carrito está en otra moneda.

Los totales y los reembolsos difieren en unos pocos pesos: la moneda CLP tiene decimales. Webpay cobra solo pesos enteros, así que los totales se redondean. Pon la precisión de CLP en 0 en International > Localization > Currencies.

El pedido queda como Transbank payment on hold tras el pago: lee las notas del bloque Transbank Webpay Plus (consulta Estados del pedido) y luego 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 y vuelve a intentarlo.

El reembolso falla con Transbank refused the refund o 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. Comprueba 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 Modules > Module Manager, abre el menú junto a VibeFox Transbank 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, se conservan todos los ajustes para una reinstalación posterior. Los intentos de Webpay y los reembolsos de los pedidos, así como el estado de pedido Transbank payment on hold, siempre se conservan, así que los pedidos pagados antes se pueden reembolsar después de reinstalar. Los pedidos existentes conservan sus notas de pago y sus IDs de transacción.

Transbank y Webpay son marcas comerciales de sus respectivos propietarios. Este módulo no está afiliado ni respaldado por Transbank.