VibeFox Paymob 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 Paymob: una cuenta de comerciante en uno de los países compatibles: Egipto, Emiratos Árabes Unidos, Arabia Saudí, Omán o Pakistán. Necesitas cuatro valores del panel de Paymob: la clave de API, el ID de integración de un pago en línea, el ID de iFrame de la página de pago y el secreto HMAC.

Moneda: la moneda de la compra debe ser la de tu país de Paymob: EGP para Egipto, AED para los Emiratos Árabes Unidos, SAR para Arabia Saudí, OMR para Omán y PKR para Pakistán. Añádela en System > Localisation > Currencies si tu tienda aún no la tiene. Con otra moneda, el método de pago se oculta en la finalización de compra. Las cuentas de Paymob multimoneda no son compatibles.

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 para ambas versiones de OpenCart. Descomprímelo en tu ordenador. Contiene README.txt, el paquete de OpenCart 3 wcp_paymob_pay-oc3-(version).ocmod.zip y el paquete de OpenCart 4 wcp_paymob_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_paymob_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 Paymob Pay y haz clic en Install (el botón verde +).

3. Haz clic en Edit (el botón con el 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 (véase Clave de licencia).

4. Elige el Paymob country e introduce la clave de API, el ID de integración, el ID de iFrame y el secreto HMAC (véase Configuración).

5. En el panel de Paymob, configura las URL de callback de tu integración con la URL que se muestra en la sección Callbacks (véase Callbacks).

6. Activa Enable/Disable y haz clic en Save. Prueba un pago con el ID de una integración de prueba de Paymob y después introduce el ID de tu integración real.

OpenCart 4

1. En el panel de administración ve a Extensions > Installer, haz clic en Upload y elige el archivo wcp_paymob_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 Paymob Pay, 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, las claves e ID de Paymob y las URL de callback 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 callback es diferente (véase Callbacks).

Una instalación nueva empieza con el método de pago desactivado.

Configuración

Todos los ajustes están en la página de la extensión: Extensions > Extensions > Payments > VibeFox Paymob Pay > Edit. Las secciones aparecen a la izquierda; el botón Save bajo la lista guarda toda la página. Encima de los ajustes, la página te avisa cuando falta uno de los cuatro valores de Paymob (hasta entonces Paymob se oculta en la finalización de compra) y cuando la moneda predeterminada de la tienda no la acepta el país de Paymob seleccionado.

Al guardar, Title no puede tener más de 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 la zona geográfica y los estados de pedido seleccionados deben existir; si no, no se guarda nada y la página indica el campo.

Paymob

Enable/Disable: Enable Paymob 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, hasta 128 caracteres. Si está vacío, los clientes ven Paymob. Por defecto: Paymob.

Description: el texto que se muestra al cliente en el paso Confirm Order, encima del botón de confirmación. Por defecto: Pay securely by card or mobile wallet on the Paymob payment page. Déjalo vacío para no mostrar ningún texto.

Sort Order: la posición de Paymob 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 Paymob solo a direcciones de pago de la zona geográfica seleccionada. Por defecto: All zones. Las zonas geográficas se configuran en System > Localisation > Geo Zones. En OpenCart 4, cuando la tienda no pide dirección de pago, se usa la dirección de envío.

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

Cuenta de Paymob

Todos los valores están en tu panel de comerciante de Paymob. No hay un modo de prueba aparte: para los pagos de prueba introduce el ID de integración de una integración en modo de prueba. Ningún otro ajuste cambia.

Paymob country: el país de tu cuenta de Paymob. Selecciona el servidor de API y de página de pago, y la moneda de la compra debe ser la de este país. Por defecto: Egypt.

API key: en el panel de Paymob, en Settings > Account info > API Key.

Integration ID: en el panel de Paymob, en Developers > Payment Integrations: el ID numérico de la integración de tarjeta o monedero en línea. Los métodos de pago que se ofrecen en la página de Paymob son los de esta integración.

iFrame ID: en el panel de Paymob, en Developers > iframes: el ID numérico del iFrame de pago.

HMAC secret: en el panel de Paymob, en Settings > Account info > HMAC. Obligatorio: los pedidos solo se marcan como pagados con callbacks firmados con este secreto.

Integration ID e iFrame ID deben contener solo dígitos. Los espacios se eliminan. Cualquier otro valor se rechaza al guardar con el mensaje de que el campo must contain digits only — the previous value was kept. Los demás campos se guardan.

La clave de API y el secreto HMAC 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 valor guardado, marca Clear the saved API key on save o Clear the saved HMAC secret on save debajo del campo y haz clic en Save.

Callbacks

Paymob informa a tu tienda de cada transacción. En el panel de Paymob abre Developers > Payment Integrations, elige tu integración, haz clic en Edit y define tanto Transaction processed callback como Transaction response callback con la Callback URL que se muestra en esta sección. En OpenCart 3 tiene este aspecto: https://your-store/index.php?route=extension/payment/wcp_paymob_pay/callback, y en OpenCart 4: https://your-store/index.php?route=extension/wcp_paymob_pay/payment/wcp_paymob_pay.callback. Se construye a partir de la dirección pública de tu instalación de OpenCart. Cópiala con el botón Copy. La sección también enlaza con el panel de Paymob del país seleccionado. Define las URL en cada integración que uses, incluida la de prueba.

El callback de transacción procesada (Transaction processed callback) lo envía el servidor de Paymob. El callback de respuesta de la transacción (Transaction response callback) devuelve al cliente a tu tienda. Ambos se firman con tu secreto HMAC y la extensión los comprueba. Los callbacks sin una firma válida se rechazan y no cambian nada. Si el callback del servidor llega tarde o se pierde, un retorno firmado del cliente también confirma el pago. La URL de callback también funciona 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 (startup) que deja pasar los callbacks y el retorno del cliente.

Pedidos

OpenCart crea el pedido en el paso Confirm Order sin estado (un pedido sin estado). Recibe un estado solo después de que Paymob haya informado de una transacción firmada correctamente. Un pago rechazado deja el pedido sin estado; el cliente vuelve a la finalización de compra con el carrito conservado. Cada campo siguiente muestra tus estados de pedido de OpenCart.

Order Status After Payment: la transacción de Paymob está pagada con el importe y la moneda esperados. Por defecto: Procesando.

Awaiting Paymob Payment Status: la transacción está pendiente, por ejemplo un pago en efectivo o en quiosco. El pedido recibe el estado de después del pago cuando Paymob lo confirma. Por defecto: Pendiente.

Paymob Payment On Hold Status: Paymob solo autorizó el importe (captúralo en el panel de Paymob), el importe o la moneda pagados no coinciden con el pedido, o el pago llegó para un pedido cancelado. Una nota 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í.

Los tres campos siguientes indican a la extensión qué estados usa tu tienda. La extensión nunca los establece.

Payment Error Status: el estado que usa tu tienda para los pedidos con error de pago. Una transacción pendiente puede pasar un pedido así al estado de en espera. Por defecto: Fallido.

Cancelled Order Status: el estado que usa tu tienda para los pedidos cancelados. Un pago recibido para un pedido así lo pone en espera, o solo añade una nota si ya se había pagado antes. Por defecto: Cancelado.

Refunded Order Status: el estado que usa tu tienda para los pedidos reembolsados. Un pago recibido para un pedido así solo añade una nota. Por defecto: Reembolsado.

Avanzado

Debug log: escribe los pasos del pago y los callbacks en paymob_p_debug.log.php en la carpeta de registros de OpenCart (storage/logs). El archivo no se puede abrir desde la web. Los errores y los callbacks rechazados siempre se registran, incluso con el interruptor desactivado. Las claves, los tokens 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.

Clean uninstall: si está activado, al desinstalar la extensión se eliminan los ajustes de la pasarela y el registro. Los ID de Paymob guardados para los pedidos (intentos de pago) siempre se conservan. Por defecto: desactivado.

Importar / Exportar

Export: Download JSON guarda los ajustes como archivo JSON. La clave de API y el secreto HMAC no se exportan.

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

Finalización de compra

En el paso Payment Method el cliente elige el método de pago (por defecto Paymob). En el paso Confirm Order el cliente ve tu descripción y la nota You will be redirected to the secure Paymob payment page to pay by card or mobile wallet. OpenCart crea el pedido en este paso, aún 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 finalización de compra. Cuando el cliente hace clic en Confirm Order, la extensión registra un nuevo pedido de Paymob por el total del pedido en la moneda del pedido, envía a Paymob el nombre, el correo electrónico, el teléfono y la dirección de pago del cliente (en OpenCart 4, cuando la tienda no pide dirección de pago, la dirección de envío) y lo lleva a la página de pago de Paymob de tu país. Allí el cliente paga con uno de los métodos de tu integración, por ejemplo una tarjeta o un monedero móvil.

Después de pagar, el cliente vuelve a tu tienda. El pedido se marca como pagado solo cuando Paymob lo confirma con una transacción firmada. Entonces 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 éxito del pedido de OpenCart. Un pago pendiente (por ejemplo en efectivo o en quiosco) o un pago autorizado también dan un estado al pedido, el de en espera o el de retención, y llevan a la página de éxito.

Si el pedido aún se está confirmando cuando el cliente vuelve, una página Payment confirmation dice Paymob accepted your payment and we are confirming it. You will receive an e-mail as soon as your order is confirmed — there is no need to pay again. En un pago pendiente el texto es Your Paymob payment is pending (for example a cash or kiosk payment). Complete it as Paymob instructed you: your order is confirmed as soon as Paymob reports the payment. La página tiene un botón Check again y otro Back to checkout.

Si el pago fue rechazado, el cliente vuelve a la finalización de compra con el mismo carrito y el mensaje Your Paymob payment was not completed. Please try again or choose another payment method. Cada nuevo intento registra su propio pedido de Paymob, así que el cliente puede volver a pagar 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, así que el cliente paga el mismo pedido con un nuevo intento. Si no se puede verificar la respuesta de Paymob, el cliente ve We could not verify the response from Paymob. If you were charged, your order will be updated as soon as Paymob confirms the payment. Si otro pedido del mismo carrito ya se ha pagado o está esperando el pago (por ejemplo desde una segunda pestaña del navegador), el cliente pasa a la página de éxito en lugar de pagar otra vez. En OpenCart 4 los mensajes tras el retorno desde Paymob se muestran encima de la página de finalización de compra.

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ó sin pago entretanto (por ejemplo, lo cancelaste), el cliente vuelve a la finalización de compra con Your previous order was cancelled without a payment. Please confirm the order again to pay with a new order., y el siguiente Confirm Order paga un pedido nuevo. Si ese pedido ya tiene un estado y el carrito ahora tiene otros productos o cantidades, el cliente también vuelve a la finalización de compra, y el carrito nuevo recibe un pedido nuevo.

Si Paymob no puede iniciar el pago, el cliente permanece en el paso Confirm Order con un mensaje breve encima del botón, por ejemplo Paymob could not start the payment. Please check your billing details and try again, or choose another payment method. o Could not connect to Paymob. Please try again in a moment. El motivo técnico se escribe en el registro.

La extensión acepta solo pagos únicos en la página de Paymob. No tiene tarjetas guardadas, ni suscripciones, ni formulario de tarjeta integrado en tu web, ni reembolsos desde el panel de administración.

Pedidos

Estados de pedido

No status (missing order): el cliente fue enviado a Paymob y no ha pagado, el pago fue rechazado o Paymob aún no ha confirmado el pago. En Sales > Orders estos pedidos solo se muestran con el filtro Order Status en Missing Orders.

En OpenCart 4 un pedido no pagado de la finalización de compra puede recibir el estado Voided, que OpenCart 4 establece cuando el cliente vuelve al paso Confirm Order. La extensión trata ese pedido como un pedido sin estado, y un pago posterior sigue confirmándolo.

Order Status After Payment (default Processing): Paymob confirmó el pago. Una nota muestra la transacción, el importe y el tipo de tarjeta con los cuatro últimos dígitos.

Awaiting Paymob Payment Status (default Pending): el pago está pendiente en Paymob, por ejemplo un pago en efectivo o en quiosco. El pedido pasa al estado de después del pago cuando Paymob confirma el pago.

Paymob Payment On Hold Status (default Pending): Paymob solo autorizó el importe y no lo ha capturado (captúralo en el panel de Paymob; el pedido pasa al estado de después del pago cuando llega el callback de captura); o el importe o la moneda pagados no coinciden con el pedido; o llegó un pago para un pedido que había sido cancelado. La nota explica el motivo. Revisa el pedido y complétalo o reembolsa el pago en el panel de Paymob.

Cuando cambia un pedido que ya tiene estado, OpenCart avisa al cliente. Si llega un segundo pago correcto para un pedido ya pagado, o un pago para un segundo pedido de un carrito ya pagado, el pedido pagado no cambia y una nota te pide reembolsar el duplicado en el panel de Paymob. Un pago para un pedido cancelado que se había pagado antes, o para un pedido reembolsado, solo añade una nota: el pedido no se reabre. Un pago rechazado para un pedido que ya tiene estado solo añade una nota.

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

Pestaña VibeFox Paymob Pay

En Sales > Orders abre un pedido pagado con Paymob. En la parte inferior de la página del pedido, junto a History y Additional, la pestaña VibeFox Paymob Pay muestra cada intento de Paymob del pedido: el Paymob order con el ID de pedido del comerciante y el país, el Paymob transaction ID, el Status, el importe Requested, el Amount reported by Paymob con la tarjeta y el Paymob message. Debajo están las Notes de la extensión para este pedido. La pestaña se muestra a los usuarios que tienen acceso a la extensión.

Reembolsos

Los reembolsos desde el panel de administración no son compatibles. Reembolsa o anula el pago en el panel de Paymob. Cuando Paymob informa de un reembolso o una anulación, se añade una nota al pedido, y el estado del pedido no cambia. 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 Paymob Pay es el primer bloque de Extensions > Extensions > Payments > VibeFox Paymob Pay > Edit, encima de los ajustes. Pega la clave en License key y haz clic en Activate. Después, el bloque muestra la clave oculta, el estado (por ejemplo, la fecha hasta la que la licencia está activa y tu dominio) y los botones Check now para comprobar el estado de nuevo, 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-paymob y el enlace Manage licenses and domains in your account, que abre tu cuenta de vibefox.net. Solo los usuarios de administración con el permiso Modify de 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 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, Paymob no se muestra a los clientes en la finalización de compra. Si aun así se inicia un pago, el cliente ve This payment method is not available. Please choose another one. Un usuario de administración 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 del administrador, así que sin una clave activa el método de pago se oculta a 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.

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 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 por semana. No hace falta una tarea cron. Al desinstalar la extensión siempre se eliminan la clave de licencia y el estado de la licencia.

Solución de problemas

Paymob no aparece en la finalización de compra: comprueba que la licencia está activa, que Enable/Disable está activado, que los cuatro valores (clave de API, ID de integración, ID de iFrame, secreto HMAC) están rellenados y que la moneda de la compra es la del Paymob country seleccionado. La página de ajustes muestra una advertencia cuando falta algo. Comprueba también que la dirección de pago está en la Geo Zone seleccionada y que el pedido alcanza el Total definido en los ajustes.

El pago se realizó, pero el pedido se queda sin estado: los callbacks no llegan a tu tienda. Comprueba que Transaction processed callback y Transaction response callback de la integración que usas son exactamente la URL que se muestra en la sección Callbacks, y que el HMAC secret es el de la misma cuenta de Paymob. Los callbacks rechazados se escriben en el registro como advertencias, incluso con Debug log desactivado. Mira el campo Log en la página de la extensión.

El callback responde Invalid signature: el secreto HMAC de los ajustes no coincide con la cuenta de Paymob, o está seleccionada la cuenta de otro país. Copia de nuevo el secreto HMAC.

El callback responde Not configured: el secreto HMAC está vacío. Introduce el secreto; Paymob reintenta el callback.

El callback responde locked o retry: otra petición estaba actualizando el pedido en ese mismo momento, por ejemplo el retorno del cliente, o no se pudo establecer el estado del pedido. Paymob reintenta el callback. El motivo se escribe en el registro.

Abrir la URL de callback en el navegador lleva a la finalización de compra con el mensaje de que no se pudo verificar: es normal. La URL solo acepta peticiones firmadas de Paymob.

El cliente ve un error después de Confirm Order: activa Debug log y mira el registro. Paymob payments are temporarily unavailable significa una clave de API incorrecta o un valor que falta. Paymob could not start the payment significa que Paymob rechazó la petición, por ejemplo por un ID de integración incorrecto o datos de facturación incompletos. This order cannot be paid with Paymob significa que el total del pedido es cero. Paymob does not accept payments in seguido de una moneda significa que la moneda del pedido no es la del país de Paymob seleccionado. This payment method is not available. significa que la sesión de compra ya no coincide con el pedido o que el método de pago se desactivó entretanto: el cliente debe recargar la finalización de compra.

El pedido está en el estado de en espera o de retención tras el pago: lee las notas de la pestaña VibeFox Paymob Pay. El pago está pendiente (efectivo o quiosco), la transacción solo fue autorizada (captúrala en el panel de Paymob), el importe o la moneda no coincidían, o el pago llegó después de que el pedido se cancelara.

Pagos de prueba: introduce el ID de una integración de prueba de Paymob en Integration ID y define las URL de callback en esa integración. Para los pagos reales, vuelve a introducir el ID de tu integración real.

Desinstalar

Ve a Extensions > Extensions, elige el tipo Payments y haz clic en Uninstall (el botón rojo −) junto a VibeFox Paymob Pay. La clave de licencia y el estado de licencia de esta extensión se eliminan siempre. 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 OpenCart de la extensión y su acción de inicio, que deja pasar los callbacks y el retorno del cliente en modo de mantenimiento. Si Clean uninstall está activado, se eliminan los demás ajustes de la pasarela (título, descripción, país, claves e ID, registro) y el registro. Si está desactivado, se conservan para una reinstalación posterior. Los intentos de pago de Paymob de los pedidos siempre se conservan. Los pedidos existentes conservan sus notas de pago y sus ID de Paymob.

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

Paymob es una marca comercial de su respectivo propietario. Esta extensión no está afiliada ni respaldada por Paymob.