VibeFox PayPal for OpenCart — Ayuda

Requisitos

OpenCart: 3.0.x (probado en 3.0.5.0) o 4.0.2 y posteriores (probado en 4.1.0.3).

PHP: 8.0 o posterior.

Cuenta de PayPal: una cuenta PayPal Business con una aplicación de API REST en el PayPal Developer Dashboard. Necesitas el Client ID y el Secret de la aplicación. Las aplicaciones de sandbox y de modo real tienen credenciales distintas. No hace falta ningún webhook: la extensión confirma cada pago en tu servidor mientras el cliente está en la compra.

Moneda: una de las monedas admitidas por 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

La descarga es un único archivo zip con los paquetes para ambas versiones de OpenCart. Descomprímelo en tu ordenador. Contiene README.txt, el paquete de OpenCart 3 wcp_paypal_gateway-oc3-(version).ocmod.zip y el paquete de OpenCart 4 wcp_paypal_gateway.ocmod.zip. Instala solo el paquete de tu versión de OpenCart. La clave de licencia es la misma para ambas versiones.

OpenCart 3

1. En el panel de administración ve a Extensions > Installer, haz clic en Upload y elige el archivo wcp_paypal_gateway-oc3-(version).ocmod.zip. La extensión no tiene modificaciones OCMOD, así que Extensions > Modifications no necesita actualizarse. En lugar del instalador, puedes copiar el contenido de la carpeta upload de este paquete en la carpeta raíz de tu tienda.

2. Ve a Extensions > Extensions y elige el tipo Payments. Busca VibeFox PayPal Gateway y haz clic en Install (el botón verde +). Tu usuario de administración necesita el derecho a modificar la lista de extensiones de pago.

3. Haz clic en Edit (el botón del lápiz) para abrir la página de ajustes. Pega tu clave de licencia de VibeFox en License key, en el bloque de licencia de la parte superior de la página, y haz clic en Activate (consulta License key).

4. En el PayPal Developer Dashboard crea una aplicación de API REST (sandbox y/o real) y copia su Client ID y su Secret en la sección API credentials.

5. Elige Capture o Authorize, activa Enable/Disable y haz clic en Save.

6. Prueba con una cuenta compradora de sandbox de PayPal, luego desactiva Sandbox mode e introduce las credenciales reales.

OpenCart 4

1. En el panel de administración ve a Extensions > Installer, haz clic en Upload y elige el archivo wcp_paypal_gateway.ocmod.zip. No cambies el nombre del archivo: OpenCart 4 toma el código de la extensión del nombre del archivo, y un paquete renombrado no funciona.

2. El paquete aparece en la lista de extensiones instaladas en la misma página. Haz clic en Install (el botón verde +) junto a él.

3. Ve a Extensions > Extensions y elige el tipo Payments. Busca VibeFox PayPal Gateway, haz clic en Install (el botón verde +) y luego en Edit (el botón del lápiz).

4. Introduce la clave de licencia, las credenciales de PayPal y la acción de pago siguiendo los pasos 3 a 6 de OpenCart 3. La página de ajustes y sus campos son los mismos en ambas versiones. La extensión no toca la extensión de PayPal que viene con OpenCart 4: ambas pueden instalarse en la misma tienda.

Una instalación nueva empieza con el método de pago desactivado y el modo sandbox activado.

Configuración

Todos los ajustes están en la página de la extensión: Extensions > Extensions > Payments > VibeFox PayPal Gateway > Edit. Las secciones aparecen a la izquierda; el botón Save situado debajo de la lista guarda toda la página. Encima de los ajustes, 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 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. Sin el derecho a modificar la extensión, la página muestra los ajustes pero no permite guardarlos.

Al guardar, Title no puede estar vacío (hasta 128 caracteres), Sort Order debe ser un número entero (se permiten negativos), Total debe ser un número igual o mayor que 0, y los estados de pedido deben existir. Si alguna comprobación falla, no se guarda nada y la página enumera los errores. Al guardar los ajustes se descartan los tokens de acceso de PayPal almacenados en caché, para que se usen de inmediato las nuevas credenciales.

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 ve el cliente en la compra. También es el nombre del método de pago guardado en el pedido. Por defecto: PayPal. Obligatorio, hasta 128 caracteres.

Description: el texto que ve el cliente en el paso Confirm Order, encima del botón de PayPal. Por defecto: Pay with your PayPal account or a card via PayPal.

Sort Order: la posición de PayPal entre los métodos de pago de la compra. Déjalo vacío o introduce un número entero.

Geo Zone: ofrece PayPal solo para las direcciones de pago de la zona geográfica seleccionada. Por defecto: All zones. Las zonas geográficas se configuran en System > Localisation > Geo Zones.

Total: el total de la compra, en la moneda predeterminada de la tienda, que debe alcanzar un pedido para que se ofrezca PayPal. Déjalo vacío para ofrecer PayPal con cualquier total.

API credentials

Crea una aplicación de API REST 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 aplicaciones reales. 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 siempre usan el entorno en el que se pagó el pedido. Mientras esté activado, el cliente ve Sandbox mode: pay with a PayPal sandbox buyer account — no real money is charged. en el paso Confirm Order.

Sandbox Client ID: el Client ID de tu aplicación de API REST de sandbox.

Sandbox Secret: el Secret de tu aplicación de API REST de sandbox.

Live Client ID: el Client ID de tu aplicación de API REST real.

Live Secret: el Secret de tu aplicación de API REST real.

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 para cambiarlo. Para eliminar un secreto guardado, marca Clear the saved secret on save debajo del campo y haz clic en Save.

Payment

Payment action: lo que ocurre cuando el cliente aprueba el pago. Por defecto: Capture.

Orders

OpenCart crea el pedido en el paso Confirm Order sin estado (un pedido sin estado). El pedido solo recibe un estado después de que PayPal haya respondido a la captura o autorización en tu servidor. Un pago rechazado deja el pedido sin estado, y el cliente permanece en el paso Confirm Order. Cada campo de abajo enumera tus estados de pedido de OpenCart.

Order Status After Payment: la captura se ha completado, también cuando se captura una autorización o se completa una captura pendiente en la pestaña del pedido. Por defecto: Processing.

Awaiting Payment Status: la captura está PENDING en PayPal (revisión del pago, fondos aún no liquidados). Por defecto: Pending.

Authorized Status: acción de pago Authorize: los fondos están reservados, pero aún no pagados. Por defecto: Pending.

On Hold (Review) Status: PayPal cobró dinero, pero no se pudo leer el pago o el importe o la moneda no coinciden con el pedido. Una nota explica qué hay que revisar. Por defecto: Pending, porque OpenCart no tiene un estado On hold. Puedes crear tus propios estados en System > Localisation > Order Statuses y seleccionarlos aquí.

Voided Status: la autorización se anuló en la pestaña del pedido y los fondos reservados se liberaron. Por defecto: Canceled.

Refunded Status: el pago está reembolsado por completo. Los reembolsos parciales solo añaden una nota. Por defecto: Refunded.

Failed Status: PayPal rechazó una captura pendiente. Por defecto: Failed.

Advanced

Debug log: registra las solicitudes a la API en wc_plg_debug.log.php, en la carpeta de registros de OpenCart (storage/logs). El archivo no se puede abrir desde la web, y al llegar a 5 MB se mueve a wc_plg_debug.old.log.php. Los errores y las advertencias siempre se registran, incluso con este interruptor desactivado. Las credenciales, los tokens y los datos de los compradores nunca se registran. Por defecto: desactivado.

Log: muestra el tamaño y las entradas más recientes del registro. Haz clic en Clear log para vaciarlo.

Delete data on uninstall: si está activado, al desinstalar la extensión se eliminan los ajustes de la pasarela y el registro. Los tokens en caché siempre se eliminan. Los datos de pago de los pedidos (los ID de PayPal de los pedidos y los reembolsos) siempre se conservan, así que los pedidos pagados antes pueden seguir reembolsándose, capturándose o anulándose tras reinstalar. Por defecto: desactivado.

Import / Export

Export: Download JSON guarda los ajustes como archivo JSON. Los secretos no se exportan.

Import: pega el JSON exportado anteriormente y haz clic en Import para restaurar los ajustes. Los secretos guardados se conservan.

Compra

En el paso Payment Method el cliente elige el método de pago (por defecto, PayPal). OpenCart crea el pedido en el paso Confirm Order, todavía sin estado. Allí el cliente ve tu descripción y el botón de PayPal. Al hacer clic en el botón, se crea en tu servidor un pedido de PayPal por el total del pedido en la moneda del pedido. El importe siempre se calcula en el servidor, nunca en el navegador. En OpenCart 4 el cliente elige el método de pago con el botón Choose del bloque del método de pago, en la ventana Payment method options; la descripción y el botón de PayPal aparecen entonces en el bloque de confirmación al final de la página de compra, junto al botón Confirm Order.

El cliente aprueba el pago en la ventana de PayPal con una cuenta de PayPal u otra fuente de financiación que ofrezca PayPal. La compra muestra entonces PayPal payment approved. Completing your order… y completa el pedido por sí sola. Si el cliente hace clic en Confirm 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ó en esta compra, que no pertenece a otro pedido y que su importe y su moneda coinciden con el pedido. Solo entonces se captura (o autoriza) el pago. El pedido se marca como pagado solo después de que PayPal lo confirme. Después recibe su estado de la forma estándar de OpenCart, con los correos habituales del pedido y la actualización del stock, el carrito se vacía y el cliente ve la página de éxito del pedido de OpenCart.

Si el total del pedido 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 pedido queda sin estado y se pide al cliente que haga clic en el botón de PayPal o elija otra forma de pago. Si el cliente cierra la ventana de PayPal, la 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 para este carrito, también después de recargar la página: la compra muestra PayPal payment approved. Click "Confirm Order" to complete it. y Confirm Order la usa de nuevo. 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 asignar el estado del 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 asigna el estado a partir del pago guardado sin volver a cobrar.

OpenCart 3 crea un pedido nuevo cada vez que se muestra el paso Confirm Order, y OpenCart 4 actualiza el pedido de la compra, así que el pago pertenece al carrito: una aprobación hecha para un pedido anterior del mismo carrito paga el pedido actual si el total es el mismo, y un carrito ya pagado nunca se vuelve a cobrar. Un cambio en el carrito, incluida una nueva cantidad, cuenta como un carrito nuevo que necesita su propio pago. El script de PayPal se carga desde PayPal solo en el paso Confirm Order y en su propio espacio de nombres, así que no entra en conflicto con otra extensión de PayPal de la página.

OpenCart 4 mantiene el pedido de la compra hasta que se muestra la página de éxito. Si ese pedido se cerró entretanto (por ejemplo, lo cancelaste o se rechazó la captura pendiente), o ya se pagó por un carrito anterior, el cliente ve Your previous order of this checkout is already closed or paid. Please refresh the page and confirm the order again — a new order will be created. Después de recargar la página, el siguiente pago paga un pedido nuevo. Un pedido pagado nunca se muestra como pagado para un carrito distinto.

La extensión no tiene webhooks de PayPal, ni mensajes de Pay Later, ni campos de tarjeta, ni Venmo, Apple Pay, Google Pay o 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 compra de OpenCart, no una dirección de PayPal.

Pedidos y reembolsos

Estados de pedido

Sin estado (pedido incompleto): el cliente no ha aprobado el pago, o PayPal lo ha rechazado. En Sales > Orders estos pedidos solo se muestran con el filtro Order Status en Missing Orders.

Estado del pedido tras el pago (por defecto Processing): la captura se ha completado. Una nota muestra el importe, el pedido de PayPal y la captura.

Estado autorizado (por defecto Pending): el pago se autorizó y espera la captura (acción de pago Authorize).

Pago pendiente en PayPal (por defecto Pending): la captura está PENDING en PayPal, por ejemplo en revisión de pago.

Estado en revisión (por defecto Pending): el importe o la moneda pagados difieren del pedido, o no se pudo leer el pago de la respuesta de PayPal. La nota lo explica. Revisa el pedido y completa el envío o reembolsa lo pagado.

Estado anulado (por defecto Canceled): la autorización se anuló con Void PayPal authorization.

Estado fallido (por defecto Failed): una captura pendiente fue rechazada o falló.

Estado reembolsado (por defecto Refunded): el pago se reembolsó por completo mediante la extensión.

Si llega un segundo pago para un carrito que ya está pagado, el pedido pagado no cambia. Una nota te pide que lo compruebes en tu cuenta de PayPal y lo reembolses.

Las notas son entradas del History del pedido que el cliente no ve. Los cambios de estado hechos en la pestaña del pedido (captura, anulación, comprobación de estado, reembolso) se escriben directamente, sin notificar al cliente y sin cambiar el stock.

Pestaña VibeFox PayPal Gateway

En Sales > Orders abre un pedido pagado con PayPal. En la parte inferior de la página del pedido, junto a History y Additional, la pestaña VibeFox PayPal Gateway muestra el PayPal order ID y la intención, con una etiqueta Sandbox en los pagos de sandbox, el Capture ID (enlazado al pago en tu cuenta de PayPal, sandbox o real), el Authorization ID, el Status del pago, el Amount, los importes Paid / refunded, el historial de reembolsos y las PayPal notes del pedido. La pestaña se muestra a los usuarios que tienen acceso a la extensión; sus botones necesitan el derecho a modificar la extensión (se configura en System > Users > User Groups). El resultado de cada acción se muestra en la pestaña.

Refunds

En la pestaña VibeFox PayPal Gateway introduce el importe (se rellena el importe que aún no se ha reembolsado), opcionalmente un Reason (optional, sent to the buyer), y haz clic en 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 de moneda puedes reembolsar hasta lo que el cliente pagó realmente, no el total del pedido. El reembolso se envía al entorno de PayPal en el que se hizo el pago (sandbox o real), así que las credenciales de ese entorno deben estar configuradas. Si PayPal no acepta el reembolso, la pestaña 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 asigna el pedido al Refunded Status. Un reembolso parcial no cambia el estado.

Un pago que solo está autorizado no puede reembolsarse: usa Void PayPal authorization en su lugar. Las devoluciones de productos en Sales > Returns no devuelven dinero a través de PayPal. Los reembolsos, las disputas y las devoluciones de cargo hechos en tu cuenta de PayPal no se sincronizan con OpenCart.

Clave de licencia

La extensión funciona con una clave de licencia de VibeFox de vibefox.net. El bloque de licencia License — VibeFox PayPal Gateway es el primer bloque de Extensions > Extensions > Payments > VibeFox PayPal Gateway > Edit, por encima de los ajustes. Pega 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 están la línea Product: opencart-payment-paypal y el enlace Manage licenses and domains in your account, que abre tu cuenta de vibefox.net. Solo los usuarios administradores con el permiso Modify para la extensión pueden cambiar la clave. Los textos del bloque siguen el idioma del panel de administración (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 una plaza de dominio en tu cuenta, haz clic en Check now. Si no se puede contactar con el servidor de licencias, la extensión sigue funcionando con el último estado conocido.

Una clave funciona en un dominio: la dirección de la tienda de la configuración de OpenCart. Eliminar la clave de la tienda no libera su plaza de dominio. Libérala en tu cuenta de vibefox.net.

Sin una clave activa, PayPal no se muestra a los clientes en la compra. Si aun así se inicia un pago, la tienda rechaza crear el pedido de PayPal y el cliente ve An error occurred during PayPal checkout. Please try again. Un usuario administrador que haya iniciado sesión en el panel de administración en el mismo navegador sigue viendo el método de pago en la tienda, marcado como (unlicensed — visible to admins only), para que puedas configurar y probar la extensión antes de comprar una clave. En OpenCart 4 esta vista previa no está disponible: la tienda no ve el inicio de sesión del administrador, así que sin una clave activa el método de pago se oculta a todos. Después de abrir una vez la página Edit, aparece un recordatorio en el Dashboard del panel de administración. Ciérralo con × para ocultarlo durante 7 días. Los pedidos existentes no se ven afectados: los reembolsos y las acciones de la pestaña del pedido siguen funcionando.

Si la licencia caduca, la extensión sigue funcionando, pero las actualizaciones y el soporte necesitan una renovación. El estado se vuelve a comprobar automáticamente al abrir el Dashboard o la página Edit del panel de administración: 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 hace falta ningún cron job. Desinstalar la extensión elimina siempre la clave de licencia y el estado de la licencia.

Solución de problemas

PayPal no aparece en la compra: 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 pedido sea compatible con PayPal y que el total del pedido sea superior a cero. La página de ajustes muestra una advertencia cuando el problema son las credenciales o la moneda de la tienda. Comprueba también que la dirección de pago esté en la Geo Zone seleccionada y que el pedido alcance el Total definido en los ajustes.

El pago se realizó, pero el pedido sigue sin estado: la extensión no tiene webhook, así que el pago solo se confirma durante la compra. Esto ocurre cuando PayPal no respondió durante la captura o no se pudo asignar el estado del pedido. Activa el Debug log y revisa el campo Log, comprueba el pago en tu cuenta de PayPal, o deja que el cliente lo intente de nuevo: un nuevo intento nunca cobra dos veces y asigna el estado a partir del pago guardado.

No se pudo cargar PayPal: el script de PayPal no se cargó en el navegador, por ejemplo porque una extensión del navegador bloquea www.paypal.com o por un problema de red.

PayPal no está disponible en este momento: las credenciales son incorrectas o pertenecen al otro modo. Copia de nuevo el Client ID y el Secret de la aplicación correcta.

Tu aprobación de PayPal no se pudo asociar a esta compra: el pedido de PayPal no se creó en esta compra, por ejemplo después de que caducara la sesión. El cliente vuelve a hacer clic en el botón de PayPal.

Tu sesión ha caducado. Actualiza la página e inténtalo de nuevo: la página de compra estuvo abierta demasiado tiempo. El cliente recarga la página.

Este pago ya se está procesando: el mismo carrito se envió dos veces en el mismo momento. El cliente espera un momento y revisa el correo electrónico antes de volver a intentarlo.

El pedido está en estado de revisión o pendiente después del pago: lee las notas de la pestaña VibeFox PayPal Gateway. El pago se autorizó (cápturalo 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 coincidían con el pedido (completa el pedido o reembolsa lo pagado).

Falla la captura de una autorización: la autorización puede tener más de 29 días o estar ya anulada. La pestaña y las notas muestran el error de PayPal.

No hay botones en la pestaña: la pestaña indica por qué: tu grupo de usuarios no tiene derecho a modificar la extensión, el pago está reembolsado por completo, o no están configurados el Client ID y el Secret del entorno en el que se hizo el pago.

Falla el reembolso: 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. La pestaña indica cuál es el caso.

Desinstalación

Ve a Extensions > Extensions, elige el tipo Payments y haz clic en Uninstall (el botón rojo −) junto a VibeFox PayPal Gateway. La clave de licencia y el estado de licencia de esta extensión siempre se eliminan. OpenCart siempre elimina los ajustes propios de la extensión: Enable/Disable, Sort Order, Geo Zone, Total y los estados de pedido de la sección Orders, que vuelven a sus valores predeterminados al reinstalar. Los tokens de acceso de PayPal en caché siempre se eliminan. Si Delete data on uninstall está activado, se eliminan los demás ajustes de la pasarela (título, descripción, modo sandbox, credenciales, acción de pago, registro) y el registro. Si está desactivado, se conservan para una reinstalación posterior. Las transacciones y los reembolsos de PayPal siempre se conservan, así que los pedidos pagados antes pueden seguir reembolsándose, capturándose o anulándose tras reinstalar. Los pedidos existentes conservan sus notas de pago.

En OpenCart 4, para eliminar también los archivos de la extensión, ve a Extensions > Installer después de la desinstalación y haz clic en Uninstall (el botón naranja −) junto a VibeFox PayPal Gateway en la lista de extensiones instaladas, y después en Delete (el botón rojo de la papelera) para eliminar el paquete subido.

PayPal es una marca comercial de su titular. Esta extensión no está afiliada ni respaldada por PayPal.