VibeFox Paysera 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.

Proyecto de Paysera: necesitas el ID de proyecto y la contraseña de proyecto (clave de firma) de tu proyecto de Paysera. Los métodos de pago que ve el cliente son los activados en este proyecto. No hay que configurar nada en Paysera para la devolución de llamada: su URL se envía con cada solicitud de pago.

Tienda accesible: los pedidos reciben su estado de la devolución de llamada de Paysera, así que tu tienda debe ser accesible desde internet, sin inicio de sesión, autenticación básica ni cortafuegos que la bloqueen. La devolución de llamada funciona también mientras la tienda está en modo de mantenimiento.

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_paysera_payment-oc3-(version).ocmod.zip y el paquete de OpenCart 4 wcp_paysera_payment.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_paysera_payment-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 Paysera Payment y haz clic en Install (el botón verde +). Tu usuario administrador necesita el permiso para modificar la lista de extensiones de pago.

3. Haz clic en Edit (el botón con el lápiz) para abrir la página de configuración. 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 (ver Clave de licencia).

4. Introduce el Project ID y la Project password de tu cuenta de Paysera (ver Configuración).

5. Opcional: activa Allow test payments en el proyecto de Paysera y Test payments en la extensión para probar el flujo sin cobrar dinero. Desactívalo antes de empezar a vender.

6. Activa Enable/Disable y haz clic en Save.

OpenCart 4

1. En el panel de administración ve a Extensions > Installer, haz clic en Upload y elige el archivo wcp_paysera_payment.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 Paysera Payment, haz clic en Install (el botón verde +) y después en Edit (el botón con el lápiz).

4. Introduce la clave de licencia, el ID y la contraseña del proyecto y los ajustes de prueba como en los pasos 3 a 6 de OpenCart 3. La página de ajustes y sus campos son los mismos en ambas versiones. Solo la URL de devolución de llamada es distinta (ver Proyecto de Paysera).

Una instalación nueva empieza con el método de pago desactivado, los pagos de prueba desactivados y el entorno Production.

Configuración

Todos los ajustes están en la página de la extensión: Extensions > Extensions > Payments > VibeFox Paysera Payment > Edit. Las secciones aparecen a la izquierda; el botón Save debajo de la lista guarda la página completa. Sobre los ajustes, la página muestra Paysera is hidden at checkout until the project ID and the project password are entered. mientras falte uno de los dos, y Test mode is on: customers are not charged. Turn off "Test payments" and select "Production" before accepting real orders. mientras los pagos de prueba o el sandbox estén activados. Sin permiso para modificar la extensión, la página muestra los ajustes pero no permite guardarlos.

Al guardar, Title debe tener de 1 a 128 caracteres, Project ID debe contener solo dígitos, Sort Order debe ser un número entero, 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 muestra los errores.

Paysera

Enable/Disable: Enable Paysera Payment 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 compra. También es el nombre del método de pago guardado en el pedido. Por defecto: Paysera. Obligatorio, hasta 128 caracteres.

Description: el texto que ve el cliente en el paso Confirm Order, encima del botón de confirmación. Por defecto: Pay securely via Paysera.

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

Geo Zone: ofrece Paysera solo para 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 Paysera. Déjalo vacío para ofrecer Paysera con cualquier total.

Proyecto de Paysera

Encuentra el ID de proyecto y la contraseña de proyecto en tu cuenta de Paysera, en Projects and activities, tu proyecto, General project settings. La sección tiene un enlace a la cuenta de Paysera.

Callback URL: la dirección que usa Paysera para confirmar cada pago. En OpenCart 3 tiene este aspecto: https://your-store/index.php?route=extension/payment/wcp_paysera_payment/callback, y en OpenCart 4: https://your-store/index.php?route=extension/wcp_paysera_payment/payment/wcp_paysera_payment.callback. Se construye a partir de la dirección de la tienda de tu instalación de OpenCart. Se envía automáticamente con cada pago, así que no hay que configurar nada en Paysera, pero debe ser accesible desde internet. Los pedidos reciben su estado solo de estas devoluciones de llamada firmadas o cifradas.

Project ID: el ID numérico de tu proyecto de Paysera. Solo se aceptan dígitos: cualquier otro valor da el error Project ID must contain digits only: the numeric ID of your Paysera project. y no se guarda nada.

Project password: la contraseña de proyecto (clave de firma). Firma las solicitudes de pago y verifica las devoluciones de llamada de Paysera. La contraseña guardada nunca se vuelve a mostrar. El campo queda vacío y muestra Saved — leave empty to keep it. Escribe un valor nuevo solo si quieres cambiarlo. Para eliminar la contraseña guardada, marca Clear saved password (tick and save; an empty field keeps the saved value) debajo del campo y haz clic en Save.

Pruebas

Test payments: envía los pagos en modo de prueba, así que no se cobra dinero. Paysera devuelve un pago de prueba correcto sin cobrar al cliente. Activa primero Allow test payments en la configuración del proyecto de Paysera. Mientras esta opción esté activada, los pagos de prueba marcan los pedidos como pagados; cuando esté desactivada, un pago de prueba pone el pedido en espera. Por defecto: desactivado. Mientras esté activada, el cliente ve TEST MODE — no money will be charged. en el paso Confirm Order.

Environment: adonde se envía al cliente. Mantén Production para un proyecto normal de Paysera, también para los pagos de prueba. Por defecto: Production.

Pedidos

OpenCart crea el pedido en el paso Confirm Order sin estado (un pedido perdido). El pedido recibe un estado solo de la devolución de llamada de Paysera. Un pago cancelado o no ejecutado deja el pedido sin estado, y el cliente puede volver a pagar. Cada campo siguiente muestra tus estados de pedido de OpenCart.

Order Status After Payment: el estado que se asigna cuando Paysera confirma el pago con el importe y la moneda esperados. Por defecto: Processing.

Awaiting Payment Status: el banco ha aceptado la orden de pago, pero aún no la ha ejecutado. El pedido se marca como pagado cuando Paysera confirma el pago. Por defecto: Pending.

On Hold Status: un pago de PRUEBA mientras Test payments está desactivado, un importe o una moneda distintos, o un pago posterior a la cancelación del cliente. El pedido no se marca como pagado; una nota explica el motivo. Por defecto: Pending, porque OpenCart no tiene el estado On hold. Puedes crear tu propio estado en System > Localisation > Order Statuses y seleccionarlo aquí.

Cancelled Order Status: la extensión nunca establece este estado; solo lo lee: un pago que llega para un pedido en este estado no reabre el pedido, solo se añade una nota. Por defecto: Canceled.

Avanzado

Debug log: registra los eventos de pago en wc_psr_debug.log.php, en la carpeta de registros de OpenCart (storage/logs). El archivo no se puede abrir desde la web. Los errores y las advertencias siempre se escriben; los demás pasos solo mientras esta opción esté activada. Las contraseñas y los datos del cliente nunca se escriben. Por defecto: desactivado.

Log: muestra el tamaño y las últimas entradas del registro. Haz clic en Clear log para vaciarlo.

Delete data: si está activado, al desinstalar la extensión se eliminan sus ajustes y su registro. Los datos de pedidos (pedidos, registros de pago de Paysera) siempre se conservan. Por defecto: desactivado.

Importar / Exportar

Export: Download JSON guarda los ajustes en un archivo JSON. La contraseña de proyecto no se exporta.

Import: pega un JSON exportado previamente y haz clic en Import para restaurar los ajustes. La contraseña de proyecto guardada se mantiene.

Compra

En el paso Payment Method el cliente elige el método de pago (por defecto, Paysera). En el paso Confirm Order el cliente ve tu descripción y la nota You will be redirected to the Paysera payment window (bank links, cards and other Paysera methods) to complete the payment. OpenCart crea el pedido en este paso, todavía sin estado. 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, y hace clic en Confirm Order al final de la página de compra. Cuando el cliente hace clic en Confirm Order, la extensión crea una solicitud de pago firmada con el número de pedido, el total del pedido en la unidad menor de la moneda del pedido, el nombre, el correo electrónico y la dirección de facturación del cliente, y el idioma de la página de la tienda (lituano, letón, estonio, ruso, alemán, polaco; en otro caso, inglés). El cliente es enviado a la ventana de pago de Paysera y elige allí un banco, una tarjeta u otro método.

Paysera confirma el pago mediante una devolución de llamada de servidor a servidor. El pedido solo se marca como pagado cuando Paysera lo confirma con una devolución de llamada firmada; el regreso del cliente a la tienda nunca paga un pedido. Después el pedido recibe su estado de la forma estándar de OpenCart, con los correos habituales de pedido y la actualización de stock. Cuando el cliente vuelve tras la devolución de llamada, se muestra la página de éxito del pedido de OpenCart. Si el banco ha aceptado la orden de pago pero aún no la ha ejecutado, el pedido recibe el Awaiting Payment Status y la página muestra Paysera is confirming your payment. You will receive an e-mail as soon as it is confirmed — there is no need to pay again. Para un pedido en espera la página muestra Your payment is being reviewed. We will contact you if anything else is needed.

Si el cliente vuelve antes de la devolución de llamada, aparece una página Payment confirmation que explica que el pedido se confirmará en cuanto Paysera confirme el pago, y ofrece Check again y Back to checkout.

Si el cliente cancela en la ventana de Paysera, vuelve a la compra con el mensaje The Paysera payment was cancelled. You can try again or choose another payment method. Si Paysera informa de que el pago no se ejecutó, el mensaje es The payment was not completed. You can try again or choose another payment method. El carrito se conserva en ambos casos. En OpenCart 4 estos mensajes se muestran encima de la página de compra. OpenCart 3 crea un pedido nuevo cada vez que se muestra el paso Confirm Order, y OpenCart 4 actualiza el pedido de la compra (un nuevo intento paga el mismo pedido); si otro pedido del mismo carrito ya está pagado, pendiente de pago o en espera, un nuevo intento va directamente a la página de éxito en lugar de a un segundo pago. Un cambio en el carrito, incluida una nueva cantidad, cuenta como un carrito nuevo que necesita su propio pago.

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, cancelaste un pedido que esperaba el pago del banco), el cliente vuelve a la compra con el mensaje Your previous order was cancelled or refunded by the store. Please confirm the order again to pay with a new order. El siguiente Confirm Order paga un pedido nuevo. Si ese pedido ya estaba pagado por un carrito anterior y el carrito ha cambiado desde entonces, el cliente vuelve a la compra, y el siguiente Confirm Order paga un pedido nuevo del carrito actual. Un pedido cerrado nunca se muestra como pagado.

Si el pago no puede iniciarse, el cliente permanece en el paso Confirm Order con Paysera payments are temporarily unavailable. Please choose another payment method. o, si el total del pedido no es válido, con This order cannot be paid via Paysera. El motivo se escribe en el registro.

La devolución de llamada también funciona mientras la tienda está en modo de mantenimiento, porque OpenCart deja pasar las solicitudes de las extensiones de pago (en OpenCart 4 la extensión añade para ello su propia acción de inicio, que también permite al cliente volver desde Paysera).

La extensión no permite reembolsos desde la administración, ni elegir banco o método de pago en la página de compra, ni suscripciones, ni tarjetas guardadas, ni servicios de entrega o mensajería de Paysera.

Pedidos

Estados de pedido

Sin estado (pedido perdido): el cliente fue enviado a Paysera y la devolución de llamada aún no ha llegado, o el cliente canceló, o el pago no se ejecutó. En Sales > Orders estos pedidos solo se muestran con el filtro Order Status establecido en Missing Orders.

Order Status After Payment (por defecto Processing): Paysera confirmó el pago con el importe y la moneda correctos. Una nota muestra la solicitud y el método de pago, marcada como (TEST — no money charged) en los pagos de prueba.

Awaiting Payment Status (por defecto Pending): Paysera aceptó la orden de pago, pero el banco aún no la ha ejecutado. El pedido pasa a Order Status After Payment cuando Paysera confirma el pago.

On Hold Status (por defecto Pending): el pago necesita una revisión manual. El importe o la moneda pagados difieren del total del pedido; un pago de PRUEBA llegó mientras Test payments está desactivado (no se cobró dinero); o el pago se confirmó después de que el cliente lo cancelara. La nota lo explica, y la pestaña del pedido indica que hay que comprobar el pago en tu cuenta de Paysera y, después, poner el pedido en el estado de pagado o cancelarlo y reembolsar el pago en Paysera. Un pago correcto posterior para el mismo pedido lo marca como pagado.

Cancelled Order Status (por defecto Canceled): un pago confirmado más tarde para un pedido cancelado no cambia su estado. Una nota pide restaurar el pedido (ponerlo en el estado de pagado) o reembolsar el pago en Paysera. Si el método de pago del pedido ya no es Paysera, un pago confirmado solo añade una nota.

Si llega otro pago correcto para un pedido que ya está pagado, o para otro pedido de un carrito que ya está pagado, el pedido pagado no se modifica y una nota pide reembolsar el duplicado en tu cuenta de Paysera. Otros estados de Paysera (pago no ejecutado, información adicional) solo añaden una nota. Las notas son entradas del History del pedido que el cliente no ve.

Pestaña VibeFox Paysera Payment

En Sales > Orders abre un pedido pagado con Paysera. En la parte inferior de la página del pedido, junto a History y Additional, la pestaña VibeFox Paysera Payment muestra el Paysera order ID (el número de pedido y el intento), el Paysera request ID, el Environment y una marca TEST payment, el Status del pago, los importes Requested / paid, el Payment method y las Notes de la extensión. En un pedido en espera muestra qué comprobar. La pestaña solo muestra información y se muestra a los usuarios que tienen acceso a la extensión.

Reembolsos

Los reembolsos desde la administración no están disponibles: el protocolo de la ventana de pago de Paysera no tiene API de reembolsos. Haz los reembolsos en tu cuenta de Paysera. Cuando Paysera informa de un reembolso, se añade al pedido una nota con el importe reembolsado, y el estado del pedido no cambia. Registra el reembolso en OpenCart manualmente si hace falta. Las devoluciones de productos en Sales > Returns no devuelven dinero a través de Paysera.

Clave de licencia

La extensión funciona con una clave de licencia de VibeFox de vibefox.net. El bloque de licencia License — VibeFox Paysera Payment es el primer bloque de Extensions > Extensions > Payments > VibeFox Paysera Payment > Edit, 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 quitar la clave de esta tienda. Debajo aparecen la línea Product: opencart-payment-paysera 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 el servidor de licencias no responde, 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. Quitar la clave de la tienda no libera su plaza de dominio. Libérala en tu cuenta de vibefox.net.

Sin una clave activa, Paysera no se muestra a los clientes en la compra. Si aun así se inicia un pago, el cliente ve This payment method is not available. Please choose another one. Un usuario administrador que haya iniciado sesión en el panel 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 panel, así que sin una clave activa el método de pago se oculta para todos. Después de abrir una vez la página Edit, aparece un recordatorio en el Dashboard del panel. Ciérralo con × para ocultarlo durante 7 días. Los pedidos existentes no se ven afectados: los pagos ya iniciados siguen siendo confirmados por la devolución de llamada.

Cuando una 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 del panel o la página Edit: una vez al día durante los primeros 14 días después de introducir la clave, y después una vez a la semana. No hace falta ningún cron job. Desinstalar la extensión elimina siempre la clave de licencia y su estado.

Solución de problemas

Paysera no aparece en la compra: comprueba que la licencia está activa, que Enable/Disable está activado y que tanto Project ID como Project password están introducidos. La página de ajustes muestra una advertencia mientras falte alguno. Comprueba también que la dirección de pago está en la Geo Zone seleccionada y que el pedido alcanza el Total de los ajustes.

El pago se realizó, pero el pedido se queda sin estado: el pedido recibe su estado de la devolución de llamada de Paysera, no del regreso del cliente. Comprueba que tu tienda es accesible desde internet en la Callback URL que aparece en los ajustes (no detrás de un inicio de sesión, autenticación básica o cortafuegos) y revisa el campo Log de la página de la extensión.

La devolución de llamada responde Invalid signature: la Project password no coincide con el proyecto, o la devolución de llamada no procede de Paysera. Vuelve a copiar la contraseña de proyecto. Si cambiaste el proyecto o la contraseña, los pagos iniciados antes del cambio ya no se pueden verificar.

La devolución de llamada responde Project ID mismatch: el Project ID de los ajustes es distinto del proyecto que realizó el pago.

La devolución de llamada responde Order not found: el pedido de la devolución de llamada no tiene ningún pago de Paysera en esta tienda, por ejemplo porque el pago se inició en otra tienda con el mismo proyecto.

La devolución de llamada responde Gateway not configured, Busy o Temporary error: el ID o la contraseña del proyecto están vacíos, otra devolución de llamada del mismo carrito todavía se está procesando, o no se pudo establecer el estado del pedido. Paysera reintenta la devolución de llamada. Activa Debug log para ver el motivo.

Paysera rechaza la ventana de pago o dice que el proyecto no existe: revisa Environment. Un proyecto normal de Paysera solo funciona con Production; Sandbox necesita un proyecto creado en el entorno sandbox de Paysera.

El pago de prueba no paga el pedido: un pago de PRUEBA solo paga un pedido mientras Test payments esté activado. En caso contrario, el pedido se pone en espera con una nota que indica que no se cobró dinero. Activa también Allow test payments en el proyecto de Paysera.

Un pedido está en espera con una nota sobre diferencia de importe o moneda: Paysera confirmó un pago cuyo importe o moneda difiere del total del pedido. Compara el pago en tu cuenta de Paysera y acepta el pedido o reembolsa el pago manualmente.

El cliente ve Paysera payments are temporarily unavailable: consulta el campo Log. El ID o la contraseña del proyecto pueden estar vacíos, o una de las direcciones de la tienda enviadas a Paysera tiene más de 255 caracteres.

El cliente ve This payment method is not available. Please reload the checkout page.: la sesión de compra ya no coincide con el pedido, o el método de pago se desactivó entretanto. El cliente debe recargar la compra.

Desinstalación

Ve a Extensions > Extensions, elige el tipo Payments y haz clic en Uninstall (el botón rojo −) junto a VibeFox Paysera Payment. 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. También se elimina el evento de OpenCart de la extensión (en OpenCart 4, también sus eventos y su acción de inicio, que permite pasar la devolución de llamada y el regreso del cliente en modo de mantenimiento). Si Delete data está activado, se eliminan los demás ajustes (título, descripción, ID y contraseña del proyecto, pruebas, registro) y el registro. Si está desactivado, se conservan para una reinstalación posterior. Los registros de pagos de Paysera siempre se conservan. 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 desinstalar y haz clic en Uninstall (el botón naranja −) junto a VibeFox Paysera Payment en la lista de extensiones instaladas, y después en Delete (el botón rojo con el icono de papelera) para eliminar el paquete subido.

Paysera es una marca comercial de su respectivo titular. Esta extensión no está afiliada a Paysera ni cuenta con su aprobación.