VibeFox Tranzila 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 de la tienda: ILS, USD, EUR o GBP. Para otras monedas del carrito, el método de pago no se muestra al finalizar la compra.

Terminal de Tranzila: necesitas el nombre del terminal. La contraseña del terminal (TranzilaPW) se necesita para el handshake y para los reembolsos desde la página del pedido. Algunos terminales también necesitan una contraseña de crédito aparte (CreditPass) para los reembolsos. El nombre del terminal y las contraseñas los proporciona Tranzila: consulta la configuración de tu terminal o pide ayuda al soporte de Tranzila. Tranzila no tiene sandbox público. Para hacer pruebas, Tranzila te da un terminal de prueba independiente; introduce su nombre como nombre del terminal.

IP real del visitante: las notificaciones de pago se comprueban con la dirección IP del servidor de Tranzila. Si tu tienda está detrás de un proxy o CDN como Cloudflare, el servidor web debe pasar la IP real del visitante a PHP (REMOTE_ADDR).

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 carga, haz clic en Configure, o busca más tarde VibeFox Tranzila Payment 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. Introduce el Terminal name (supplier) y la Terminal password (TranzilaPW) si usas el handshake o los reembolsos.

5. Deja Notifications activado y revisa Trusted IP: debe incluir las direcciones IP desde las que Tranzila envía las notificaciones. Confirma la lista con el soporte de Tranzila.

6. Recomendado: activa el handshake en el terminal de Tranzila, permite allí la IP de tu servidor y después activa Handshake en el módulo.

7. Activa Enable/Disable, haz clic en Save y prueba un pago con el terminal de prueba de Tranzila.

Al instalarse, el módulo crea el estado de pedido Tranzila payment on hold. PrestaShop ofrece un 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 Tranzila Payment 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 cuando el nombre del terminal está vacío (entonces el método de pago no se muestra al finalizar la compra), cuando las notificaciones están desactivadas o Trusted IP está vacío (los pedidos pagados pasan entonces a espera para revisión manual), cuando el handshake está activado sin contraseña del terminal (no se puede abrir la página de pago) y cuando la moneda predeterminada de la tienda no es compatible. Al guardar, no se guarda un nombre de terminal no válido, una entrada no válida en Trusted IP ni un campo numérico que no sea un número entero: la página muestra un error y se mantiene el valor anterior. Un número fuera del rango permitido se guarda como el valor permitido más cercano, y la página te lo indica.

Tranzila

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

Title: el nombre del método de pago que ven los clientes al finalizar la compra y el título de la página de pago. También es el nombre del método de pago que se guarda en el pedido. Predeterminado: Credit Card (Tranzila).

Description: el texto que se muestra bajo el método de pago al finalizar la compra. Predeterminado: Pay securely with your credit card on the Tranzila payment page.

Terminal

Terminal name (supplier): el nombre de tu terminal de Tranzila, por ejemplo myshop. Solo letras, dígitos, «-» y «_». Mientras no se introduzca, el método de pago no se muestra al finalizar la compra. Para hacer pruebas, introduce el nombre de tu terminal de prueba de Tranzila.

Terminal password (TranzilaPW): la contraseña de API del terminal. Es necesaria para el handshake y para los reembolsos desde la página del pedido.

Refund password (CreditPass): solo si tu terminal requiere una contraseña aparte para las transacciones de crédito (reembolsos). Si no, déjala vacía.

Las contraseñas guardadas 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 passwords: marca una contraseña y haz clic en Save para eliminarla. Un campo vacío mantiene el valor guardado.

Página de pago

Payment page version: la página de Tranzila que se muestra en el iframe.

Payment page language: el idioma de la página de Tranzila: Site language, hebreo, inglés, ruso, español, alemán, francés o japonés. Predeterminado: hebreo. Site language usa el idioma del carrito del cliente si es uno de estos idiomas; si no, inglés.

iFrame width (px): de 300 a 1200. Predeterminado: 600. En pantallas pequeñas, el marco nunca es más ancho que la página.

iFrame height (px): de 400 a 1500. Predeterminado: 650.

Max installments: el número máximo de cuotas (tashlumim) que el cliente puede elegir en la página de pago, hasta 36. 0 o 1 significa sin cuotas. Predeterminado: 0. El terminal debe tener permiso para procesar cuotas.

Handshake: bloquea el importe con un token de handshake (recomendado). Antes de abrir la página de pago, la tienda pide a Tranzila un token único vinculado al importe, de modo que el importe no se puede cambiar en el navegador. Requiere la contraseña del terminal, que el handshake esté activado en el terminal de Tranzila y que la IP de tu servidor esté permitida allí. Predeterminado: desactivado.

Confirmación del pago

Las notificaciones de Tranzila no están firmadas. Un pedido se crea como pagado solo cuando la notificación llega desde una IP de confianza y su token de la página de pago, carrito, terminal, importe y moneda coinciden con la página de pago. Con el handshake, el token también debe coincidir con la página de pago. El regreso del cliente desde la página de pago nunca marca un pedido como pagado.

Notifications: confirma los pagos automáticamente con las notificaciones de Tranzila (URL de notificación). Predeterminado: activado. Cuando las notificaciones están desactivadas, un cliente que vuelve de una página de pago exitosa crea el pedido en Tranzila payment on hold, y tú confirmas el pago manualmente después de comprobar el terminal de Tranzila.

Notification URL: se muestra solo a título informativo. Con URLs amigables tiene este aspecto: https://your-shop/module/wcp_tranzila_payment_gateway/notify, posiblemente con un código de idioma. La URL se envía a Tranzila con cada pago, así que no tienes que introducirla en el terminal de Tranzila.

Trusted IP: las direcciones IP o rangos CIDR de los servidores de Tranzila que envían las notificaciones, separados por comas. Predeterminado: 80.244.170.7. Confirma la lista actual con el soporte de Tranzila. Las notificaciones desde otras direcciones se rechazan. Si el campo está vacío, las notificaciones no se pueden verificar: un pago exitoso notificado crea el pedido en Tranzila payment on hold para revisión manual, y un rechazo notificado no cambia nada.

Avanzado

Debug log: registra los eventos de la página de pago, las notificaciones y los reembolsos en logs/tranzila_p_debug.log.php, dentro de la carpeta del módulo. El archivo no se puede abrir desde la web. Los avisos y errores siempre se registran, incluso cuando esta opción está desactivada. Nunca se escriben contraseñas, tokens ni datos de clientes. 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 el módulo se eliminan los ajustes y los registros. Las transacciones y reembolsos de Tranzila y el estado de pedido Tranzila payment on hold siempre se conservan, porque los pedidos antiguos los necesitan. Predeterminado: desactivado.

Finalizar compra

En el paso de pago, el cliente elige el método de pago (predeterminado Credit Card (Tranzila)) y ve la descripción y la nota After you confirm, you will enter your card details on the secure Tranzila payment page. The order is created once Tranzila confirms the payment. Tras confirmar, el cliente pasa a una página de pago de tu tienda. Allí se abre la página de pago de Tranzila en un iframe, con el total del carrito en la moneda del carrito, los datos de facturación y una lista breve de los productos. La página dice Enter your card details on the secure Tranzila payment page below. If it does not load, click "Proceed to payment". El enlace Choose another payment method está debajo del marco. Si se permiten cuotas, el cliente elige su número en la página de Tranzila. En este momento todavía no existe ningún pedido.

Tras un pago exitoso, Tranzila devuelve al cliente y toda la ventana avanza. El pedido se marca como pagado solo cuando Tranzila lo confirma con una notificación. Si la notificación ya ha llegado, el cliente ve la página estándar de confirmación del pedido con Your payment with Tranzila has been received. Si el pedido está en espera de revisión, la página muestra Your payment is being reviewed by the store. You will receive an e-mail once it is confirmed. Si la notificación todavía no ha llegado, una página Payment confirmation muestra Your payment is being confirmed by Tranzila. You will receive an e-mail as soon as it is confirmed — there is no need to pay again. y un botón Check again.

Si el pago es rechazado o cancelado, el cliente vuelve a la finalización de compra con el mensaje The payment was not completed. You have not been charged — please try again or choose another payment method. Cuando Tranzila informa de un código de respuesta, se añaden el motivo y el código, por ejemplo que la tarjeta ha caducado. El carrito se conserva y no se crea ningún pedido. Cada vez que se abre la página de pago, es una página nueva con su propio token.

Si no se puede abrir la página de pago, por ejemplo cuando falla el handshake, el cliente ve un mensaje breve como Could not connect to Tranzila. Please try again in a moment. y el botón Choose another payment method. El motivo técnico se escribe en el registro.

La notificación funciona mientras la tienda está en modo de mantenimiento y no se bloquea por la restricción de países de tu tienda. Se usa la misma página de pago con los temas Classic y Hummingbird.

El módulo acepta solo pagos únicos con tarjeta, en la página de Tranzila. No tiene tarjetas ni tokens guardados, ni suscripciones, ni autorización y captura por separado (J5), ni botones propios de Bit, Apple Pay o Google Pay (lo que ofrezca tu página de pago de Tranzila se muestra dentro del iframe), ni facturas de Tranzila.

Pedidos y reembolsos

Estados del pedido

No order yet: el cliente fue enviado a la página de pago y no ha pagado, el pago fue rechazado o la notificación de Tranzila todavía no ha llegado. Solo existe el carrito.

Payment accepted: el pago fue confirmado mediante una notificación verificada. El pago se registra con el índice de transacción de Tranzila como ID de transacción, y una nota muestra el importe, la transacción, el número de autorización y el número de cuotas cuando las hay.

Tranzila payment on hold: el pago fue notificado pero no se aceptó automáticamente: no coincidieron el importe, la moneda o el token de handshake, la notificación no se pudo verificar porque Trusted IP está vacío, o las notificaciones están desactivadas y el cliente volvió de una página de pago exitosa. La nota explica el motivo. Comprueba el pago en el terminal de Tranzila y cambia el estado manualmente.

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

Si llega un pago para un pedido que fue cancelado, vuelve a ponerse en Payment accepted con una nota que te pide revisar el stock antes de enviarlo. Si llega un segundo pago para un pedido que ya está pagado o reembolsado, el pedido no cambia. Una nota te pide revisarlo y reembolsar el duplicado en el terminal de Tranzila. Las notificaciones repetidas de la misma transacción se ignoran.

Bloque de pago de Tranzila

La página del pedido muestra un bloque Tranzila payment con el índice de transacción, el número de autorización, el terminal, el estado, el importe pagado y reembolsado, el número de cuotas, el historial de reembolsos, todas las Payment pages of the cart con su resultado y las Tranzila notes del pedido.

Reembolsos

En el bloque Tranzila payment introduce el importe (se rellena el importe que aún no se ha reembolsado), opcionalmente un motivo, y haz clic en Refund via Tranzila. Confirma la pregunta Refund this amount via Tranzila? This cannot be undone. Se admiten reembolsos totales y parciales. Necesitas el permiso para editar pedidos; no hace falta acceso a las páginas de Módulos. El reembolso se realiza como transacción de crédito de Tranzila del pago original, en el terminal que lo cobró, por el importe y la moneda que Tranzila realmente cobró. Así que, tras una diferencia de importe o moneda, puedes reembolsar hasta lo que el cliente realmente pagó, no el total del pedido.

El formulario está disponible cuando la contraseña del terminal está configurada y el pedido tiene una transacción de Tranzila confirmada con número de autorización. Si no, el bloque indica el motivo, por ejemplo Refunds need the terminal password (TranzilaPW) in the gateway settings. Un pedido pagado en otro terminal distinto del que está ahora en los ajustes (por ejemplo, un terminal de prueba) no se puede reembolsar desde la página del pedido; reembólsalo en ese terminal de Tranzila.

Si Tranzila no acepta el reembolso, el bloque muestra el error, por ejemplo Tranzila declined the refund con el código y su significado, y no se registra ningún reembolso. Un reembolso exitoso se añade al historial de reembolsos y a las notas con la transacción de crédito de Tranzila. Un reembolso total pone el pedido en Refunded. Un reembolso parcial no cambia el estado.

El módulo no crea facturas de abono (credit slips). Los botones estándar de devolución de PrestaShop de la página del pedido no devuelven el dinero a través de Tranzila. Los reembolsos hechos en el terminal de Tranzila no se comunican a la tienda. Actualiza el pedido manualmente si es necesario.

Clave de licencia

El módulo funciona con una clave de licencia de VibeFox de vibefox.net. El bloque de licencia License — VibeFox Tranzila Payment Gateway es el primer bloque de Modules > Module Manager > VibeFox Tranzila Payment 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-tranzila 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, Tranzila no se muestra a los clientes al finalizar 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 al finalizar 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 con la notificación de Tranzila y con el regreso a la tienda, y los reembolsos 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

Tranzila no aparece al finalizar la compra: comprueba que la licencia está activa, que Enable/Disable está activado, que Terminal name (supplier) está rellenado y que la moneda del carrito es ILS, USD, EUR o GBP. La página de ajustes muestra un aviso cuando falta el nombre del terminal o la moneda predeterminada no es compatible. En Payment > Preferences comprueba que el módulo está permitido para la moneda del carrito, el país del cliente y el grupo del cliente.

El pago se realizó, pero no se creó ningún pedido: la notificación no llegó o fue rechazada. Comprueba que Notifications está activado y que Trusted IP incluye las direcciones desde las que Tranzila envía las notificaciones. Los errores siempre se escriben en el registro; consulta el campo Log de la página del módulo. El mensaje de que una IP no está en la lista Trusted IP significa que hay que corregir el ajuste Trusted IP o la configuración de tu proxy: detrás de un proxy o CDN, el servidor web debe pasar la IP real del visitante a PHP. Los desarrolladores cuya tienda está detrás de un proxy inverso de confianza pueden establecer la IP con el hook actionTranzilaPRemoteIp.

La notificación responde Forbidden: llegó desde una dirección IP que no está en Trusted IP.

La notificación responde Bad request o Not found: el carrito, el token de la página de pago, el terminal o el índice de transacción de la notificación no coinciden con ninguna página de pago de esta tienda.

La notificación responde Accepted for manual review: Trusted IP está vacío, así que la notificación no se pudo verificar. Un pago exitoso crea el pedido en espera. Rellena Trusted IP para confirmar los pagos automáticamente.

La notificación responde Busy, retry: el carrito estaba siendo procesado por otra petición en ese mismo momento, o no se pudo crear el pedido (por ejemplo, el módulo está desactivado). El registro muestra el motivo. Comprueba el pago en el terminal de Tranzila; si allí está aprobado y no se creó ningún pedido, contacta con el cliente o crea el pedido manualmente.

Algunos pedidos están en Tranzila payment on hold: lee las notas del bloque Tranzila payment. No coincidieron el importe, la moneda o el token de handshake, o la notificación no se pudo verificar (Trusted IP vacío o notificaciones desactivadas). Comprueba el pago en el terminal de Tranzila y cambia el estado manualmente.

La página de pago no se abre con el handshake activado: comprueba el nombre del terminal y la contraseña del terminal, que el handshake esté activado en el terminal de Tranzila y que la IP de tu servidor esté permitida allí. El registro muestra el motivo.

Los reembolsos fallan: los reembolsos necesitan Terminal password (TranzilaPW). Algunos terminales también requieren una contraseña de crédito aparte; introdúcela en Refund password (CreditPass). Los pedidos pagados en otro terminal deben reembolsarse en ese terminal. Si la respuesta de Tranzila es inesperada, el bloque indica que el reembolso no está confirmado: comprueba el terminal de Tranzila antes de volver a intentarlo.

Otras monedas: el módulo solo admite ILS, USD, EUR y GBP.

Desinstalación

Ve a Modules > Module Manager, abre el menú junto a VibeFox Tranzila Payment 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 y los registros. Si está desactivado, todos los ajustes se conservan para una reinstalación posterior. Las transacciones y reembolsos de Tranzila y el estado de pedido Tranzila payment on hold siempre se conservan, así que los pedidos pagados antes pueden seguir reembolsándose tras una reinstalación. Los pedidos existentes conservan sus notas de pago y sus ID de transacción.

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