VibeFox PayPal for PrestaShop — Ayuda
Requisitos
PrestaShop: 8.0 a 9.x.
PHP: 8.0 o posterior. El módulo se niega a instalarse en versiones anteriores de PHP.
Cuenta de PayPal: una cuenta Business de PayPal con una aplicación REST API en el PayPal Developer Dashboard. Necesitas el Client ID y el Secret de la aplicación. Las aplicaciones de sandbox y de producción tienen credenciales distintas. No se necesita webhook: el módulo confirma cada pago en tu servidor mientras el cliente está en la finalización de compra.
Moneda: una de las monedas que admite PayPal: AUD, BRL, CAD, CHF, CNY, CZK, DKK, EUR, GBP, HKD, HUF, ILS, JPY, MXN, MYR, NOK, NZD, PHP, PLN, SEK, SGD, THB, TWD o USD.
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 pulsa Upload a module. Elige el archivo ZIP del módulo.
2. Cuando termine la subida, pulsa Configure, o busca VibeFox PayPal Gateway más tarde en la lista de módulos y pulsa 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 (ver Clave de licencia).
4. En el PayPal Developer Dashboard, crea una aplicación REST API (sandbox y/o producción) y copia su Client ID y su Secret.
5. Introduce las credenciales del modo que uses, elige Capture o Authorize, activa Enable/Disable y pulsa Save.
6. Haz una prueba con una cuenta de comprador de sandbox de PayPal; después desactiva Sandbox mode e introduce las credenciales de producción.
Al instalarse, el módulo crea tres estados de pedido: PayPal payment authorized, Awaiting PayPal payment y PayPal payment on hold. PrestaShop habilita el 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 PayPal 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 método de pago está activado pero el Client ID o el Secret del modo seleccionado están vacíos, y cuando PayPal no admite la moneda predeterminada de la tienda. En ambos casos, el método de pago se oculta en la finalización de compra. Mientras el modo sandbox está activado, la página muestra Sandbox mode is on: payments go to the PayPal sandbox, no real money is moved. Al guardar los ajustes se borran los tokens de acceso de PayPal en caché, así que las nuevas credenciales se usan de inmediato.
General
Enable/Disable: Enable PayPal Gateway activa o desactiva el método de pago. Por defecto: desactivado.
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 que se guarda en el pedido. Por defecto: PayPal. Obligatorio.
Description: el texto que se muestra debajo del método de pago en la finalización de compra. Por defecto: Pay with your PayPal account or a card via PayPal.
Credenciales de API
Crea una aplicación REST API en el PayPal Developer Dashboard y copia su Client ID y su Secret. La sección tiene enlaces a las aplicaciones de sandbox y a las de producción. Solo se muestran los campos del modo seleccionado; las credenciales de ambos modos se mantienen guardadas.
Sandbox mode: los pagos van al sandbox de PayPal con las credenciales de sandbox; no se mueve dinero real. Por defecto: activado. Desactívalo para aceptar pagos reales. Las capturas, anulaciones y reembolsos usan siempre el entorno en el que se pagó el pedido. Mientras está activado, los clientes ven Sandbox mode: pay with a PayPal sandbox buyer account — no real money is charged. debajo del método de pago.
Sandbox Client ID: el Client ID de tu aplicación REST API de sandbox.
Sandbox Secret: el Secret de tu aplicación REST API de sandbox.
Live Client ID: el Client ID de tu aplicación REST API de producción.
Live Secret: el Secret de tu aplicación REST API de producción.
Los secretos guardados 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 secrets: marca un secreto y pulsa Save para eliminarlo. Un campo vacío mantiene el valor guardado.
Pago
Payment action: qué ocurre cuando el cliente aprueba el pago. Por defecto: Capture.
Avanzado
Debug log: registra las solicitudes a la API en logs/wc_plg_debug.log.php, en la carpeta del módulo. El archivo no se puede abrir desde la web. Los errores y las advertencias se registran siempre, incluso con este interruptor desactivado. Las credenciales, los tokens y los datos del comprador nunca se registran. Por defecto: desactivado.
Log: muestra el tamaño y las entradas más recientes del registro. Pulsa Clear log para vaciarlo.
Delete data on uninstall: si está activado, al desinstalar el módulo se eliminan los ajustes del método de pago, los tokens en caché y el registro. Los datos de pago de los pedidos (IDs de PayPal de los pedidos, reembolsos) y los estados de pedido se conservan siempre. Por defecto: desactivado.
Finalización de compra
En el paso de pago, el cliente elige el método de pago (por defecto PayPal) y el botón de PayPal aparece en lugar del formulario de pago. Al pulsar el botón, tu servidor crea un pedido de PayPal por el total del carrito en la moneda del carrito. El importe siempre se calcula en el servidor, nunca en el navegador. Todavía no existe ningún pedido en este punto.
El cliente aprueba el pago en la ventana de PayPal con una cuenta de PayPal u otra fuente de financiación que ofrezca PayPal. Después, la finalización de compra muestra PayPal payment approved. Completing your order… y crea el pedido. Si todavía no se han aceptado las condiciones del servicio, la finalización de compra muestra PayPal payment approved. Click "Place order" to complete it. Si el cliente pulsa Place order sin aprobar un pago, el mensaje es Please click the PayPal button and approve the payment first.
Después, tu servidor lee el pedido de PayPal y comprueba que está aprobado, que se creó para este carrito, que no lo usa otro carrito y que su importe y su moneda coinciden con los del carrito. Solo entonces se captura (o autoriza) el pago, se crea el pedido y el cliente ve la página estándar de confirmación del pedido.
Si el total del carrito cambió después de la aprobación, no se captura nada. El cliente ve The order total changed after you approved the payment in PayPal. Please click the PayPal button again to approve the new total. Si PayPal rechaza el pago, el cliente vuelve al paso de pago y se le pide que pulse el botón de PayPal y elija otra forma de pago. No se crea ningún pedido. Si el cliente cierra la ventana de PayPal, la finalización de compra muestra You cancelled the PayPal payment.
Si PayPal no responde durante la captura, el cliente ve We could not confirm your PayPal payment yet. Please try again in a moment — you will not be charged twice. La aprobación se conserva, también después de recargar la página, y Place order la vuelve a usar. Si PayPal había completado el intento anterior, se usa ese pago y no se captura una nueva aprobación. Si el pago se cobró pero no se pudo crear el pedido, el cliente ve Your payment was received, but the order could not be completed automatically. Please contact us — do not pay again. El siguiente intento crea el pedido a partir del pago guardado, sin volver a cobrar.
El script de PayPal se carga solo en la página de finalización de compra y en su propio espacio de nombres, así que no entra en conflicto con otro módulo de PayPal de la página. El módulo funciona con los temas Classic y Hummingbird.
El módulo no tiene webhooks de PayPal, mensajes de Pay Later, campos de tarjeta, Venmo, Apple Pay, Google Pay ni Fastlane, ni métodos de pago guardados o suscripciones, ni botones en las páginas de producto o de carrito. Se usan las direcciones introducidas en la finalización de compra de PrestaShop, no una dirección de PayPal.
Pedidos y reembolsos
Estados del pedido
No order yet: el cliente no ha aprobado el pago, o PayPal lo rechazó. Solo existe el carrito.
Payment accepted: la captura se ha completado. El pedido se marca como pagado solo después de que PayPal lo confirme. El pago se registra con el ID de captura de PayPal como ID de transacción, y una nota muestra el importe, el pedido de PayPal y la captura.
PayPal payment authorized: el pago se autorizó y espera la captura (acción de pago Authorize).
Awaiting PayPal payment: la captura está PENDING en PayPal, por ejemplo en revisión del pago.
PayPal payment on hold: el importe o la moneda pagados no coinciden con el pedido, o el pago no se pudo leer de la respuesta de PayPal. La nota lo explica. Cuando PayPal cobró en la moneda del pedido, el importe realmente pagado se registra como pago. Revisa el pedido y procésalo o reembolsa el pago.
Canceled: la autorización se anuló con Void PayPal authorization.
Payment error: una captura pendiente fue rechazada o falló.
Refunded: el pago se reembolsó por completo a través del módulo.
Si llega un segundo pago para un carrito que ya tiene pedido, el pedido no cambia. Una nota te pide que lo compruebes en tu cuenta de PayPal y lo reembolses.
Bloque de pago de PayPal
La página del pedido muestra un bloque PayPal payment con el ID del pedido de PayPal y la intención, el ID de captura (enlazado al pago en tu cuenta de PayPal, sandbox o producción), el ID de autorización, el estado del pago, el importe, los importes pagado y reembolsado, una insignia Sandbox para los pagos de sandbox, el historial de reembolsos y las PayPal notes del pedido. Los botones del bloque requieren el permiso para editar pedidos, pero no el acceso a las páginas de módulos. El resultado de cada acción se muestra en el bloque.
Reembolsos
En el bloque PayPal payment, introduce el importe (se rellena el importe que aún no se ha reembolsado), opcionalmente un motivo, y pulsa Refund via PayPal. Confirma la pregunta Refund this amount through PayPal? This cannot be undone. Se admiten reembolsos totales y parciales. El motivo se envía a PayPal como nota para el comprador. Los reembolsos se hacen en el importe y la moneda que cobró PayPal, así que, tras una discrepancia de importe o moneda, puedes reembolsar hasta lo que el cliente realmente pagó, y no el total del pedido. El reembolso se envía al entorno de PayPal en el que se hizo el pago (sandbox o producción), así que las credenciales de ese entorno deben estar configuradas. Si PayPal no acepta el reembolso, el bloque muestra el error y no se registra ningún reembolso. Un reembolso correcto se añade al historial de reembolsos y a las notas con el ID y el estado del reembolso de PayPal; un reembolso PENDING lo completa PayPal más tarde. Un reembolso total pone el pedido en Refunded. Un reembolso parcial no cambia el estado.
Un pago que solo está autorizado no se puede reembolsar: usa Void PayPal authorization en su lugar. El módulo no crea facturas rectificativas. Los botones estándar de reembolso de PrestaShop en la página del pedido no devuelven dinero a través de PayPal. Los reembolsos, disputas y devoluciones hechos en tu cuenta de PayPal no se sincronizan 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 PayPal Gateway es el primer bloque de Modules > Module Manager > VibeFox PayPal 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 quitar la clave de esta tienda. Debajo están la línea Product: presta-payment-paypal 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 después de liberar un hueco 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 dominio: el dominio de la tienda principal, también en una configuración multitienda. Quitar la clave de la tienda no libera su hueco de dominio. Libéralo en tu cuenta de vibefox.net.
Sin una clave activa, PayPal no se muestra a los clientes en la finalización de compra. Si se inicia un pago de todos modos, la tienda se niega a crear el pedido de PayPal y el cliente ve An error occurred during PayPal checkout. Please try again. La tienda 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. Aparece un recordatorio en Modules > Module Manager, en la pestaña Alerts. Los pedidos existentes no se ven afectados: los reembolsos y las acciones del bloque de PayPal siguen funcionando.
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 después de introducir la clave, y después una vez por semana. No se necesita ninguna tarea cron. Desinstalar o restablecer el módulo siempre elimina la clave de licencia y el estado de la licencia.
Solución de problemas
PayPal does not appear at checkout: comprueba que la licencia está activa, que Enable/Disable está activado, que el Client ID y el Secret del modo seleccionado están rellenados, que la moneda del carrito es compatible con PayPal y que el total del carrito es superior a cero. La página de ajustes muestra un aviso cuando las credenciales o la moneda son el problema. 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. Una extensión del navegador que bloquee www.paypal.com también oculta el botón.
The payment went through, but no order was created: el módulo no tiene webhook, así que el pago se confirma solo durante la finalización de compra. Esto ocurre cuando PayPal no respondió durante la captura o cuando no se pudo crear el pedido. Activa Debug log y revisa el campo Log, comprueba el pago en tu cuenta de PayPal, o deja que el cliente lo vuelva a intentar: un reintento nunca cobra dos veces y crea el pedido a partir del pago guardado.
PayPal could not be loaded: el script de PayPal no se cargó en el navegador, por ejemplo por un bloqueador o un problema de red.
PayPal is not available right now: las credenciales son incorrectas o pertenecen al otro modo. Copia de nuevo el Client ID y el Secret de la aplicación correcta.
Your PayPal approval could not be matched to this checkout: el pedido de PayPal no se creó para este carrito, por ejemplo tras caducar la sesión. El cliente vuelve a pulsar el botón de PayPal.
This payment is already being processed: el mismo carrito se envió dos veces al mismo tiempo. El cliente espera un momento y revisa el correo electrónico antes de volver a intentarlo.
The order is on hold after payment: lee las notas del bloque PayPal payment. El pago fue autorizado (captúralo con Capture PayPal payment), la captura está PENDING en PayPal (usa Check PayPal payment status más tarde), o el importe o la moneda pagados no coincidieron con el pedido (procesa el pedido o reembolsa lo que se pagó).
Capture of an authorization fails: la autorización puede tener más de 29 días o estar ya anulada. El bloque y las notas muestran el error de PayPal.
Refund fails: el pedido no tiene una captura de PayPal (solo una autorización), el importe supera lo que queda por reembolsar, o faltan las credenciales del entorno en el que se hizo el pago. El bloque indica cuál es el caso.
Desinstalación
Ve a Modules > Module Manager, abre el menú junto a VibeFox PayPal 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 del método de pago, los tokens de acceso de PayPal en caché y el registro. Si está desactivado, todos los ajustes se conservan para una reinstalación posterior. Las transacciones y los reembolsos de PayPal y los estados de pedido PayPal payment authorized, Awaiting PayPal payment y PayPal payment on hold se conservan siempre, así que los pedidos pagados antes se pueden reembolsar después de reinstalar. Los pedidos existentes conservan sus notas de pago y sus IDs de transacción.
PayPal es una marca comercial de su respectivo titular. Este módulo no está afiliado ni respaldado por PayPal.