VibeFox Satispay 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 con la extensión OpenSSL. La extensión genera sus claves RSA con OpenSSL.

Moneda: EUR. Satispay solo cobra en euros. La moneda EUR debe estar activada en System > Localisation > Currencies, y el método de pago solo se muestra mientras el cliente tenga seleccionado EUR.

Cuenta de Satispay: una cuenta Satispay Business. No copias ninguna clave de API: la extensión se conecta con un código de activación de un solo uso que generas en el Satispay Business Dashboard (véase Configuración). Para las pruebas necesitas una cuenta sandbox de Satispay, que solicitas a Satispay para desarrolladores.

Tienda pública: tu tienda debe ser accesible desde internet, para que Satispay pueda llamarla cuando cambie un pago. Para esto no hay que configurar nada en Satispay.

Clave de licencia de VibeFox: se compra en vibefox.net. Una clave funciona en un dominio.

Instalación

El archivo descargado es un único zip con los paquetes de ambas versiones de OpenCart. Descomprímelo en tu ordenador. Contiene README.txt, el paquete de OpenCart 3 wcp_satispay_gateway-oc3-(version).ocmod.zip y el paquete de OpenCart 4 wcp_satispay_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 administrador, ve a Extensions > Installer, haz clic en Upload y elige el archivo wcp_satispay_gateway-oc3-(version).ocmod.zip. La extensión no tiene modificaciones OCMOD, así que Extensions > Modifications no necesita actualizarse. En lugar del instalador, también 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 Satispay Gateway y haz clic en Install (el botón verde +). Tu usuario de 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 (véase License key).

4. Elige el entorno: activa Sandbox Mode para las pruebas; déjalo desactivado para los pagos reales.

5. Pega un código de activación de ese entorno en Activation Code y haz clic en Save. El campo Status mostrará entonces Connected con el Key ID.

6. Activa Enable/Disable y haz clic en Save. Prueba un pago en el sandbox; después, desactiva Sandbox Mode y conecta el entorno de producción con un código de activación de producción.

OpenCart 4

1. En el administrador, ve a Extensions > Installer, haz clic en Upload y elige el archivo wcp_satispay_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 Satispay Gateway, 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, elige el entorno y conéctalo con un código de activación, como en los pasos 3 a 6 de OpenCart 3. La página de ajustes y sus campos son iguales en ambas versiones. Solo la URL del callback es distinta (véase Notificaciones de pago).

Una instalación nueva empieza con el método de pago desactivado y con el entorno de producción seleccionado.

Configuración

Todos los ajustes están en la página de la extensión: Extensions > Extensions > Payments > VibeFox Satispay 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 entorno en uso no está conectado (en ese caso el método de pago queda oculto en la finalización de compra), y cuando la moneda predeterminada de la tienda no es EUR (en ese caso el método de pago solo se muestra mientras el cliente tenga seleccionado EUR). Sin el derecho a modificar la extensión, la página muestra los ajustes pero no permite guardarlos.

Al guardar, Title debe tener entre 1 y 128 caracteres, Sort Order debe ser un número entero (se permiten los negativos), Total debe ser un número igual o mayor que 0, y la zona geográfica y los estados de pedido deben existir. Si un valor es incorrecto, no se guarda nada y el código de activación no se envía.

Finalización de compra

Enable/Disable: Enable Satispay payment activa o desactiva el método de pago. Default: 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. Default: Satispay. Obligatorio, hasta 128 caracteres.

Description: el texto que se muestra al cliente en el paso Confirm Order, encima del botón de confirmar. Default: Pay with the Satispay app: scan the QR code or confirm the payment on your phone.

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

Geo Zone: ofrece Satispay solo para las direcciones de pago de la zona geográfica seleccionada. Default: 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 Satispay: un número igual o mayor que 0. Déjalo vacío para ofrecer Satispay con cualquier total.

Conexión con Satispay

Status: el estado de ambos entornos, por ejemplo Live: Connected con el Key ID o Sandbox: Not connected, y cuál es el entorno in use. Mientras el entorno en uso no esté conectado, el campo dice Satispay is hidden at checkout until the environment in use is connected.

Sandbox Mode: usa el entorno sandbox (de pruebas) de Satispay. Los pagos en sandbox no se cobran. Default: off. Sandbox y producción tienen claves separadas: conecta cada entorno con un código de activación de ese mismo entorno. Mientras se usa el sandbox, el cliente ve Sandbox mode: no real money is charged. en el paso Confirm Order.

Activation Code: para conectar el entorno seleccionado arriba, pega un código de activación nuevo de 6 caracteres y haz clic en Save. Los códigos de producción se generan en el Satispay Business Dashboard, sección Online shop (el campo tiene un enlace a ese panel). Los códigos de sandbox vienen con una cuenta sandbox de Satispay. El código se usa una sola vez y no se guarda. Deja el campo vacío para mantener la conexión actual.

Cuando guardas con un código, primero se guardan los ajustes. Después, la extensión crea un par de claves RSA, envía la clave pública y el código a Satispay, y guarda el Key ID y las claves del entorno en uso. Las claves privadas nunca se muestran ni se exportan. Si todo va bien, la página muestra, por ejemplo, Satispay Live connected. Key ID: seguido del ID. Si Satispay rechaza el código, la página muestra Satispay activation failed: con el mensaje de Satispay y te pide que compruebes que el código es de este entorno y que aún no se ha usado; la conexión actual se mantiene. Un código que no tenga entre 4 y 64 letras y dígitos se rechaza antes de enviar nada. Guardar un código nuevo para un entorno sustituye su conexión anterior.

Notificaciones de pago

No hay nada que configurar en Satispay. Cada pago lleva su propia URL de callback, a la que Satispay llama cuando cambia el pago, y la extensión vuelve a leer el pago desde la API de Satispay antes de cambiar un pedido. El campo Callback URL muestra un ejemplo de esta URL. En OpenCart 3 tiene este aspecto: https://your-store/index.php?route=extension/payment/wcp_satispay_gateway/callback&satispay_p_order={order}&payment_id={uuid}, y en OpenCart 4: https://your-store/index.php?route=extension/wcp_satispay_gateway/payment/wcp_satispay_gateway.callback&satispay_p_order={order}&payment_id={uuid}. Se genera a partir de la dirección de la tienda de tu instalación de OpenCart. La URL debe ser accesible desde internet: no puede haber ningún cortafuegos ni autenticación básica delante. El modo de mantenimiento de OpenCart no la bloquea. Si el callback no puede llegar a tu tienda, el pedido se confirma cuando el cliente regresa.

Pedidos

OpenCart crea el pedido en el paso Confirm Order sin estado (un pedido sin estado, missing order). El pedido solo recibe un estado cuando Satispay ha aceptado el pago. Cada campo de abajo muestra los estados de pedido de tu OpenCart.

Order Status After Payment: el estado que recibe el pedido tras aceptarse el pago. Default: Processing.

Satispay Payment On Hold Status: el dinero se recibió, pero el pedido necesita revisión (véase Order statuses). Default: Pending, porque OpenCart no tiene el estado On hold. Puedes crear tu propio estado en System > Localisation > Order Statuses y seleccionarlo aquí.

Refunded Status: se establece cuando el pago se reembolsa por completo desde la página del pedido. Default: Refunded.

Avanzado

Debug log: escribe las llamadas a la API y los eventos de pago en satispay_p_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 traslada a satispay_p_debug.old.log.php. Las claves, el código de activación y los datos de los clientes no se registran. Los errores siempre se registran, incluso cuando está desactivado. Default: 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 la extensión se eliminan los ajustes de la pasarela, las claves de Satispay de ambos entornos y el registro. Los pagos y reembolsos de Satispay guardados para los pedidos siempre se conservan. Default: off.

Importar / Exportar

Export: Download JSON guarda los ajustes como un archivo JSON. Las claves de Satispay no se exportan.

Import: pega el JSON exportado previamente y haz clic en Import para restaurar los ajustes. La conexión con Satispay se mantiene.

Finalización de compra

En el paso Payment Method, el cliente elige el método de pago (por defecto Satispay). En el paso Confirm Order, el cliente ve tu descripción y la nota You will be redirected to the Satispay page: scan the QR code with the Satispay app or confirm the payment on your phone. OpenCart crea el pedido en este paso, todavía sin estado. Cuando el cliente hace clic en Confirm Order, la extensión crea un pago de Satispay por el total del pedido en euros, con el número de pedido como referencia, y envía al cliente a la página de pago de Satispay. En un ordenador, el cliente escanea el código QR con la aplicación de Satispay. En un teléfono, el cliente confirma el pago en la aplicación. 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 finalización de compra.

Después del pago, el cliente vuelve a tu tienda. El pedido se marca como pagado solo cuando Satispay lo confirma: la extensión lee el pago desde la API de Satispay, comprueba que se creó para este pedido y compara su estado, su importe (en céntimos) y su moneda con los del pedido. Esto ocurre tanto cuando Satispay llama a la URL de callback como cuando el cliente regresa, lo que ocurra primero. Después, el pedido recibe su estado de la forma habitual de OpenCart, con los correos electrónicos de pedido habituales y la actualización del stock, y el cliente ve la página de éxito del pedido de OpenCart. Si Satispay aún no ha confirmado el pago cuando el cliente regresa, aparece una página Payment confirmation con el mensaje Satispay has not confirmed your payment yet. The order will be updated automatically as soon as the confirmation arrives. y un botón Check again. El callback establece el estado del pedido en cuanto llega.

Si el cliente abandona la página de Satispay sin pagar, la extensión cancela el pago en Satispay, de modo que la página abandonada ya no se puede pagar. El cliente vuelve a la finalización de compra con el mensaje Your Satispay payment was cancelled and nothing was charged. You can try again or choose another payment method. El mismo mensaje aparece cuando el cliente rechaza el pago en la aplicación. El carrito se conserva.

OpenCart 3 crea un pedido nuevo cada vez que se muestra el paso Confirm Order. OpenCart 4 mantiene un único pedido para la finalización de compra y lo actualiza, de modo que tras un pago cancelado se paga el mismo pedido con un nuevo pago de Satispay. Antes de crear un pago nuevo de Satispay, se comprueban los pagos anteriores del carrito: un pago pendiente se cancela en Satispay y, si alguno ya está pagado, confirma su pedido; no se realiza un segundo pago y el cliente pasa directamente a la página de éxito.

En OpenCart 4, el mensaje sobre el pago cancelado se muestra encima de la página de finalización de compra. Si el pedido de la finalización de compra lo cerró la tienda entretanto (por ejemplo, cancelado o reembolsado), o si ya está pagado pero el carrito ha cambiado desde entonces, incluida una nueva cantidad, el cliente vuelve a la finalización de compra con Your previous order is already closed. Please confirm the order again: the cart will be paid with a new order. encima de la página de finalización de compra, y el siguiente Confirm Order paga un pedido nuevo.

Si no se puede iniciar el pago, el cliente se queda en el paso Confirm Order con un breve mensaje encima del botón: Satispay is not available at the moment. Please choose another payment method. cuando Satispay rechaza las claves; Satispay supports EUR currency only. para un pedido en otra moneda; o Unable to create the Satispay payment. Please try again or choose another payment method. para otros errores. El motivo se escribe en el registro.

El callback y el regreso del cliente funcionan aunque la tienda esté en modo de mantenimiento: OpenCart 3 deja pasar las solicitudes de las extensiones de pago, y en OpenCart 4 la extensión añade una acción de inicio para ellas.

La extensión acepta solo pagos únicos en euros. No tiene suscripciones, métodos de pago guardados, preautorizaciones ni vales de comida. No hay ninguna comprobación programada de los pagos pendientes: si ni el callback de Satispay ni el regreso del cliente llegan a tu tienda, el pedido se queda sin estado y el pago es visible en el Satispay Dashboard.

Pedidos y reembolsos

Estados de pedido

No status (missing order): el cliente fue enviado a Satispay y no ha pagado, o Satispay todavía no ha confirmado el pago. En Sales > Orders, estos pedidos solo se muestran con el filtro Order Status configurado en Missing Orders. Un pago de Satispay cancelado deja el pedido sin estado, y el cliente puede volver a pagar.

Order Status After Payment (default Processing): el pago fue aceptado. Una nota muestra el pago de Satispay, el importe y la forma en que se verificó (callback, redirección o finalización de compra).

Satispay Payment On Hold Status (default Pending): Satispay informó de un importe o una moneda distintos del total del pedido, o el pago se aceptó después de que el pedido hubiera recibido otro estado (por ejemplo, cancelado). La nota lo explica. Comprueba el pago en el Satispay Dashboard y, después, completa el pedido o reembolsa el pago. Si más adelante se acepta otro pago del mismo carrito por el importe correcto, el pedido pasa a Order Status After Payment.

Refunded Status (default Refunded): el pago fue reembolsado por completo a través de la extensión.

Si se acepta un segundo pago para un pedido que ya está pagado, o para otro pedido del mismo carrito, el pedido pagado no se modifica. Una nota te pide que reembolses el pago duplicado desde el Satispay Dashboard.

Las notas son entradas del History del pedido que el cliente no ve.

VibeFox Satispay Gateway tab

En Sales > Orders, abre un pedido pagado con Satispay. En la parte inferior de la página del pedido, junto a History y Additional, la pestaña VibeFox Satispay Gateway muestra el Satispay payment ID con la etiqueta Sandbox en los pagos de sandbox, el Status del pago, los importes Paid / refunded, el formulario de reembolso, el historial Refunds, la lista Satispay payments of this cart con cada intento de pago, su pedido y su entorno, y las Satispay notes del pedido. La pestaña se muestra a los usuarios que tienen acceso a la extensión.

Reembolsos

En la pestaña VibeFox Satispay Gateway, introduce el Amount (ya aparece el importe aún no reembolsado), opcionalmente un Reason (optional), y haz clic en Refund via Satispay. Confirma la pregunta Refund this amount through Satispay? This cannot be undone. Se admiten reembolsos totales y parciales. Necesitas el permiso para modificar la extensión (se configura en System > Users > User Groups). Los reembolsos se limitan al importe que Satispay cobró por el pago, así que tras una diferencia de importe puedes reembolsar hasta lo que el cliente pagó realmente, no el total del pedido. El reembolso se envía al entorno en el que se hizo el pago (producción o sandbox), por lo que ese entorno debe seguir conectado. Un reembolso se considera realizado solo cuando Satispay lo acepta: un reembolso correcto se añade al historial y a las notas, con el ID de reembolso de Satispay y el motivo. Si Satispay no acepta el reembolso, la pestaña muestra el error y no se registra ningún reembolso. Un reembolso total pone el pedido en Refunded Status sin notificar al cliente y sin devolver los productos al stock, igual que un cambio de estado manual. Un reembolso parcial no cambia el estado. Los reembolsos están disponibles cuando Satispay ya ha aceptado el pago.

Las devoluciones de productos en Sales > Returns no devuelven dinero a través de Satispay. Los reembolsos hechos en el Satispay Dashboard no se registran en OpenCart. Si hace falta, actualiza el pedido manualmente.

Clave de licencia

La extensión funciona con una clave de licencia de VibeFox de vibefox.net. El bloque de licencia License — VibeFox Satispay Gateway es el primer bloque de Extensions > Extensions > Payments > VibeFox Satispay Gateway > 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 eliminar la clave de esta tienda. Debajo aparecen la línea Product: opencart-payment-satispay 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 administrador (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 acceder al servidor de licencias, la extensión sigue funcionando con el último estado conocido.

Una clave funciona en un solo 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, Satispay no se muestra a los clientes en la finalización de compra. Si de todos modos 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 administrador 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 en el administrador, así que sin una clave activa el método de pago queda oculto para todos. Después de abrir la página Edit una vez, aparece un recordatorio en el Dashboard del administrador. Ciérralo con × para ocultarlo durante 7 días. Los pedidos existentes no se ven afectados: los pagos ya iniciados se siguen confirmando y los reembolsos funcionan.

Cuando una licencia caduca, la extensión sigue funcionando, pero las actualizaciones y el soporte requieren una renovación. El estado se vuelve a comprobar automáticamente al abrir el Dashboard o la página Edit del administrador: 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. Al desinstalar la extensión siempre se eliminan la clave de licencia y el estado de la licencia.

Solución de problemas

Satispay no aparece en la finalización de compra: comprueba que la licencia está activa, que Enable/Disable está activado, que el entorno en uso está conectado (el campo Status muestra Connected para él) y que el cliente tiene seleccionado EUR. 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 cuando Satispay llama a tu tienda o cuando el cliente regresa. Comprueba que tu tienda es accesible desde internet, sin cortafuegos ni autenticación básica delante de la URL de callback, y activa Debug log para ver los callbacks en el campo Log. El pago es visible en el Satispay Dashboard.

El callback responde Payment status unavailable, retry later. o Not configured.: la extensión no pudo leer el pago desde Satispay, o el entorno del pago no está conectado. No se modifica ningún pedido. Satispay vuelve a llamar. Comprueba el estado de la conexión y el registro.

El callback responde Busy, retry later.: el carrito estaba siendo confirmado por otra solicitud en el mismo momento, o no se pudo establecer el estado del pedido. Satispay vuelve a llamar. El registro muestra el motivo.

El callback responde Unknown payment. o Missing or invalid payment_id.: el pago no lo creó esta tienda para este pedido, o la solicitud no es un callback de Satispay. No se cambia nada.

La activación falla: los códigos de activación solo se pueden usar una vez. Comprueba que el código pertenece al entorno seleccionado en Sandbox Mode (un código de producción para producción, un código de sandbox para el sandbox), genera un código nuevo y vuelve a guardar. Si la página indica que no se pudo generar un par de claves RSA, pide a tu proveedor de alojamiento que active la extensión OpenSSL de PHP. Si no se pudo contactar con Satispay, comprueba que tu servidor puede abrir conexiones HTTPS salientes.

Satispay desapareció de la finalización de compra al pasar de sandbox a producción: sandbox y producción usan claves distintas. Pega un código de activación de producción con Sandbox Mode desactivado y guarda.

El cliente ve This payment method is not available.: el pedido ya no coincide con la finalización de compra, o el método de pago se desactivó entretanto. El cliente recarga la finalización de compra.

El pedido está en el estado de revisión tras el pago: lee las notas de la pestaña VibeFox Satispay Gateway (véase Order statuses), comprueba el pago en el Satispay Dashboard y, después, completa el pedido o reembolsa el pago.

No hay formulario de reembolso en la pestaña: la pestaña indica el motivo: el pedido no tiene un pago de Satispay aceptado, está reembolsado por completo, tu grupo de usuarios no tiene permiso para modificar la extensión, o el entorno del pago ya no está conectado.

El reembolso falla porque el entorno ya no está conectado: el pago se hizo en producción o en sandbox, y ese entorno ya no tiene claves. Vuelve a conectarlo con un código de activación, o reembolsa el pago desde el Satispay Dashboard.

El reembolso falla con Satispay did not accept the refund: Satispay devolvió un estado distinto de accepted. OpenCart no registró el reembolso, y una nota lo indica. Compruébalo en el Satispay Dashboard.

Desinstalación

Ve a Extensions > Extensions, elige el tipo Payments y haz clic en Uninstall (el botón rojo −) junto a VibeFox Satispay Gateway. La clave de licencia y el estado de la licencia de esta extensión siempre se eliminan. OpenCart siempre elimina sus propios ajustes 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. En OpenCart 4 también se eliminan el evento de la extensión y su acción de inicio, que deja pasar el callback y el regreso del cliente en modo de mantenimiento. Si Delete data on uninstall está activado, se eliminan los demás ajustes de la pasarela (título, descripción, modo sandbox, registro), las claves de Satispay de ambos entornos y el registro. Si está desactivado, se conservan para una reinstalación posterior, incluida la conexión con Satispay. Los pagos y reembolsos de Satispay guardados para los pedidos siempre se conservan, así que los pedidos pagados antes pueden seguir reembolsándose tras una reinstalación, una vez que el entorno vuelva a estar conectado. 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 desinstalarla, haz clic en Uninstall (el botón naranja −) junto a VibeFox Satispay Gateway en la lista de extensiones instaladas, y después en Delete (el botón rojo de papelera) para eliminar el paquete subido.

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