VibeFox DPO for OpenCart — Ayuda

Requisitos

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

PHP: 8.0 o posterior con la extensión SimpleXML.

Cuenta de DPO Pay: necesitas el Company Token y el Service Type ID de tu cuenta de comerciante de DPO. DPO los emite cuando se abre tu cuenta; consíguelos con tu gestor de cuenta de DPO o en dpogroup.com. DPO también puede proporcionar una cuenta de prueba con su propio token y su propio tipo de servicio. No hay un servidor de pruebas aparte: DPO usa la misma dirección de API para las cuentas de prueba y las reales, y la cuenta se elige según el token.

Moneda: la moneda del pedido debe estar admitida por tu cuenta de DPO. DPO acepta como máximo 2 decimales, así que los totales de pedido con 3 decimales (por ejemplo KWD 12.345) no se pueden pagar.

Cron del servidor: una tarea cron que llama a la URL de re-comprobación de la extensión cada 15 minutos (ver Configuración).

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_dpo_pay-oc3-(version).ocmod.zip y el paquete de OpenCart 4 wcp_dpo_pay.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_dpo_pay-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 DPO Pay Gateway y haz clic en Install (el botón verde +). Tu usuario administrador necesita el derecho de modificar la lista de extensiones de pago.

3. Haz clic en Edit (el botón del 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 Company Token y el Service Type de prueba y/o de producción (ver Configuración).

5. Envía al soporte de DPO la URL de notificación push que aparece en la sección Payment notifications y pídeles que la configuren para tu cuenta. Añade la URL de cron a las tareas cron de tu servidor.

6. Activa Enable/Disable y haz clic en Save. Haz un pedido de prueba en modo de prueba y luego desactiva Test mode para aceptar pagos reales.

OpenCart 4

1. En el panel de administración, ve a Extensions > Installer, haz clic en Upload y elige el archivo wcp_dpo_pay.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 DPO Pay 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 y las credenciales de DPO, configura la URL de notificación push y el cron y prueba el pago 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 de notificación push y la URL de cron son diferentes (ver Notificaciones de pago).

Una instalación nueva empieza con el método de pago desactivado y el modo de prueba activado. Al instalar, la extensión crea su tabla de transacciones y el token secreto de la URL de cron.

Configuración

Todos los ajustes están en la página de la extensión: Extensions > Extensions > Payments > VibeFox DPO Pay Gateway > Edit. Las secciones aparecen a la izquierda; el botón Save situado debajo de la lista guarda toda la página. Cuando el método de pago está activado pero el Company Token o el Service Type del modo seleccionado están vacíos, la página avisa de que el método de pago queda oculto en la finalización de compra, y al guardar se muestra el mismo aviso. Mientras el modo de prueba está activado, la página muestra El modo de prueba está activado: los pagos se crean con las credenciales de la cuenta de prueba. Sin el derecho a modificar la extensión, la página muestra los ajustes pero no puede guardarlos.

Al guardar, Title no puede estar vacío (máximo 128 caracteres), Sort Order debe ser un número entero y Total un número igual o mayor que 0; si no, no se guarda nada.

DPO Pay

Enable/Disable: Enable DPO Pay 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 guardado en el pedido. Por defecto: DPO Pay. Obligatorio.

Description: el texto que ve el cliente en el paso Confirm Order, encima del botón de confirmar. Por defecto: Paga de forma segura con tarjeta o dinero móvil en la página de pago de DPO Pay.

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

Geo Zone: ofrece DPO Pay 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 un pedido debe alcanzar para que se ofrezca DPO Pay. Déjalo vacío para ofrecer DPO Pay con cualquier importe.

Credenciales de API

DPO emite un Company Token y un Service Type ID para tu cuenta de comerciante, y otros distintos para una cuenta de prueba. Consíguelos con tu gestor de cuenta de DPO o en dpogroup.com (la sección enlaza allí).

Test mode: cuando está activado, los nuevos pagos se crean con el Company Token y el Service Type de prueba. Por defecto: activado. Desactívalo para aceptar pagos reales con las credenciales reales. Mientras está activado, los clientes ven Modo de prueba: los pagos se crean con la cuenta de prueba. en el paso Confirm Order. Las consultas de estado y las cancelaciones de pagos existentes siempre usan la cuenta con la que se creó el pago.

Test Company Token: el Company Token de tu cuenta de prueba de DPO.

Test Service Type: el Service Type ID numérico de tu cuenta de prueba de DPO.

Live Company Token: el Company Token de tu cuenta de comerciante real de DPO.

Live Service Type: el Service Type ID numérico de tu cuenta de comerciante real de DPO.

Los Company Token guardados nunca se vuelven a mostrar. El campo queda vacío y muestra Guardado: déjalo vacío para conservarlo. Escribe un valor nuevo solo si quieres cambiarlo. Para eliminar un token guardado, marca Clear the saved Company Token on save debajo del campo y haz clic en Save. Un Service Type debe ser un número. Cualquier otro valor no se guarda: la página muestra un aviso y conserva el valor anterior, mientras que los demás ajustes sí se guardan.

Notificaciones de pago

Push notification URL: la notificación push avisa a tu tienda de inmediato de que se ha hecho un pago, incluso si el cliente cierra el navegador después de pagar. La URL no se configura en un panel: pide al soporte de DPO que la configure para tu cuenta. En OpenCart 3 tiene la forma https://your-store/index.php?route=extension/payment/wcp_dpo_pay/notify, y en OpenCart 4 https://your-store/index.php?route=extension/wcp_dpo_pay/payment/wcp_dpo_pay.notify y se construye a partir de la dirección de la tienda de tu instalación de OpenCart. Cópiala exactamente como la muestra la página. Debe ser accesible desde internet, sin cortafuegos ni autenticación básica delante.

Las notificaciones push de DPO no llevan firma, así que su contenido nunca se considera fiable. La extensión solo las usa para encontrar el pago por su token de transacción y después comprueba el resultado con el propio DPO. Un token que tu tienda no creó se rechaza sin ninguna petición a DPO.

Re-comprobación programada del estado (cron): llama a esta URL cada 15 minutos desde una tarea cron del servidor, por ejemplo con curl. Los pagos no confirmados se vuelven a comprobar con DPO 15 minutos después de la redirección y de nuevo tras el límite de tiempo de pago. La URL contiene un token secreto, así que manténla privada. En OpenCart 4 tiene el aspecto de https://your-store/index.php?route=extension/wcp_dpo_pay/payment/wcp_dpo_pay.cron&token= y el token. Sin la URL push y el cron, un pedido solo recibe su estado cuando el cliente vuelve a la tienda después de pagar.

Pedidos

OpenCart crea el pedido en el paso Confirm Order sin estado (un pedido faltante). El pedido solo recibe un estado después de que DPO haya confirmado el pago. Cada campo siguiente muestra tus estados de pedido de OpenCart.

Successful payment status: el estado del pedido tras un pago exitoso verificado. Por defecto: Procesando. Elige Completado si cada pedido pagado debe completarse, o tu propio estado de revisión para aprobar cada pedido manualmente.

DPO payment on hold status: el estado de un pago que necesita tu revisión: diferencia de importe o moneda, un pago solo autorizado, una transacción pagada de más o de menos, o un pago realizado después de que el cliente cancelara. Una nota en el historial del pedido explica el motivo. Por defecto: Pendiente, porque OpenCart no tiene un estado On hold. Puedes crear tu propio estado en System > Localisation > Order Statuses y seleccionarlo aquí.

Cancelled order status: cuando pones en este estado un pedido no pagado de DPO Pay, su pago abierto de DPO también se cancela en DPO. Por defecto: Cancelado.

Avanzado

Logging: escribe las llamadas a la API y las notificaciones en dpo_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 dpo_p_debug.old.log.php. Los errores siempre se registran. Los tokens se enmascaran y no se registran datos de clientes. Por defecto: desactivado.

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

Delete data: cuando está activado, desinstalar la extensión elimina los ajustes de la pasarela y el registro. Los datos de DPO guardados de los pedidos se conservan siempre. Desinstalar sin esta opción nunca elimina datos. Por defecto: desactivado.

Importación / Exportación

Export: Download JSON guarda los ajustes en un archivo JSON. Los Company Token no se exportan.

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

Finalización de compra

En el paso Payment Method el cliente elige el método de pago (por defecto DPO Pay). En el paso Confirm Order el cliente ve tu descripción y la nota Serás redirigido a la página de pago segura de DPO Pay. OpenCart crea el pedido en este paso, todavía sin estado. Cuando el cliente hace clic en Confirm Order, la extensión crea una transacción de DPO por el total del pedido en la moneda del pedido, con el número de pedido y el nombre de tu tienda como descripción, y envía al cliente a la página de pago de DPO. Su nombre, correo electrónico, teléfono y dirección de pago se envían para rellenar previamente la página. Allí el cliente paga con cualquier método habilitado en tu cuenta de DPO. El enlace de pago es válido durante 5 horas. En OpenCart 4, el cliente elige el método de pago con el botón Choose del bloque de métodos de pago, en la ventana Payment method options, y hace clic en Confirm Order en la parte inferior de la página de finalización de compra. Si la tienda no pide una dirección de pago (valor predeterminado de OpenCart 4), se envía en su lugar la dirección de envío.

Después de pagar, el cliente vuelve a tu tienda. El pedido solo se marca como pagado cuando DPO lo confirma: la extensión consulta a DPO el resultado de la transacción cuando el cliente vuelve, cuando llega una notificación push y en las re-comprobaciones programadas. Después el pedido recibe su estado de la forma habitual de OpenCart, con los correos de pedido habituales y la actualización del stock, y el cliente ve la página de pedido realizado de OpenCart. En OpenCart 4, el navegador no envía la sesión de la tienda cuando DPO devuelve al cliente, así que la extensión muestra primero una página breve que vuelve a abrir la misma dirección de retorno desde tu tienda: el cliente conserva el carrito y el inicio de sesión.

Si el pago no se confirma, el cliente vuelve a la finalización de compra con uno de estos mensajes (en OpenCart 4, encima de la página de finalización de compra). El carrito se conserva.

Si el cliente hace clic en el botón de la página de DPO para volver a la tienda, primero se comprueba la transacción. Si se pagó, el cliente ve la página de éxito. Si no, la transacción se cancela en DPO y el cliente vuelve a la finalización de compra con el carrito.

OpenCart 3 crea un pedido nuevo cada vez que se muestra el paso Confirm Order; OpenCart 4 mantiene un pedido para la finalización de compra y lo actualiza, y un nuevo intento es una nueva transacción de DPO del mismo pedido. Antes de un nuevo pago, se comprueban las transacciones abiertas de DPO del pedido y de los pedidos anteriores del mismo carrito. Si una se pagó, ese pago se confirma y el cliente va a la página de éxito sin un segundo cargo. Si una todavía se está procesando, el cliente ve Tu pago anterior para este pedido todavía lo está procesando DPO. Espera unos minutos antes de volver a intentarlo. Si no, las transacciones antiguas se cancelan en DPO y se crea una nueva.

OpenCart 4 mantiene el pedido en la finalización de compra hasta que se muestra la página de éxito. Si ese pedido se cerró entretanto (por ejemplo, se canceló o se reembolsó), Confirm Order o el regreso desde DPO devuelve al cliente a la finalización de compra: con The payment was declined or cancelled. Please try again or choose another payment method. si el pedido no tenía pago, o con Your previous order was closed by the store. Please confirm the order again: the cart will be paid with a new order. si lo tenía. Si el pedido ya está pagado y el carrito ha cambiado desde entonces (otros productos o cantidades), el mensaje es Your previous order is already paid. Please confirm the order again: the cart will be paid with a new order. En todos estos casos, el siguiente Confirm Order paga un pedido nuevo del carrito.

Si DPO no puede iniciar el pago, el cliente se queda en el paso Confirm Order con un breve mensaje encima del botón, elegido según el código de error de DPO, por ejemplo DPO Pay no admite la moneda de este pedido. Elige otro método de pago. o El importe supera el límite permitido por DPO Pay. Elige otro método de pago o ponte en contacto con nosotros. Otros errores muestran DPO Pay no está disponible temporalmente. Inténtalo de nuevo o elige otro método de pago. El motivo técnico se escribe en el registro.

La notificación push y la URL de cron también funcionan mientras la tienda está en modo de mantenimiento: OpenCart 3 deja pasar las peticiones de las extensiones de pago, y en OpenCart 4 la extensión añade una acción de inicio que deja pasar la notificación push, la URL de cron y el retorno del cliente. Los pagos ya iniciados se confirman aunque desactives el método de pago.

La extensión acepta pagos únicos solo en la página de DPO. No tiene reembolsos desde la tienda, ni tarjetas guardadas, ni suscripciones o pagos recurrentes, ni campos de tarjeta en tu sitio, ni captura de pagos solo autorizados.

Pedidos

Estados del pedido

Sin estado (pedido faltante): el cliente fue enviado a DPO y no ha pagado, el pago fue rechazado o cancelado, o DPO todavía no ha confirmado el pago. En Sales > Orders estos pedidos solo se muestran con el filtro Order Status establecido en Missing Orders.

Successful payment status (por defecto Procesando): el pago se verificó. Una nota en el historial del pedido muestra el importe, la moneda, el código de aprobación y el inicio del token de transacción de DPO.

DPO payment on hold status (por defecto Pendiente): DPO confirmó un pago, pero el importe o la moneda difieren del pedido, el pago solo está autorizado y no capturado, la transacción tiene un pago de más o de menos, o el cliente había cancelado el pago o el pedido ya estaba cancelado. La nota explica el motivo. Revisa la transacción en el portal de DPO. Captura o anula un pago solo autorizado en el portal de DPO y después actualiza el estado del pedido.

Cancelled order status (por defecto Cancelado): cuando pones en este estado un pedido no pagado de la extensión (por ejemplo, uno retenido por un pago solo autorizado), su transacción abierta de DPO también se cancela en DPO.

Un resultado posterior de rechazo nunca cambia un pedido, y los resultados de transacciones antiguas nunca hacen fallar el intento actual. Si DPO confirma un segundo pago exitoso para un pedido que ya está pagado, el pedido no cambia y recibe una nota sobre un posible doble pago, para que puedas reembolsarlo en el portal de DPO. Se añade el mismo tipo de nota al pedido pagado cuando el mismo carrito (misma sesión del cliente y mismo contenido) se pagó de nuevo con otro pedido, por ejemplo en una segunda pestaña del navegador; ese otro pedido no conserva ningún estado. Un pedido que hayas cambiado a otro estado (por ejemplo, reembolsado) nunca se vuelve a abrir; un pago tardío solo añade una nota.

Las notas son entradas del History del pedido que el cliente no ve. La extensión no tiene pestaña en la página del pedido.

Reembolsos

Los reembolsos desde la tienda no están disponibles en esta versión. Reembolsa el pago en el portal de comerciante de DPO y luego cambia el estado del pedido en OpenCart.

Clave de licencia

La extensión funciona con una clave de licencia de VibeFox de vibefox.net. El bloque de licencia License — VibeFox DPO Pay Gateway es el primer bloque de Extensions > Extensions > Payments > VibeFox DPO Pay 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 aparecen la línea Product: opencart-payment-dpo 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 el inglés y el ruso).

Si la clave no es aceptada, el bloque indica el motivo, por ejemplo Clave no encontrada, Esta clave pertenece a otro producto, Límite de dominios alcanzado o Licencia caducada el una fecha. Después de cambiar la dirección de la tienda, o tras liberar una plaza de dominio en tu cuenta, haz clic en Check now. Si el servidor de licencias no está disponible, 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. Quitar la clave de la tienda no libera su plaza de dominio. Libérala en tu cuenta de vibefox.net.

Sin una clave activa, DPO Pay no se muestra a los clientes en la finalización de compra. Si de todos modos se inicia un pago, el cliente ve Este método de pago no está disponible. Elige otro. 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) (sin licencia: visible solo para administradores), 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 de administración, 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 panel de administración. Ciérralo con × para ocultarlo durante 7 días. Los pedidos existentes no se ven afectados: los pagos ya iniciados se siguen confirmando.

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 panel de administración: una vez al día durante los primeros 14 días tras introducir la clave, y después una vez por semana. No hace falta ninguna tarea cron. Al desinstalar la extensión siempre se eliminan la clave de licencia y el estado de la licencia.

Solución de problemas

DPO Pay no aparece en la finalización de compra: comprueba que la licencia está activa, que Enable/Disable está activado y que el Company Token y el Service Type del modo seleccionado están configurados: los campos de prueba en modo de prueba, los reales en caso contrario. La página de configuración muestra un aviso si faltan. 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: probablemente la URL de notificación push no está configurada para tu cuenta de DPO, y el cliente no volvió a la tienda. Pide al soporte de DPO que configure la URL que aparece en los ajustes, y comprueba que el cron llama a la URL de re-comprobación cada 15 minutos. Activa Logging y revisa el campo Log de la página de la extensión.

La notificación push responde Unknown transaction: el token de transacción no pertenece a un pago de DPO Pay de esta tienda; por ejemplo, la notificación procede de otra tienda de la misma cuenta de DPO.

La notificación push responde Verification failed: no se pudo contactar con DPO para comprobar el pago, otra petición estaba procesando el pedido en el mismo momento, o no se pudo establecer el estado del pedido. DPO repite la notificación, y la re-comprobación programada también confirma el pedido. El motivo está en el registro.

La URL push muestra Method not allowed en el navegador: es normal. La URL solo acepta peticiones de DPO.

La URL de cron responde Forbidden: el token de la URL es incorrecto. Copia la URL de nuevo desde la página de ajustes. Una llamada correcta responde OK checked= y el número de pagos comprobados.

El Service Type no se guarda: debe ser el Service Type ID numérico de DPO.

El cliente ve Este método de pago no está disponible. Recarga la página de finalización de compra.: la sesión de finalización de compra ya no coincide con el pedido, o el método de pago se desactivó entretanto. El cliente recarga la finalización de compra.

El cliente ve DPO Pay is temporarily unavailable: DPO rechazó crear la transacción, por ejemplo por un Company Token o Service Type incorrectos, o un token del otro modo. El código de resultado de DPO está en el registro.

El cliente ve que DPO admite como máximo 2 decimales: el total del pedido tiene 3 decimales. DPO no puede cobrar importes así.

El cliente ve This order has already been paid with DPO Pay: DPO rechazó un segundo pago para el mismo pedido. Revisa el pago en el portal de DPO y el pedido en OpenCart.

El pedido está en el estado de revisión tras el pago: lee la nota en el History del pedido (ver Estados del pedido) y revisa después la transacción en el portal de DPO.

Para desarrolladores: la extensión dispara los eventos de OpenCart wcp_dpo_pay_customer_data (los datos del cliente enviados a DPO) y wcp_dpo_pay_payment_time_limit (el límite de tiempo de pago en horas).

Desinstalación

Ve a Extensions > Extensions, elige el tipo Payments y haz clic en Uninstall (el botón rojo −) junto a VibeFox DPO Pay 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. 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 deja pasar DPO y el cron en modo de mantenimiento). Si Delete data está activado, se eliminan los demás ajustes de la pasarela (título, descripción, modo de prueba, Company Tokens, Service Types, registro) y el registro, y una reinstalación crea una nueva URL de cron. Si está desactivado, se conservan para una reinstalación posterior. Los datos de DPO guardados de los pedidos se conservan siempre, de modo que las notificaciones tardías y las re-comprobaciones de pagos antiguos siguen funcionando tras una reinstalación. 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 DPO Pay Gateway en la lista de extensiones instaladas, y luego en Delete (el botón rojo de papelera) para eliminar el paquete subido.

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