VibeFox Paytrail 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: EUR. Paytrail solo acepta euros. Para un carrito en cualquier otra moneda, el método de pago se oculta en la finalización de compra. Los importes se envían en céntimos.
Acceso a internet a tu tienda: Paytrail confirma cada pago mediante una llamada de callback servidor a servidor, así que la tienda debe ser accesible desde internet. Sin las llamadas de callback, los pedidos se crean igualmente cuando el cliente vuelve desde Paytrail.
Cuenta de Paytrail: necesitas tu ID de comerciante y tu clave secreta, que se muestran en el Panel de comerciante de Paytrail (datos de la cuenta o de la integración). Para las pruebas no hace falta ninguna cuenta: el modo de prueba usa la cuenta de prueba pública de Paytrail. Los métodos de pago se activan en tu cuenta de Paytrail.
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 VibeFox Paytrail Gateway más tarde en la lista de módulos y haz clic en Configure.
3. Pega tu clave de licencia de VibeFox en License key del bloque de licencia de la parte superior de la página Configure y haz clic en Activate (ver Clave de licencia).
4. Para probar primero el módulo, activa Test mode. Para los pagos reales, desactívalo e introduce tu Merchant ID y tu Secret key. No hace falta configurar ninguna URL de callback en Paytrail.
5. Activa Enable/Disable y haz clic en Save.
Al instalarse, el módulo crea dos estados de pedido, Awaiting Paytrail payment y Paytrail payment on hold. PrestaShop ofrece un nuevo módulo de pago para todas las monedas, países y grupos de clientes. Puedes limitarlo en Payment > Preferences.
Configuración
Todos los ajustes están en la página del módulo: Modules > Module Manager > VibeFox Paytrail Gateway > Configure. Cada sección tiene su propio botón Save, que guarda toda la página. Encima de los campos, la página muestra Test mode is active. Payments use the public Paytrail test account — no real money is charged. mientras el modo de prueba está activado. En modo real avisa cuando falta el ID de comerciante o la clave secreta, o cuando el ID de comerciante es la cuenta de prueba pública 375917. También avisa cuando la moneda de la tienda no es EUR. En todos estos casos, Paytrail no se muestra en la finalización de compra.
Al guardar, un ID de comerciante que contenga algo distinto de dígitos no se guarda, y se muestra el error Paytrail merchant ID must contain digits only. The previous value was kept.. El campo Title no puede estar vacío.
Paytrail
Enable/Disable: Enable Paytrail activa o desactiva el método de pago. Por defecto: off.
Title: el título que se muestra a los clientes durante la finalización de compra. También es el nombre del método de pago guardado en el pedido. Por defecto: Paytrail. Obligatorio.
Description: el texto que se muestra a los clientes debajo del método de pago durante la finalización de compra. Por defecto: Pay securely with Finnish online banking, card, mobile payment or invoice on the Paytrail payment page.
Credenciales de API
Tu ID de comerciante y tu clave secreta se muestran en el Panel de comerciante de Paytrail (datos de la cuenta o de la integración). La sección enlaza con el Panel de comerciante. Solo se admiten pagos en EUR.
Test mode: usa la cuenta de prueba pública de Paytrail (ID de comerciante 375917) para los pagos nuevos, en lugar de tus propias credenciales. No se cobra dinero real y no hacen falta claves. Los clientes ven Test mode: no real payment will be made. debajo del método de pago. La clave secreta de la cuenta de prueba es pública, así que cualquiera podría simular un pago hecho en modo de prueba. Nunca mantengas el modo de prueba activado en una tienda real. Por defecto: off.
Merchant ID: tu ID de comerciante de Paytrail (solo dígitos). Se usa cuando el modo de prueba está desactivado.
Secret key: tu clave secreta de Paytrail. Se usa cuando el modo de prueba está desactivado. La clave guardada nunca vuelve a mostrarse. El campo queda vacío y muestra Saved — leave empty to keep it. Escribe un valor nuevo solo si quieres cambiarla.
Clear saved secret key: marca Secret key y haz clic en Save para eliminar la clave guardada. Un campo vacío mantiene el valor guardado.
Las llamadas de callback y los reembolsos siempre usan las credenciales del modo en que se hizo el pago, así que cambiar entre prueba y real no rompe los pedidos anteriores.
Pedidos
Callback URL: muestra la URL en la que Paytrail confirma cada pago servidor a servidor. Con URLs amigables tiene este aspecto: https://your-shop/module/wcp_paytrail_gateway/callback. Se envía con cada pago, así que no hay que configurar nada en el panel de Paytrail, pero la tienda debe ser accesible desde internet.
Order status after payment: el estado de un pedido pagado.
Los pagos pendientes esperan en Awaiting Paytrail payment. Las diferencias de importe y otros problemas siempre van a Paytrail payment on hold.
Avanzado
Debug log: registra las peticiones a la API y las llamadas de callback en logs/ptg_debug.log.php, dentro de la carpeta del módulo. El archivo no se puede abrir desde la web. Los datos personales y las claves no se registran. Los errores y las advertencias siempre se registran. Por defecto: 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 el módulo se eliminan los ajustes y el registro. Desactivar el módulo nunca borra nada. Los datos de transacción de Paytrail de los pedidos siempre se conservan, porque los reembolsos de pedidos antiguos los necesitan. Por defecto: off.
Finalización de compra
En el paso de pago, el cliente elige el método de pago (por defecto Paytrail) y confirma. El módulo crea un pago de Paytrail por el total del carrito en euros y envía con él las líneas del pedido: productos después de las reglas del carrito, envío y envoltorio de regalo, cada uno con su tipo de IVA de un decimal. Las líneas siempre suman el importe del pago; una diferencia de redondeo se incorpora a una línea o se envía como una línea Rounding. Las direcciones de facturación y de entrega se envían solo cuando están completas, y los valores largos se acortan a los límites de Paytrail. El idioma de la página de pago es finlandés, sueco o inglés, según el idioma del carrito. En este punto todavía no existe ningún pedido.
El cliente es enviado a la página de pago de Paytrail, elige un método de pago activado en tu cuenta de Paytrail y paga. Después, Paytrail confirma el pago dos veces: devuelve al cliente a tu tienda y llama a la URL de callback servidor a servidor. Ambas confirmaciones se aceptan solo con una firma válida hecha con las credenciales de ese intento de pago, y solo para un intento creado para ese carrito. El importe pagado se compara con el total del carrito. El pedido se marca como pagado solo después de que Paytrail lo confirme de esta forma. El módulo gestiona estos estados de Paytrail:
Tras un pago correcto, el cliente ve la página estándar de confirmación del pedido con Your Paytrail payment has been received. En un pago pendiente, la página muestra Your Paytrail payment is pending confirmation by the payment provider. The order is updated automatically — please do not pay again. Si la llamada de callback registra el pago en ese mismo momento, una página Payment confirmation pide al cliente que no pague de nuevo y ofrece un botón Check again.
Tras un pago cancelado o fallido, el cliente vuelve a la finalización de compra con The Paytrail payment was cancelled or failed. You can try again or choose another payment method. Si el pago aún no ha terminado, el mensaje es The Paytrail payment has not been completed yet. You can try again or choose another payment method. El carrito se conserva. Un regreso que no puede verificarse muestra Payment verification failed. y no cambia nada.
Si Paytrail no puede iniciar el pago, el cliente permanece en la finalización de compra con un mensaje breve, por ejemplo Could not connect to Paytrail. Please try again in a moment., Paytrail is temporarily unavailable. Please choose another payment method. (credenciales incorrectas) o Paytrail could not start the payment. Please check your billing details and try again, or choose another payment method. El motivo técnico se escribe en el registro. Un total fuera de los límites de Paytrail muestra This order total cannot be paid with Paytrail. Please choose another payment method.
Un pago de Paytrail no se puede cancelar a través de la API. Cada nuevo intento para el carrito es un nuevo pago de Paytrail. Si el cliente paga también una página de pago anterior que sigue abierta, el segundo pago se indica en el pedido como duplicado a reembolsar.
La llamada de callback funciona mientras la tienda está en modo de mantenimiento y no la bloquea la restricción por país de tu tienda.
El cliente elige el método de pago en la página de Paytrail, no en tu finalización de compra. El módulo no tiene tokenización de tarjetas ni tarjetas guardadas, ni suscripciones, ni shop-in-shop, ni activación manual de facturas, ni informes de liquidación.
Pedidos y reembolsos
Estados del pedido
Todavía sin pedido: el cliente fue enviado a Paytrail y no ha pagado, o Paytrail todavía no ha confirmado el pago. Solo existe el carrito.
Payment accepted or Delivered: el pago fue confirmado. El estado sigue a Order status after payment. El pago se registra con el ID de transacción de Paytrail, y una nota muestra la transacción, el método de pago usado en Paytrail y el importe.
Awaiting Paytrail payment: el pago está pendiente en el proveedor (factura o pago diferido). El pedido pasa al estado de pagado cuando Paytrail confirma el pago, o a Payment error cuando falla.
Paytrail payment on hold: el importe pagado no coincide con el total del pedido (se registra el importe realmente pagado), el pago llegó después de que el pedido se hubiera cancelado, o se recibió un pago de prueba mientras la tienda está en modo real (sin dinero real, no se registra nada). La nota explica el motivo. Revisa el pedido y luego tramítalo o reembolsa el pago.
Payment error: un pago pendiente falló o se canceló.
Refunded: el pago se reembolsó por completo a través del módulo.
Las llamadas de callback repetidas o paralelas nunca crean un segundo pedido ni notas duplicadas. Si se paga un segundo intento de un carrito ya pagado, el pedido no cambia; una nota Duplicate payment te pide reembolsarlo en el Panel de comerciante de Paytrail.
Bloque de pago de Paytrail
La página del pedido muestra un bloque Paytrail payment con el ID de transacción, el modo (una insignia TEST mode para los pagos de prueba), el método de pago, el estado de Paytrail, el importe pagado y reembolsado, el formulario de reembolso, el historial de reembolsos, los intentos de pago del carrito y las Paytrail notes del pedido.
Reembolsos
En el bloque Paytrail payment introduce el importe (se rellena el importe que aún no se ha reembolsado), opcionalmente un motivo para la nota del pedido, y haz clic en Refund via Paytrail. Confirma la pregunta Refund this amount through Paytrail? This cannot be undone. Se admiten reembolsos totales y parciales, solo por importe. Necesitas el permiso para editar pedidos; no hace falta acceso a las páginas de Módulos. Puedes reembolsar hasta el importe que Paytrail realmente cobró, así que tras una diferencia de importe el límite es lo que pagó el cliente, no el total del pedido. El reembolso usa las credenciales del modo en que se hizo el pago, así que para un pago real deben estar configuradas las credenciales reales. Los reembolsos están disponibles una vez que Paytrail ha confirmado el pago.
Si el método de pago no admite reembolsos directos, el módulo inicia automáticamente un reembolso por correo electrónico: Paytrail envía un correo al cliente para que introduzca una cuenta bancaria. Esto requiere el correo electrónico del cliente en el pedido. La nota indica qué tipo de reembolso se ha iniciado.
Un reembolso puede completarse de inmediato o procesarse más tarde. La confirmación posterior de Paytrail se añade como nota. Si Paytrail no pudo completar el reembolso, una nota indica que el dinero no se devolvió al cliente, y el reembolso deja de contar como reembolsado; reembolsa al cliente por otra vía. Si Paytrail rechaza el reembolso de inmediato, el bloque muestra el error y no se registra ningún reembolso. Un reembolso total pone el pedido en Refunded. Un reembolso parcial no cambia el estado.
El módulo no crea vales de crédito. Los botones de reembolso estándar de PrestaShop en la página del pedido no devuelven dinero a través de Paytrail. Los reembolsos realizados en el Panel de comerciante de Paytrail no se sincronizan de vuelta con PrestaShop.
Clave de licencia
El módulo funciona con una clave de licencia de VibeFox de vibefox.net. El bloque de licencia License — VibeFox Paytrail Gateway es el primer bloque de Modules > Module Manager > VibeFox Paytrail 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 eliminar la clave de esta tienda. Debajo aparecen la línea Product: presta-payment-paytrail y el enlace Manage licenses and domains in your account, que abre tu cuenta de vibefox.net. Solo los empleados con el permiso Configure para el módulo pueden cambiar la clave. Los textos del bloque siguen el idioma del back office (se incluyen el inglés y el 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 de liberar una plaza de 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 plaza de dominio. Libérala en tu cuenta de vibefox.net.
Sin una clave activa, Paytrail 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. La tienda de PrestaShop 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 finalización de compra. En Modules > Module Manager, en la pestaña Alerts, aparece un recordatorio. Los pedidos existentes no se ven afectados: los pagos ya iniciados se siguen confirmando mediante los callbacks y el regreso del cliente, y los reembolsos funcionan.
Cuando una licencia caduca, el módulo sigue funcionando, pero las actualizaciones y el soporte necesitan 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 después de introducir la clave, y después una vez a la semana. No hace falta configurar ninguna tarea cron. Desinstalar o restablecer el módulo elimina siempre la clave de licencia y el estado de la licencia.
Solución de problemas
Paytrail no aparece en la finalización de compra: comprueba que la licencia esté activa, que Enable/Disable esté activado y que Test mode esté activado o que Merchant ID y Secret key estén rellenados (no la cuenta de prueba pública 375917). Comprueba que la moneda del carrito sea EUR. 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. La página de ajustes muestra una advertencia si faltan credenciales o si la moneda de la tienda no es la correcta.
El pago se realizó, pero no se creó ningún pedido: la llamada de callback no puede llegar a tu tienda y el cliente no volvió a la tienda. La Callback URL que se muestra en la sección Pedidos debe ser accesible desde internet (sin autenticación básica ni cortafuegos que lo bloquee).
La llamada de callback o el regreso responde Payment verification failed.: la firma no es válida, o el pago no pertenece a un intento de pago del carrito. No se cambia nada. Comprueba que la Secret key sea correcta y pertenezca al Merchant ID.
La llamada de callback responde Temporarily unavailable: el pedido estaba siendo confirmado por otra petición en ese mismo momento, o el pedido no pudo crearse (por ejemplo, el módulo está desactivado). Paytrail vuelve a llamar. Consulta el campo Log para ver el motivo.
El cliente ve un error al elegir Paytrail: revisa el campo Log en la página del módulo. Por ejemplo, Paytrail API error (401) significa credenciales incorrectas. Activa Debug log para ver más detalles.
El ID de comerciante no se guarda: debe contener solo dígitos. Cópialo de nuevo desde el Panel de comerciante de Paytrail.
El pedido está en Paytrail payment on hold: lee las notas del bloque Paytrail payment. El motivo es un importe pagado distinto, un pago posterior a la cancelación o un pago de prueba en modo real.
El reembolso falla: lee el mensaje. This order has no confirmed Paytrail payment. Refund it manually. significa que no hay ningún pago de Paytrail confirmado que reembolsar. The live Paytrail credentials used for this payment are missing. Enter them in the Paytrail settings. significa que el pago se hizo en modo real y que las credenciales reales no están configuradas. Invalid refund amount: at most … significa que el importe es mayor que lo que queda por reembolsar. Si el método de pago solo admite reembolsos por correo electrónico, el pedido necesita el correo electrónico del cliente.
Hook para desarrolladores: el hook actionWcpPaytrailPaymentRequest modifica la petición de pago antes de firmarla y enviarla.
Desinstalación
Ve a Modules > Module Manager, abre el menú junto a VibeFox Paytrail 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 el registro. Si está desactivado, todos los ajustes se conservan para una reinstalación posterior. Las transacciones y reembolsos de Paytrail y los estados de pedido Awaiting Paytrail payment y Paytrail payment on hold siempre se conservan, de modo que los pedidos pagados antes pueden reembolsarse tras una reinstalación. Los pedidos existentes conservan sus notas de pago y sus ID de transacción.
Paytrail es una marca comercial de su respectivo propietario. Este módulo no está afiliado a Paytrail ni cuenta con su respaldo.