VibeFox TrustPay for WooCommerce — Ayuda
Requisitos
WordPress: 6.0 o posterior.
WooCommerce: 7.0 o posterior, instalado y activo. El plugin no se activa sin él.
PHP: 8.0 o posterior.
Cuenta de finby (TrustPay): necesitas un proyecto en el Merchant Portal de finby con su ID de proyecto y su clave secreta. Para los pagos de prueba necesitas un proyecto de prueba (playground) independiente, con su propio ID de proyecto y clave secreta. No se necesitan otras claves: la clave secreta se usa tanto para obtener acceso a la API como para comprobar la firma de las notificaciones de pago.
URL de notificación accesible: finby debe poder llegar a tu sitio desde internet. Un cortafuegos, el modo de mantenimiento o la protección con contraseña del sitio bloquean las notificaciones de pago.
Clave de licencia de VibeFox: se compra en vibefox.net. Una clave funciona en un solo 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_trustpay_gateway a /wp-content/plugins/ por FTP.
2. Haz clic en Activate.
3. Abre la configuración: WooCommerce > Settings > Payments > TrustPay / finby, 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. Introduce el ID de proyecto y la clave secreta de tu proyecto de producción y, para las pruebas, los de tu proyecto de prueba (consulta Configuración).
6. Activa Enable / Disable y guarda. Haz un pago de prueba con Test mode activado y luego desmarca Test mode para cobrar pagos reales.
Al actualizar desde la versión 1.0, tu ID de proyecto y tu clave secreta se conservan como credenciales de producción y el modo de prueba se desactiva. Revisa la configuración después de la actualización.
Configuración
Todos los ajustes están en una sola página: WooCommerce > Settings > Payments > TrustPay / finby. Encima de los campos, la página te avisa cuando la pasarela está activada pero el ID de proyecto o la clave secreta del modo actual están vacíos, y cuando la moneda de la tienda no es compatible. En ambos casos, el método de pago se oculta en la finalización de compra. En la lista de métodos de pago, la pasarela aparece marcada como pendiente de configuración hasta que el modo actual tenga su ID de proyecto y su clave secreta.
General
Enable / Disable: Enable TrustPay / finby card payments activa o desactiva el método de pago. Predeterminado: desactivado.
Title: el nombre del método de pago que ven los clientes en la finalización de compra. Predeterminado: Card payment (TrustPay).
Description: el texto que se muestra debajo del método de pago en la finalización de compra. Predeterminado: Pay securely by card on the TrustPay / finby payment page.
API credentials
Copia el ID de proyecto y la clave secreta de tu proyecto desde el Merchant Portal de finby (TrustPay). La sección tiene un enlace al Merchant Portal. Los pagos de prueba usan un proyecto de prueba (playground) independiente, con su propio ID de proyecto y clave secreta. No se cobra dinero real allí.
Test mode: Use the test project (no real payments). Los pagos nuevos y los reembolsos usan las credenciales de prueba. Los reembolsos de un pedido siempre se hacen en el proyecto con el que se pagó el pedido. Predeterminado: activado.
Live Project ID: el ID numérico de tu proyecto de producción.
Live Secret key: la clave secreta del proyecto de producción. Se usa para obtener tokens de acceso a la API y para verificar las notificaciones de pago.
Test Project ID: el ID numérico de tu proyecto de prueba (playground).
Test Secret key: la clave secreta del proyecto de prueba.
El ID de proyecto debe contener solo dígitos. Si guardas otro valor, la página muestra un error y se mantiene el valor anterior. Las claves secretas se guardan exactamente como las introduces; solo se eliminan los espacios al principio y al final.
Payment notifications
El pedido solo se marca como pagado cuando finby confirma el pago con una notificación firmada. El plugin envía automáticamente la URL de notificación con cada pago, así que no tienes que configurarla. La sección muestra la URL, por ejemplo https://your-site/wc-api/trustpay_payment_callback/. También puedes introducirla como URL de notificación de tus proyectos en el Merchant Portal. Las notificaciones sin firma válida se rechazan.
El plugin no consulta a finby el estado del pago por su cuenta. Si una notificación no llega a tu sitio, el pedido permanece en Pending payment hasta que finby la entregue.
Advanced
Order status after payment: el estado del pedido que se establece tras un pago correcto. El estado se cambia en un solo paso, así que el cliente recibe un único correo.
Debug logging: Log API requests and notifications añade detalles al registro. Los errores siempre se registran, incluso cuando esta opción está desactivada. Los registros están en WooCommerce > Status > Logs, origen wcp_trustpay_gateway, y no contienen claves, tokens, datos de tarjeta ni datos de clientes. Predeterminado: desactivado.
Delete data on uninstall: Remove the plugin settings and logs when the plugin is deleted (order data is kept). Predeterminado: desactivado.
Finalizar compra
El cliente elige el método de pago (por defecto Card payment (TrustPay)) y realiza el pedido. En modo de prueba, la finalización de compra muestra Test mode: no real payment will be taken. debajo de la descripción.
Los pagos con tarjeta necesitan la dirección de facturación. Si falta la calle, la ciudad, el código postal o el país, el cliente ve Please enter your billing address (street, city, postcode and country) — it is required for card payments.
El plugin crea una solicitud de pago con tarjeta en finby por el total del pedido en la moneda del pedido. El nombre, la dirección y el correo electrónico del cliente se envían para 3-D Secure, y el ID del pedido se envía como referencia. El cliente es redirigido a la página de pago de finby y paga allí con tarjeta. La página se abre en el idioma de tu tienda cuando finby lo admite; si no, en inglés. Una nota en el pedido muestra la solicitud de pago, el importe y el proyecto (de prueba o de producción).
Después de pagar, el cliente vuelve a la página de pedido recibido de tu tienda y el carrito se vacía. El pedido solo se marca como pagado cuando finby lo confirma con la notificación firmada. El regreso en sí nunca cambia el estado del pago.
Si el cliente cancela en la página de pago, o si esta devuelve un error, el cliente vuelve a la página Pay for order con el mensaje The card payment was cancelled. You can try again or choose another payment method. o The card payment was not completed. Please try again or choose another payment method. Se añade una nota al pedido. El cliente puede volver a pagar desde esa página.
Si finby no puede iniciar el pago, el cliente ve We could not start the card payment. Please try again in a moment or choose another payment method. El motivo técnico se escribe en el registro.
Monedas: EUR, CZK, HUF, GBP, PLN, NOK, SEK, DKK, BGN, RON, CHF y USD. Los importes en HUF se envían sin decimales. En la página Pay for order se comprueba la moneda del pedido.
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 WooCommerce High-Performance Order Storage (HPOS). El plugin incluye traducciones al inglés, eslovaco y checo.
El plugin solo acepta pagos con tarjeta, como compra en un solo paso en la página de finby. No tiene transferencias bancarias ni otros métodos de pago de finby, ni botones de Apple Pay o Google Pay, ni tarjetas guardadas, ni suscripciones o pagos recurrentes, ni autorización y captura por separado, ni consulta del estado.
Pedidos y reembolsos
Estados del pedido
Pending payment: el cliente fue enviado a finby y aún no ha pagado, o la notificación todavía no ha llegado.
Processing or Completed: finby confirmó el pago, y el importe y la moneda coinciden con la solicitud de pago y con el total del pedido. El estado sigue a Order status after payment. La nota del pedido muestra el importe, la solicitud de pago y el proyecto. El ID de transacción es el ID de la solicitud de pago de finby.
On hold: se establece en tres casos. El pago sigue pendiente en finby y el pedido espera el resultado final. El pago solo fue autorizado, no capturado: captúralo o anúlalo en el Merchant Portal de finby y después actualiza el pedido. O bien el importe o la moneda pagados no coinciden con la solicitud de pago o con el total del pedido, por ejemplo porque el pedido se editó después de enviar al cliente a la página de pago: revisa el pago antes de enviar el pedido. La nota del pedido explica el caso.
Failed: finby rechazó el último pago del pedido. La nota muestra el motivo cuando finby lo envía. El cliente puede volver a pagar desde Pay for order.
Los pedidos cancelados o reembolsados nunca se reabren con un pago tardío. Una nota te pide restablecer el pedido o reembolsar el pago en el Merchant Portal. Si llega un segundo pago para un pedido que ya está pagado, el pedido no cambia y una nota te pide reembolsar el duplicado en el Merchant Portal. Los contracargos y las disputas notificados por finby se añaden como notas.
Reembolsos
Abre el pedido, haz clic en Refund, introduce el importe y haz clic en Refund via Card payment (TrustPay) (el botón muestra tu Title). Se admiten reembolsos totales y parciales. El reembolso se envía al proyecto con el que se pagó el pedido (de prueba o de producción), aunque hayas cambiado de modo desde entonces, así que el ID de proyecto y la clave secreta de ese modo deben estar configurados. Los reembolsos en HUF deben ser importes enteros.
Un reembolso solo se registra cuando finby lo acepta. En caso contrario, WooCommerce muestra TrustPay refused the refund: con el motivo, y no se crea ningún reembolso. Un reembolso correcto se añade a las notas del pedido.
Los reembolsos hechos en el Merchant Portal de finby no se registran como reembolsos de WooCommerce. Si finby envía una notificación sobre ellos, se añade como nota del pedido y el estado del pedido no cambia.
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 > TrustPay / finby. 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 volver a comprobar el estado, 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 solo dominio. Eliminar la clave de un sitio no libera su plaza de dominio. Libérala en tu cuenta de vibefox.net.
Sin una clave activa, el método de pago no se muestra a los clientes en la finalización de compra. Si un pago se inicia de todos modos, el cliente ve This payment method is not available. Please choose another one. Los gestores de la tienda que han 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
Card payment (TrustPay) no aparece en la finalización de compra: comprueba que la licencia está activa, que Enable / Disable está activado y que el modo actual tiene su ID de proyecto y su clave secreta: Test Project ID y Test Secret key en modo de prueba, Live Project ID y Live Secret key en modo de producción. La moneda de la tienda, o la moneda del pedido en la página Pay for order, debe ser una de las monedas admitidas. La página de configuración muestra un aviso en ambos casos. Los desarrolladores pueden cambiar la lista de monedas con el filtro trustpay_p_supported_currencies.
El pago se realizó, pero el pedido sigue en Pending payment: la notificación no llegó a tu tienda. Comprueba que https://your-site/wc-api/trustpay_payment_callback/ sea accesible desde internet (sin cortafuegos, modo de mantenimiento ni protección con contraseña). finby reintenta la notificación. Revisa WooCommerce > Status > Logs, origen wcp_trustpay_gateway.
El registro muestra Notification rejected: invalid signature or unknown project: la notificación llegó desde un proyecto cuyo ID de proyecto no está en la configuración, o la clave secreta de ese proyecto es incorrecta. La tienda responde Invalid signature y el pedido no cambia. Comprueba el ID de proyecto y la clave secreta del modo con el que se hizo el pago.
El registro muestra Notification ignored: la notificación pertenece a una solicitud de pago que esta tienda no creó para ese pedido, o a un proyecto distinto del que se usó para iniciar el pago. El pedido no cambia.
La notificación recibe la respuesta Busy, retry later: otra notificación estaba actualizando el pedido en ese mismo momento. finby lo reintenta.
El cliente ve We could not start the card payment: abre el registro. Un ID de proyecto o una clave secreta incorrectos dan un mensaje de que finby rechazó las credenciales del proyecto. Comprueba que las credenciales de prueba están en los campos de prueba y las de producción en los campos de producción.
El pago con tarjeta no está disponible temporalmente: el cliente ve este mensaje cuando el modo actual no tiene ID de proyecto ni clave secreta. Introdúcelos y guarda.
El pedido está On hold con una nota de diferencia de importe o moneda: la notificación era auténtica, pero el importe o la moneda pagados no coinciden con la solicitud de pago o con el total del pedido. Revisa el pago en el Merchant Portal antes de enviar el pedido y luego completa el pedido o reembolsa el pago.
El reembolso falla con un mensaje sobre el proyecto: el pedido se pagó con el proyecto de prueba o de producción, y el ID de proyecto o la clave secreta de ese modo no están configurados, o ahora hay otro ID de proyecto guardado. Introduce las credenciales de ese proyecto o reembolsa el pago en el Merchant Portal de finby.
El bloque de licencia muestra un error: sigue el 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 bórralo en la página Plugins. La clave de licencia y el estado de licencia de este plugin, así como los tokens de acceso a la API en caché, siempre se eliminan. La configuración de la pasarela y los registros del plugin (archivos de registro, incluidos los archivos rotados antiguos, y las entradas de registro en la base de datos) solo se eliminan si Delete data on uninstall estaba activado. Si no, se conservan para una reinstalación posterior. Los datos de pedidos se conservan: los pedidos existentes mantienen sus notas de pago, IDs de solicitud de pago e IDs de transacción.
TrustPay y finby son marcas comerciales de sus respectivos propietarios. Este plugin no está afiliado a TrustPay ni a finby, ni cuenta con su respaldo.