VibeFox Paymob for PrestaShop — Ayuda

Requisitos

PrestaShop: 8.0 a 9.x.

PHP: 8.0 o posterior. El módulo no se instala en versiones anteriores de PHP.

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 API key, el integration ID de una integración de pago online, el iFrame ID de la página de pago y el HMAC secret.

Moneda: la moneda del carrito debe ser la moneda de tu país de Paymob: EGP para Egipto, AED para Emiratos Árabes Unidos, SAR para Arabia Saudí, OMR para Omán, PKR para Pakistán. Con otra moneda, el método de pago no se muestra en Finalizar compra. Las cuentas de Paymob con varias monedas no son compatibles.

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

Instalación

1. En el back office ve a Modules > Module Manager y haz clic en Upload a module. Elige el archivo ZIP del módulo.

2. Cuando termine la subida, haz clic en Configure, o busca más tarde VibeFox Paymob Pay en la lista de módulos y haz clic en Configure.

3. Introduce tu clave de licencia de VibeFox en License key, en el bloque de licencia de la parte superior de la página Configure, y haz clic en Activate (véase Clave de licencia).

4. Elige el Paymob country e introduce la API key, el integration ID, el iFrame ID y el HMAC secret (véase Configuración).

5. En el panel de Paymob, configura las URL de callback de tu integración con la URL que aparece en la página Configure (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 luego introduce el ID de tu integración real.

Al instalarse, el módulo crea dos estados de pedido: Awaiting Paymob payment y Paymob payment on hold. De forma predeterminada, PrestaShop activa el nuevo módulo de pago para todas las monedas, países y grupos de clientes. Puedes limitarlo en Payment > Preferences. Un país que actives más tarde en tu tienda también debe estar marcado allí para este módulo.

Configuración

Todos los ajustes están en la página del módulo: Modules > Module Manager > VibeFox Paymob Pay > Configure. Cada sección tiene su propio botón Save, que guarda toda la página. Encima de los campos, la página avisa cuando falta uno de los cuatro valores de Paymob (hasta entonces Paymob no se muestra en Finalizar compra) y cuando la moneda predeterminada de la tienda no la acepta el país de Paymob seleccionado. Un cuadro Callbacks muestra la URL de callback con un botón Copy y un enlace al panel de Paymob del país seleccionado.

Paymob

Enable/Disable: Enable Paymob activa o desactiva el método de pago. Predeterminado: desactivado.

Title: el nombre del método de pago que ven los clientes en Finalizar compra. También es el nombre del método de pago guardado en el pedido. Predeterminado: Paymob.

Description: el texto que se muestra debajo del método de pago en Finalizar compra. Predeterminado: Pay securely by card or mobile wallet on the Paymob payment page. Déjalo vacío para no mostrar ningún texto.

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 integration ID 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 la página de pago, y la moneda del carrito debe ser la moneda de este país. Predeterminado: 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 online. 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 se crean como pagados solo a partir de callbacks firmados con este secreto.

El integration ID y el 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 API key y el HMAC secret guardados nunca se vuelven a mostrar. El campo queda vacío y muestra Saved — leave empty to keep it. Escribe un valor nuevo solo si quieres cambiarlo.

Clear saved secrets: marca API key o HMAC secret y haz clic en Save para eliminarlo. Un campo vacío mantiene el valor guardado.

Callbacks

Paymob informa de cada transacción a tu tienda. En el panel de Paymob abre Developers > Payment Integrations, elige tu integración, haz clic en Edit y configura Transaction processed callback y Transaction response callback con la URL que aparece en el cuadro Callbacks. Con URL amigables tiene este aspecto: https://your-shop/module/wcp_paymob_pay/callback, posiblemente con un código de idioma como /en/. La URL se genera en el idioma predeterminado de la tienda. Cópiala con el botón Copy. Configura las URL en cada integración que uses, incluida la de prueba.

El transaction processed callback lo envía el servidor de Paymob. El transaction response callback devuelve al cliente a tu tienda. Ambos van firmados con tu HMAC secret y el módulo los verifica. Los callbacks sin 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. El callback del servidor funciona mientras la tienda está en modo de mantenimiento y no lo bloquea la restricción de países de tu tienda.

Avanzado

Debug log: escribe los pasos de pago y los callbacks en logs/paymob_p_debug.log.php, dentro de la carpeta del módulo. El archivo no se puede abrir desde la web. Los errores y los callbacks rechazados siempre se registran, aunque esté desactivado. Las claves, los tokens y los datos de los clientes nunca se escriben. Predeterminado: 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 el módulo se borran los ajustes del módulo y el registro. Los IDs de Paymob guardados para los pedidos (intentos de pago) y los estados de pedido siempre se conservan. Predeterminado: desactivado.

Finalizar compra

En el paso de pago el cliente elige el método de pago (por defecto Paymob) y confirma. El módulo registra un nuevo pedido de Paymob por el total del carrito en la moneda del carrito, envía a Paymob el nombre, el correo electrónico, el teléfono y la dirección de facturación del cliente, 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. En este punto todavía no existe ningún pedido.

Tras pagar, el cliente vuelve a tu tienda. El pedido se marca como pagado solo cuando Paymob lo confirma con una transacción firmada. Entonces se crea el pedido y el cliente ve la página estándar de confirmación del pedido. Un pago pendiente (por ejemplo en efectivo o en quiosco) o un pago autorizado también crea el pedido, en un estado de espera, y lleva a la página de confirmación.

Si el pedido se está confirmando en ese mismo momento mediante el callback de Paymob, el cliente ve una página con 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. Para 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 un botón Back to checkout.

Si el pago fue rechazado, el cliente vuelve a Finalizar 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. 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 Paymob no puede iniciar el pago, el cliente se queda en Finalizar compra con un mensaje breve, 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.

El módulo admite pagos únicos en la página de Paymob. No tiene tarjetas guardadas, suscripciones, formulario de tarjeta integrado en tu sitio ni reembolsos desde el back office.

Pedidos

Estados de pedido

No order yet: el cliente fue enviado a Paymob y no ha pagado, el pago fue rechazado o Paymob todavía no ha confirmado el pago. Solo existe el carrito.

Payment accepted: Paymob confirmó el pago. El pago se registra con el ID de transacción de Paymob como ID de transacción, y una nota muestra la transacción, el importe y el tipo de tarjeta con las últimas cuatro cifras.

Awaiting Paymob payment: el pago está pendiente en Paymob, por ejemplo un pago en efectivo o en quiosco. El pedido pasa a Payment accepted cuando Paymob confirma el pago.

Paymob payment on hold: Paymob solo autorizó el importe y no lo ha capturado (captúralo en el panel de Paymob; el pedido pasa a Payment accepted cuando llega el callback de captura); o el importe o la moneda pagados no coinciden con el carrito (por ejemplo, el carrito se cambió después de iniciar el pago); o llegó un pago para un pedido que se había cancelado. La nota explica el motivo. Revisa el pedido y procésalo, o reembolsa el pago en el panel de Paymob.

Si llega un segundo pago correcto para un pedido que ya está pagado, el pedido no cambia. Una nota te pide que reembolses el duplicado en el panel de Paymob. Un pago para un pedido cancelado que antes estaba pagado, o para un pedido reembolsado, solo añade una nota: el pedido no se reabre. Un pago rechazado para un pedido que todavía no está pagado solo añade una nota.

Bloque de pago de Paymob

La página del pedido muestra un bloque Paymob payment con cada intento de Paymob del pedido: el pedido de Paymob, el ID de pedido del comerciante y el país, el ID de transacción de Paymob, el estado, el importe solicitado, el importe que Paymob informa con la tarjeta y el mensaje de Paymob. Debajo están las Notes del módulo para este pedido.

Reembolsos

Los reembolsos desde el back office no se admiten. 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, por ejemplo su estado o una nota de crédito.

Clave de licencia

El módulo funciona con una clave de licencia de VibeFox de vibefox.net. El bloque de licencia License — VibeFox Paymob Pay es el primer bloque de Modules > Module Manager > VibeFox Paymob Pay > Configure, encima de los ajustes. Introduce la clave en License key y haz clic en Activate. Después, el bloque muestra la clave enmascarada, el estado (por ejemplo, la fecha hasta la que la licencia está activa y tu dominio) y los botones Check now para volver a comprobar el estado, Change key para introducir otra clave y Remove key para eliminar la clave de esta tienda. Debajo están la línea Product: presta-payment-paymob y el enlace Manage licenses and domains in your account, que abre tu cuenta de vibefox.net. Solo los empleados con el permiso Configure para el módulo pueden cambiar la clave. Los textos del bloque siguen el idioma del back office (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 está accesible, el módulo sigue funcionando con el último estado conocido.

Una clave funciona en un dominio: el dominio de la tienda principal, también en una configuración multitienda. 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 Finalizar compra. Si de todos modos se inicia un pago, el cliente ve This payment method is not available. Please choose another one. La tienda de PrestaShop no sabe que has iniciado sesión en el back office, así que el método de pago también se oculta para ti: puedes configurar el módulo antes de comprar una clave, pero no probarlo en Finalizar compra. Aparece un recordatorio en Modules > Module Manager, en la pestaña Alerts. Los pedidos existentes no se ven afectados: los pagos ya iniciados se siguen confirmando.

Cuando una licencia caduca, el módulo sigue funcionando, pero las actualizaciones y el soporte requieren una renovación. El estado se vuelve a comprobar automáticamente mientras trabajas en el back office: 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 se necesita ninguna tarea cron. Desinstalar o restablecer el módulo elimina siempre la clave de licencia y el estado de la licencia.

Solución de problemas

Paymob no aparece en Finalizar compra: comprueba que la licencia está activa, que Enable/Disable está activado, que los cuatro valores (API key, integration ID, iFrame ID, HMAC secret) están rellenados y que la moneda del carrito es la moneda del Paymob country seleccionado. La página de ajustes muestra un aviso cuando falta algo. En Payment > Preferences comprueba que el módulo está permitido para la moneda del carrito, el país del cliente y el grupo del cliente.

El pago se completó, pero no se creó ningún pedido: 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 aparece en el cuadro 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 cuando Debug log está desactivado. Mira el campo Log en la página del módulo.

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

Callback responde Not configured: el HMAC secret está vacío. Introduce el secreto; Paymob volverá a intentar el callback.

Callback responde locked o retry: el pedido estaba siendo actualizado por otra solicitud en el mismo momento, por ejemplo el retorno del cliente, o no se pudo crear el pedido (por ejemplo, porque el módulo está desactivado). Paymob volverá a intentar el callback. El motivo se escribe en el registro.

Abrir la URL del callback en el navegador lleva a Finalizar compra con el mensaje could not verify: es normal. La URL acepta solo solicitudes firmadas de Paymob.

El cliente ve un error al elegir Paymob: activa Debug log y revisa el registro. Paymob payments are temporarily unavailable significa una API key incorrecta o un valor que falta. Paymob could not start the payment significa que Paymob rechazó la solicitud, por ejemplo por un integration ID 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 carrito no es la moneda del país de Paymob seleccionado.

El pedido está en Paymob payment on hold o en Awaiting Paymob payment tras el pago: lee las notas del bloque Paymob payment. 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 coincidieron, o el pago llegó después de que se cancelara el pedido.

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

Desinstalación

Ve a Modules > Module Manager, abre el menú junto a VibeFox Paymob Pay y elige Uninstall. La clave de licencia y el estado de la licencia de este módulo siempre se eliminan. Si Clean uninstall está activado, se borran los ajustes del módulo y el registro. Si está desactivado, todos los ajustes se conservan para una reinstalación posterior. Los intentos de pago de Paymob de los pedidos y los estados de pedido Awaiting Paymob payment y Paymob payment on hold siempre se conservan. Los pedidos existentes conservan sus notas de pago, IDs de transacción e IDs de Paymob.

Paymob es una marca comercial de su respectivo titular. Este módulo no está afiliado ni respaldado por Paymob.