VibeFox TrustPay 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.
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) aparte, con su propio ID de proyecto y clave secreta. No se necesitan otras claves: la clave secreta sirve 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 tienda desde internet. Un cortafuegos, un inicio de sesión de mantenimiento o la autenticación HTTP delante de la tienda bloquean las notificaciones de pago.
Clave de licencia de VibeFox: se compra en vibefox.net. Una clave funciona en un 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 TrustPay Gateway más tarde en la lista de módulos y haz clic en Configure.
3. Introduce tu clave de licencia de VibeFox en el campo License key del bloque de licencia de la parte superior de la página Configure y haz clic en Activate (consulta Clave de licencia).
4. Introduce el ID de proyecto y la clave secreta de tu proyecto de prueba y, para los pagos reales, de tu proyecto de producción (consulta Configuración).
5. Activa Enable / Disable y haz clic en Save. Haz un pago de prueba con Test mode activado y luego desactiva Test mode para cobrar pagos reales.
Al instalarse, el módulo crea dos estados de pedido, Awaiting TrustPay payment y TrustPay payment on hold. PrestaShop vincula un módulo de pago nuevo a los países activos en el momento de la instalación. Para los países que añadas más tarde, marca el módulo en Payment > Preferences. Allí también puedes limitar el módulo por moneda y grupo de clientes.
Configuración
Todos los ajustes están en la página del módulo: Modules > Module Manager > VibeFox TrustPay 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 si el módulo está activado pero el ID de proyecto o la clave secreta del modo actual están vacíos, y si la moneda predeterminada de la tienda no es compatible. En ambos casos, el método de pago se oculta en la finalización de compra.
TrustPay / finby
Enable / Disable: Enable TrustPay / finby card payments activa o desactiva el método de pago. Por defecto: off.
Title: el nombre del método de pago que ven los clientes en la finalización de compra. También es el nombre del método de pago guardado en el pedido. Por defecto: Card payment (TrustPay). Obligatorio.
Description: el texto que se muestra debajo del método de pago en la finalización de compra. Por defecto: Pay securely by card on the TrustPay / finby payment page.
Credenciales de API
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) aparte, con su propio ID de proyecto y clave secreta. No se cobra dinero real allí.
Test mode: usa el proyecto de prueba (no hay pagos reales). Los nuevos pagos y reembolsos usan las credenciales de prueba. Los reembolsos de un pedido siempre se hacen en el proyecto con el que se pagó el pedido. Por defecto: on. Mientras esté activado, los clientes ven Test mode: no real payment will be taken. debajo del método de pago.
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.
Un ID de proyecto debe contener solo dígitos. Si guardas otro valor, la página muestra must contain digits only — the previous value was kept. y los demás campos se guardan. Las claves secretas se guardan exactamente como las introduces; solo se eliminan los espacios al principio y al final. Las claves secretas guardadas no vuelven a mostrarse nunca. El campo queda vacío y muestra Saved — leave empty to keep it. Escribe un nuevo valor solo si quieres cambiarlo. Al guardar los ajustes también se eliminan los tokens de acceso a la API en caché, para que las nuevas credenciales se usen de inmediato.
Clear saved secrets: marca una clave secreta y haz clic en Save para eliminarla. Un campo vacío mantiene el valor guardado.
Notificaciones de pago
El pedido se marca como pagado solo cuando finby lo confirma con una notificación firmada. El módulo envía la URL de notificación con cada pago automáticamente, así que no tienes que configurarla. La sección muestra la URL bajo Notification URL. Con URL amigables tiene este aspecto: https://your-shop/module/wcp_trustpay_gateway/callback, posiblemente con un código de idioma. También puedes introducirla como URL de notificación de tus proyectos en el Merchant Portal. Las notificaciones sin una firma válida se rechazan.
El módulo no consulta por sí mismo a finby el estado del pago. Si una notificación no puede llegar a tu tienda, no se crea ningún pedido hasta que finby la entregue. finby reintenta las notificaciones.
Avanzado
Order status after payment: el estado del pedido que se asigna tras un pago correcto. El estado se asigna en un solo paso, así que el cliente recibe un único correo electrónico.
Debug logging: añade las peticiones a la API y las notificaciones a logs/trustpay_p_debug.log.php en la carpeta del módulo. El archivo no se puede abrir desde la web. Los errores siempre se registran, incluso cuando esta opción está desactivada. El registro no contiene claves, tokens, datos de tarjetas ni datos de clientes. 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 del módulo y el registro. Los datos de los pedidos se conservan: pedidos, registros de pagos de TrustPay y reembolsos, y los estados de pedido. Por defecto: off.
Finalización de compra
En el paso de pago, el cliente elige el método de pago (por defecto Card payment (TrustPay)) y confirma el pedido. El método de pago solo se ofrece en las monedas compatibles: EUR, CZK, HUF, GBP, PLN, NOK, SEK, DKK, BGN, RON, CHF y USD. Los importes en HUF se envían sin decimales.
Los pagos con tarjeta necesitan una direcció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 módulo crea en finby una solicitud de pago con tarjeta por el total del carrito en la moneda del carrito. El nombre, la dirección y el correo electrónico del cliente se envían para 3-D Secure, y el número de carrito se envía como referencia. Todavía no existe ningún pedido en este punto. El cliente es redirigido a la página de pago de finby y paga con tarjeta allí. La página se abre en el idioma del carrito cuando finby lo admite; si no, en inglés.
Tras pagar, el cliente vuelve a tu tienda. El pedido se marca como pagado solo cuando finby lo confirma con la notificación firmada. El regreso en sí nunca cambia el estado del pago. Si la notificación ya ha llegado, el cliente ve la página estándar de confirmación del pedido. Si no, aparece una página de Payment confirmation que indica que finby está confirmando el pago con tarjeta y que el pedido se creará en cuanto se confirme. Tiene un botón Check again y un botón Back to checkout. Mientras el pedido esté en Awaiting TrustPay payment o TrustPay payment on hold, la página de confirmación muestra Your card payment is being confirmed by TrustPay / finby. You will receive an e-mail as soon as it is confirmed — there is no need to pay again. Si finby rechazó el pago o el pedido sin pagar se canceló, muestra Your card payment was not completed. Please contact us about this order.
Si el cliente cancela en la página de pago, vuelve a la finalización de compra con The card payment was cancelled. You can try again or choose another payment method. Si la página de pago devuelve un error, o finby ya ha rechazado el pago, el mensaje es The card payment was not completed. Please try again or choose another payment method. El carrito se conserva y el cliente puede volver a pagar.
Si finby no puede iniciar el pago, el cliente se queda en la finalización de compra con 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.
La notificación funciona mientras la tienda está en modo de mantenimiento y no se ve bloqueada por la restricción de países de tu tienda.
El módulo solo acepta pagos con tarjeta, como compra en un solo paso en la página de finby. No ofrece transferencias bancarias ni otros métodos de pago de finby, ni botones de Apple Pay o Google Pay en tu sitio, 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
No order yet: el cliente fue enviado a finby y no ha pagado, o la notificación todavía no ha llegado. Solo existe el carrito.
Payment accepted or Delivered: finby confirmó el pago, y el importe y la moneda coinciden con la solicitud de pago y el total del carrito. El estado sigue a Order status after payment. El pago se registra con el ID de la solicitud de pago de finby como ID de transacción, y una nota muestra el importe, la solicitud de pago y el proyecto (prueba o producción).
Awaiting TrustPay payment: finby indicó que el último pago está pendiente. El pedido pasa al estado pagado cuando finby confirma el pago.
TrustPay payment on hold: se asigna en dos casos. El pago solo fue autorizado, no capturado: captúralo o cancélalo en el Merchant Portal de finby y luego actualiza el pedido. O bien el importe o la moneda pagados no coinciden con la solicitud de pago o con el total del carrito, por ejemplo porque el carrito se modificó después de que el cliente fuera enviado a la página de pago: comprueba el pago antes de enviar el pedido. La nota explica el caso.
Payment error: finby rechazó el último pago de un pedido que estaba en espera. La nota muestra el motivo cuando finby lo envía. Un pago confirmado posteriormente sigue pasando el pedido al estado pagado.
Refunded: el pago fue reembolsado por completo a través del módulo.
Los pedidos cancelados o reembolsados nunca se reabren por un pago tardío. Una nota te pide que reactives el pedido o que reembolses el pago en el Merchant Portal. Si llega un segundo pago de un pedido que ya está pagado, el pedido no se modifica y una nota te pide que reembolses el duplicado en el Merchant Portal. Los contracargos y las disputas informados por finby se añaden como notas.
Bloque de pago TrustPay / finby
La página del pedido muestra un bloque TrustPay / finby payment con el ID de la solicitud de pago, el ID del pago de finby, el proyecto, el estado del pago, los importes solicitado y pagado, el importe reembolsado, una insignia Test project para los pagos de prueba, el historial de reembolsos y las TrustPay notes del pedido.
Reembolsos
En el bloque TrustPay / finby payment, introduce el importe (el importe aún no reembolsado aparece rellenado), opcionalmente un motivo, y haz clic en Refund via TrustPay. Confirma la pregunta Refund this amount through TrustPay? This cannot be undone. Se admiten reembolsos totales y parciales. Necesitas el derecho a editar pedidos; no es necesario el acceso a las páginas de Módulos. Los reembolsos se hacen por el importe y en la moneda que finby informó para el pago, así que, tras una diferencia de importes, puedes reembolsar hasta lo que el cliente realmente pagó, no el total del pedido. Los reembolsos en HUF deben ser importes enteros.
El reembolso se envía al proyecto con el que se pagó el pedido (prueba o producción), aunque hayas cambiado de modo desde entonces. Ese proyecto debe tener su ID de proyecto y su clave secreta configurados, y su ID de proyecto no debe haber cambiado. Un reembolso solo se registra cuando finby lo acepta. Si no, el bloque muestra TrustPay refused the refund: con el motivo, y no se registra ningún reembolso. Un reembolso correcto se añade al historial de reembolsos y a las notas. Un reembolso total pone el pedido en Refunded. Un reembolso parcial no cambia el estado.
El módulo no crea facturas rectificativas. Los botones de reembolso estándar de PrestaShop en la página del pedido no devuelven dinero a través de finby. Los reembolsos hechos en el Merchant Portal de finby no se registran como reembolsos. Si finby envía una notificación sobre ellos, se añade como nota y el estado del pedido no cambia.
Clave de licencia
El módulo funciona con una clave de licencia de VibeFox de vibefox.net. El bloque de licencia License — VibeFox TrustPay Gateway es el primer bloque de Modules > Module Manager > VibeFox TrustPay Gateway > Configure, por 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-trustpay 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 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 tras liberar un hueco de dominio en tu cuenta, haz clic en Check now. Si no se puede acceder al servidor de licencias, el módulo sigue funcionando con el último estado conocido.
Una clave funciona en un dominio: el dominio de la tienda principal, también en una configuración multitienda. Quitar la clave de la tienda no libera su dominio. Libera el hueco en tu cuenta de vibefox.net.
Sin una clave activa, el pago con tarjeta 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 queda oculto para ti: puedes configurar el módulo antes de comprar una clave, pero no probarlo en la finalización de compra. Aparece un recordatorio en Modules > Module Manager, en la pestaña Alerts. Los pedidos existentes no se ven afectados: los pagos ya iniciados siguen confirmándose mediante la notificación de TrustPay y 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 a la 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
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 del carrito debe ser una de las monedas compatibles. La página de ajustes muestra una advertencia cuando faltan las credenciales 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ó a tu tienda. Comprueba que la URL que aparece bajo Notification URL es accesible desde internet (sin cortafuegos, inicio de sesión de mantenimiento ni autenticación HTTP). finby reintenta la notificación, y el pedido se crea cuando llega. Activa Debug logging y revisa el campo Log de la página del módulo.
El registro muestra Notification rejected: invalid signature or unknown project: la notificación procede de un proyecto cuyo ID de proyecto no está en los ajustes, o la clave secreta de ese proyecto es incorrecta. La tienda responde Invalid signature y no se cambia nada. Comprueba el ID de proyecto y la clave secreta del modo en 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 carrito, o a otro proyecto o modo distinto del que se usó al iniciar el pago. No se cambia nada.
La notificación recibe la respuesta Busy, retry later o Temporary error: el carrito estaba siendo actualizado por otra notificación en ese mismo momento, o no se pudo crear el pedido (por ejemplo, porque el módulo está desactivado). finby lo reintenta. El registro muestra el motivo.
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.
Card payment is temporarily unavailable: el cliente ve esto cuando el modo actual no tiene ID de proyecto o clave secreta. Introdúcelos y guarda.
El pedido está en TrustPay payment on hold: lee las notas del bloque TrustPay / finby payment (consulta Estados del pedido). Comprueba el pago en el Merchant Portal antes de enviar el pedido y, después, completa el pedido o reembolsa el pago.
Refund fails with a message about the project: 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 guardado otro ID de proyecto. Introduce las credenciales de ese proyecto o reembolsa el pago en el Merchant Portal de finby.
Invalid refund amount: at most … can be refunded: el importe es mayor que el importe pagado menos los reembolsos ya realizados a través del módulo.
Desinstalación
Ve a Modules > Module Manager, abre el menú junto a VibeFox TrustPay Gateway y elige Uninstall. La clave de licencia y el estado de la licencia de este módulo siempre se eliminan. Los tokens de acceso a la API en caché siempre se eliminan. Si Delete data on uninstall está activado, se eliminan los ajustes del módulo y el registro. Si está desactivado, todos los ajustes se conservan para una reinstalación posterior. Los registros de pagos de TrustPay y los reembolsos, y los estados de pedido Awaiting TrustPay payment y TrustPay payment on hold, siempre se conservan, así que los pedidos pagados antes se pueden reembolsar tras reinstalar. Los pedidos existentes conservan sus notas de pago y sus ID de transacción.
TrustPay y finby son marcas comerciales de sus respectivos titulares. Este módulo no está afiliado a TrustPay ni a finby, ni cuenta con su respaldo.