VibeFox Paytrail for WooCommerce — Ayuda
Requisitos
WordPress: 6.0 o posterior.
WooCommerce: 7.0 o posterior, instalado y activo. El plugin no se activará sin él.
PHP: 8.0 o posterior.
Moneda de la tienda: EUR. Paytrail solo acepta euros. Con 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 para tu sitio: Paytrail confirma cada pago mediante una llamada de retorno servidor a servidor, por lo que el sitio debe ser accesible desde internet. Sin llamadas de retorno, los pedidos se siguen confirmando cuando el cliente regresa desde Paytrail.
Cuenta de Paytrail: necesitas tu ID de comerciante y tu clave secreta, que se muestran en el Panel de comerciante de Paytrail (detalles de la cuenta o de integración). Para las pruebas no se necesita ninguna cuenta: el modo de prueba usa la cuenta de prueba pública de Paytrail. Los métodos de pago en sí se activan en tu cuenta de Paytrail.
Clave de licencia de VibeFox: se compra en vibefox.net. Una clave funciona en un dominio.
Instalación
1. En WordPress ve a Plugins > Add New > Upload Plugin, elige el archivo ZIP del plugin y haz clic en Install Now. También puedes subir la carpeta wcp_paytrail_gateway a /wp-content/plugins/ por FTP.
2. Haz clic en Activate.
3. Abre la configuración: WooCommerce > Settings > Payments > Paytrail > Manage, o haz clic en Settings debajo del nombre del plugin en la página Plugins.
4. Introduce tu clave de licencia de VibeFox en el bloque de licencia de la parte superior de la página y haz clic en Activate.
5. Para probar el plugin primero, marca Test mode. Para pagos reales, desmárcalo e introduce tu Merchant ID y Secret key. No es necesario configurar ninguna URL de callback en Paytrail.
6. Activa Enable/Disable y guarda.
Configuración
Todos los ajustes están en una sola página: WooCommerce > Settings > Payments > Paytrail. Encima de los campos, la página muestra Test mode is active. mientras el modo de prueba está activado. En modo de producción te avisa cuando falta el ID de comerciante o la clave secreta, y te avisa cuando la moneda de la tienda no es EUR. En ambos casos, Paytrail no se muestra en la finalización de compra. En la lista de métodos de pago, Paytrail aparece marcado como pendiente de configuración mientras el modo de producción no tenga credenciales.
Al guardar, un ID de comerciante que contenga cualquier carácter que no sea dígitos no se guardará: se muestra un error y se conserva el valor anterior.
General
Enable/Disable: Enable Paytrail activa o desactiva el método de pago. Por defecto: desactivado.
Title: el título que se muestra a los clientes durante la finalización de compra. Por defecto: Paytrail.
Description: el texto que se muestra a los clientes 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 (detalles de la cuenta o de integración). Solo se admiten pagos en EUR.
Test mode: Use the Paytrail test account. Los nuevos pagos usan la cuenta de prueba pública de Paytrail (ID de comerciante 375917) en lugar de tus propias credenciales. No se cobra dinero real. Los clientes ven Test mode: no real payment will be made. en la finalización de compra. La clave secreta de la cuenta de prueba es pública, por lo que cualquiera podría simular un pago para un pedido creado en modo de prueba. Nunca dejes activado el modo de prueba en una tienda en producción. Por defecto: desactivado.
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.
Las llamadas de retorno y los reembolsos siempre usan las credenciales del modo en que se realizó el pago, por lo que cambiar entre prueba y producción no afecta a los pedidos anteriores.
Pedidos
Esta sección muestra la URL de callback, que tiene el formato https://your-site/wc-api/ptg_paytrail/. Paytrail confirma cada pago de servidor a servidor en esta URL. Se envía con cada pago, por lo que no es necesario configurar nada en el panel de Paytrail, pero el sitio debe ser accesible desde internet.
Order status after payment: el estado de un pedido pagado. El estado se asigna en un solo paso, por lo que el cliente recibe un único conjunto de correos electrónicos.
Avanzado
Debug log: Log API requests and callbacks. Se escribe en WooCommerce > Status > Logs, origen wcp_paytrail_gateway, sin datos personales ni claves. Los errores siempre se registran. Por defecto: desactivado.
Delete data on uninstall: Delete settings, logs and Paytrail order data when the plugin is deleted. Desactivar el plugin nunca elimina nada. Sin los datos de transacciones de Paytrail, los reembolsos de pedidos antiguos ya no serán posibles desde WooCommerce. Por defecto: desactivado.
Finalizar compra
El cliente elige el método de pago (por defecto Paytrail) y realiza el pedido. El plugin crea un pago en Paytrail por el total del pedido en euros y envía las líneas del pedido junto con él: productos, envío y tarifas, cada uno con su tipo de IVA a un decimal. Las líneas siempre suman el importe del pago; una diferencia de redondeo se incluye en una línea o se envía como una línea de Rounding. Las direcciones de facturación y de entrega solo se envían 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 la configuración regional de la tienda.
El cliente es dirigido a la página de pago de Paytrail, elige un método de pago activado en tu cuenta de Paytrail y paga. A continuación, Paytrail confirma el pago dos veces: envía al cliente de vuelta a tu tienda y llama a la URL de callback de servidor a servidor. Ambas cosas solo se aceptan con una firma válida realizada con las credenciales de ese intento de pago, y solo para el intento creado para ese pedido. El importe pagado se compara con el total del pedido. El pedido solo se marca como pagado después de que Paytrail lo confirma de este modo. El plugin gestiona estos estados de Paytrail:
Tras un pago correcto, el cliente ve la página de pedido recibido. Tras un pago cancelado o fallido, el cliente pasa a la página Pay for order con el mensaje The Paytrail payment was cancelled or failed. You can try again or choose another payment method. Si el pago aún no ha finalizado, el mensaje es The Paytrail payment has not been completed yet. You can try again or choose another payment method.
Si Paytrail no puede iniciar el pago, el cliente ve 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 añade a las notas del pedido y al registro. Los pedidos que superen el importe máximo de Paytrail no se pueden pagar con Paytrail.
Un pago de Paytrail no se puede cancelar a través de la API. Si el cliente inicia un nuevo pago y después también paga en una página de pago anterior que aún estaba abierta, el segundo pago se registra en las notas del pedido como un duplicado a reembolsar.
El método de pago funciona en la finalización de compra clásica, en el bloque de Finalizar compra y en la página Pay for order. Es compatible con el almacenamiento de pedidos de alto rendimiento de WooCommerce (HPOS).
El cliente elige el método de pago en la página de Paytrail, no en tu finalización de compra. El plugin no tiene tokenización de tarjetas ni tarjetas guardadas, ni WooCommerce Subscriptions, ni shop-in-shop, ni activación manual de facturas ni informes de liquidación.
Pedidos y reembolsos
Estados del pedido
Pending payment: el pago de Paytrail se creó y el cliente aún no ha pagado. La nota del pedido muestra el ID de transacción de Paytrail, el importe y el modo.
Processing or Completed: el pago fue confirmado. El estado sigue a Order status after payment. La nota del pedido muestra la transacción, el método de pago utilizado en Paytrail y el importe. El ID de transacción es el ID de transacción de Paytrail.
On hold: el pago está pendiente en el proveedor (factura o pago diferido), el importe pagado difiere del total del pedido, el pago llegó después de que el pedido hubiera sido cancelado o se recibió un pago de prueba mientras la tienda está en producción (no hay dinero real). La nota del pedido explica el motivo. Revisa el pedido y después procésalo o reembolsa el pago.
Failed: el último intento de pago falló o fue cancelado por el cliente. El cliente puede pagar de nuevo.
Las llamadas de retorno repetidas o paralelas nunca crean notas duplicadas, reducciones de stock ni correos electrónicos. Si se paga un segundo intento de un pedido ya pagado, el pedido no se modifica de nuevo; una nota de Duplicate payment te pide que lo reembolses en el Panel de comerciante de Paytrail.
Reembolsos
Abre el pedido, haz clic en Refund, introduce el importe y haz clic en Refund via Paytrail (el botón muestra tu Title). Se admiten reembolsos totales y parciales, solo por importes (sin líneas de artículos a reembolsar). El botón solo está disponible para pedidos con un pago de Paytrail confirmado. El reembolso usa las credenciales del modo en que se realizó el pago, por lo que para un pago en producción deben estar configuradas las credenciales de producción.
Si el método de pago no admite reembolsos directos, el plugin inicia automáticamente un reembolso por correo electrónico: Paytrail envía un correo electrónico al cliente para que introduzca una cuenta bancaria. Para esto se necesita un correo electrónico de facturación en el pedido. La nota del pedido indica qué tipo de reembolso se inició.
Un reembolso puede completarse de inmediato o procesarse más tarde. La confirmación posterior de Paytrail se añade como una nota. Si Paytrail no pudo completar el reembolso, una nota indica que el dinero no se devolvió al cliente: reembolsalo por otra vía y elimina el reembolso de WooCommerce. Si Paytrail rechaza el reembolso de inmediato, WooCommerce muestra el error y no se registra ningún reembolso.
Los reembolsos realizados en el Panel de comerciante de Paytrail no se sincronizan con WooCommerce.
Clave de licencia
El plugin funciona con una clave de licencia de VibeFox de vibefox.net. El bloque de licencia está en la parte superior de WooCommerce > Settings > Payments > Paytrail. Pega la clave en License key y haz clic en Activate. El bloque muestra el estado, por ejemplo la fecha hasta la que la licencia está activa y tu dominio. Usa Check now para comprobar el estado de nuevo, Change key para introducir otra clave y Remove key para eliminarla de este sitio. El enlace Manage licenses and domains in your account abre tu cuenta de vibefox.net.
Una clave funciona en un dominio. Eliminar la clave de un sitio no libera su plaza de dominio. Libera la plaza en tu cuenta de vibefox.net.
Sin una clave activa, Paytrail 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. Los gestores de la tienda que hayan iniciado sesión siguen viendo el método de pago, marcado como (unlicensed — visible to admins only), para que puedas configurar y probar el plugin antes de comprar una clave. Aparece un recordatorio en la página Plugins y en las páginas de WooCommerce. Los pedidos existentes no se ven afectados: los pagos ya iniciados se siguen confirmando y los reembolsos funcionan.
Cuando una licencia caduca, el plugin sigue funcionando, pero las actualizaciones y el soporte requieren una renovación. El estado se vuelve a comprobar automáticamente en segundo plano.
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 completados. Comprueba que la moneda de la tienda (o la moneda del pedido en la página Pay for order) sea EUR. La página de ajustes muestra un aviso para cada uno de estos problemas.
El pago se realizó, pero el pedido sigue en Pendiente de pago: la llamada de retorno no puede llegar a tu sitio y el cliente no volvió a la tienda. La URL de callback mostrada en la sección Orders debe ser accesible desde internet (sin modo de mantenimiento, autenticación básica ni firewall de por medio).
La llamada de retorno o el regreso responde Payment verification failed.: la firma no es válida o el pago no pertenece a un intento de pago del pedido. El pedido no se modifica. Comprueba que la Secret key sea correcta y pertenezca al Merchant ID.
El pago no se crea: la nota del pedido y el registro muestran el error de Paytrail, por ejemplo Paytrail API error (401): … para credenciales incorrectas. Activa Debug log y consulta WooCommerce > Status > Logs, origen wcp_paytrail_gateway.
El ID de comerciante no se guarda: solo debe contener dígitos. Cópialo de nuevo desde el Panel de comerciante de Paytrail.
El pedido está en En espera: lee la nota del pedido. El motivo es un pago pendiente o diferido, un importe pagado diferente, un pago posterior a la cancelación o un pago de prueba en modo de producción.
El reembolso falla: lee el mensaje. This order has no confirmed Paytrail payment. Refund it manually. significa que no hay un pago confirmado de Paytrail que reembolsar. Un mensaje sobre la falta de credenciales de producción significa que el pago se realizó en modo de producción y las credenciales de producción no están configuradas. Si el método de pago solo admite reembolsos por correo electrónico, el pedido necesita un correo electrónico de facturación.
Hooks para desarrolladores: el filtro ptg_payment_request modifica la solicitud de pago antes de que se firme y se envíe; el filtro ptg_icon modifica el icono de la finalización de compra.
El bloque de licencia muestra un error: sigue las indicaciones del mensaje del bloque. Por ejemplo, si la clave ya se usa en otro dominio, libera una plaza en tu cuenta de vibefox.net y haz clic en Check now. Si cambió la dirección del sitio, haz clic en Check now para activar la clave para el nuevo dominio. Si no se puede acceder al servidor de licencias, el plugin sigue funcionando con el último estado conocido.
Desinstalación
Desactivar el plugin conserva todos los datos. Para eliminarlo, desactívalo y elimínalo en la página Plugins. La clave de licencia y el estado de licencia de este plugin siempre se eliminan. Los ajustes de la pasarela, el registro de este plugin y los datos de Paytrail guardados en los pedidos (intentos de pago, datos de transacciones, registros de reembolsos) se eliminan solo si Delete data on uninstall estaba activado. De lo contrario, se conservan para una reinstalación posterior. Los pedidos existentes conservan sus notas de pago e ID de transacción; sin los datos de Paytrail, los pedidos antiguos ya no podrán ser reembolsados desde WooCommerce.
Paytrail es una marca comercial de su respectivo propietario. Este plugin no está afiliado a Paytrail ni cuenta con su respaldo.