VibeFox PayMongo for PrestaShop — Ayuda
Requisitos
PrestaShop: 8.0 a 9.x.
PHP: 8.0 o posterior. El módulo se niega a instalarse en versiones anteriores de PHP.
Moneda: peso filipino (PHP). PayMongo solo se muestra en el checkout para carritos en PHP. Si la moneda predeterminada de tu tienda no es PHP, la página de configuración te avisa, y los clientes deben cambiar a PHP para ver PayMongo.
Cuenta de PayMongo: necesitas las claves API secretas de tu cuenta de PayMongo y un webhook para cada modo (ver Configuración). Solo se usan las claves secretas (sk_test_..., sk_live_...) y los secretos de firma de los webhooks (whsk_...). No se necesitan las claves públicas, porque la página de pago la aloja PayMongo. Los métodos de pago que ofrezcas deben estar activados en tu cuenta de PayMongo.
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 VibeFox PayMongo Payment Gateway más tarde en la lista de módulos y haz clic en Configure.
3. Introduce tu clave de licencia de VibeFox en el campo License key del bloque de licencia de la parte superior de la página Configure y haz clic en Activate (ver Clave de licencia).
4. Pega tus claves secretas de PayMongo, crea los webhooks en PayMongo y pega sus secretos de firma (ver Configuración).
5. Selecciona los métodos de pago, activa Enable/Disable y haz clic en Save. Prueba un pago con Test mode activado y después desactívalo.
Al instalar, el módulo crea dos estados de pedido: Awaiting PayMongo payment y PayMongo payment on hold. En Payment > Preferences comprueba que el módulo está permitido para el peso filipino, los países de tus clientes y sus grupos de clientes.
Configuración
Todos los ajustes están en la página del módulo: Modules > Module Manager > VibeFox PayMongo Payment Gateway > Configure. Cada sección tiene su propio botón Save, que guarda toda la página. Encima de los campos, la página te avisa cuando la moneda predeterminada de la tienda no es PHP, cuando el modo actual no tiene clave secreta (entonces PayMongo no se muestra en el checkout) o no tiene secreto de firma del webhook (entonces los pagos solo se confirman cuando el cliente vuelve a tu tienda), y muestra Test mode is on: no real payments are made. mientras el modo de prueba esté activado.
PayMongo
Enable/Disable: Enable PayMongo activa o desactiva el método de pago. Predeterminado: desactivado.
Title: el nombre del método de pago que ve el cliente en el checkout. También es el nombre del método de pago que se guarda en el pedido. Predeterminado: PayMongo (Card, GCash, GrabPay, Maya). Obligatorio.
Description: el texto que se muestra debajo del método de pago en el checkout. Predeterminado: You will be redirected to PayMongo to pay securely with your card, GCash, GrabPay or Maya.
Payment methods: los métodos que se ofrecen en la página de checkout de PayMongo. Selecciona solo los métodos activados en tu cuenta de PayMongo; de lo contrario PayMongo rechaza el checkout. Si no se selecciona ninguno, se usan los predeterminados. Predeterminado: Cards, GCash, GrabPay and Maya.
Claves API
Copia las claves secretas desde PayMongo Dashboard > Developers > API keys. Las claves públicas no son necesarias. Cada clave debe empezar con el prefijo esperado. Un valor con un prefijo incorrecto no se guarda: la página muestra que el campo must start with el prefijo y que The previous value was kept.
Test mode: Enable test mode (no real payments). Los nuevos pagos usan las claves de prueba. Los pagos realizados antes conservan el modo en que se hicieron, de modo que las comprobaciones de estado y los reembolsos usan la clave correspondiente. Predeterminado: activado. Desactívalo para cobrar pagos reales.
Test secret key: la clave secreta del modo de prueba. Empieza por sk_test_.
Test webhook secret: el secreto de firma del webhook del modo de prueba. Empieza por whsk_.
Live secret key: la clave secreta del modo real. Empieza por sk_live_.
Live webhook secret: el secreto de firma del webhook del modo real. Empieza por whsk_.
Las claves y los secretos 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 una clave o un secreto y haz clic en Save para eliminarlo. Un campo vacío conserva el valor guardado.
Webhook
El webhook avisa a tu tienda de que se ha realizado un pago, también cuando el cliente cierra el navegador después de pagar. Crea un webhook en el panel de PayMongo (o mediante la API de PayMongo) para cada modo, de prueba y real, con la URL que aparece en Webhook URL en esta sección. Con URLs amigables tiene este aspecto: https://your-shop/module/wcp_paymongo_payment_gateway/webhook, posiblemente con un código de idioma como /en/. Copia la URL exactamente como aparece en la configuración.
Selecciona estos eventos (también aparecen en esta sección):
Copia el secreto de firma (whsk_...) de cada webhook en Test webhook secret o Live webhook secret. Los webhooks sin una firma válida se rechazan. La firma se comprueba con el secreto de su propio modo, y el modo del evento debe coincidir con él, de modo que un webhook de prueba nunca confirma un pago real. Cada evento se vuelve a comprobar a través de la API de PayMongo con la clave secreta del modo del pago antes de crear o modificar un pedido. PayMongo envía los eventos de toda la cuenta a cada webhook; los eventos de pagos que no se iniciaron en esta tienda se ignoran. Sin el webhook, el pedido solo se crea cuando el cliente vuelve a la tienda después de pagar.
Pedidos
Order status after payment: el estado del pedido que se asigna tras un pago correcto.
Los pagos que todavía se están procesando esperan en Awaiting PayMongo payment. Las discrepancias de importe o moneda y los pagos de prueba en una tienda en modo real siempre van a PayMongo payment on hold.
Avanzado
Debug log: registra las llamadas a la API de PayMongo y los eventos de webhook en logs/paymongo_p_debug.log.php, en la carpeta del módulo. El archivo no se puede abrir desde la web. Los errores y las advertencias siempre se registran, también cuando el interruptor está desactivado. Las claves y los datos de clientes nunca se registran. Predeterminado: desactivado.
Log: muestra el tamaño y las entradas más recientes del registro. Haz clic en Clear log para vaciarlo.
Delete data on uninstall: si está activado, al desinstalar el módulo se eliminan los ajustes y el registro. Los ID de PayMongo guardados para los pedidos, los reembolsos y los estados de pedido del módulo siempre se conservan, porque se necesitan para los reembolsos y la contabilidad. Predeterminado: desactivado.
Checkout
En el paso de pago, el cliente elige el método de pago (por defecto PayMongo (Card, GCash, GrabPay, Maya)) y ve su descripción. En modo de prueba, el checkout también muestra Test mode: no real payment will be made. PayMongo solo se ofrece para carritos en PHP con un total de al menos ₱100.00.
Después de confirmar, el módulo crea una Checkout Session de PayMongo por el total del carrito en PHP, con una línea Cart # y el número de carrito, y envía al cliente a la página de checkout de PayMongo. El nombre, el correo electrónico, el teléfono y la dirección de facturación del cliente se pasan a PayMongo. Allí el cliente elige uno de los métodos seleccionados y paga. En este momento todavía no existe ningún pedido.
Después de pagar, el cliente vuelve a tu tienda. El pedido se marca como pagado solo cuando PayMongo lo confirma: el módulo consulta a la API de PayMongo sobre el pago cuando el cliente regresa y cuando llega el webhook. Entonces se crea el pedido y el cliente ve la página estándar de confirmación del pedido con Your PayMongo payment has been received. Si PayMongo todavía está procesando el pago cuando el cliente regresa, el pedido se crea en Awaiting PayMongo payment y la página muestra PayMongo is still processing your payment. Your order will be updated as soon as PayMongo confirms it — please do not pay again. Si ese pago falla después, la página muestra Your PayMongo payment was not completed. Please contact us about this order. Si no se puede contactar con PayMongo cuando el cliente regresa, aparece una página de Payment confirmation que pide al cliente que no vuelva a pagar y muestra un botón Check again; el webhook crea el pedido en cuanto llega.
Si el cliente cancela en la página de PayMongo o no termina el pago, vuelve al checkout con You cancelled the PayMongo payment. You can try again or choose another payment method. o Your PayMongo payment was not completed. You can try again or choose another payment method. El carrito se conserva. Un nuevo intento comprueba primero el anterior: si entretanto se pagó, el pedido se crea sin un nuevo pago; si no, el enlace de pago de PayMongo anterior caduca, de modo que el carrito no se puede pagar dos veces. Mientras el pago anterior siga procesándose, el cliente ve Your previous PayMongo payment for this order is still being processed. Please wait a few minutes before trying again.
Si PayMongo no puede iniciar el pago, el cliente se queda en el checkout con un mensaje breve, por ejemplo The payment could not be started. Please try again or choose another payment method. o PayMongo could not be reached. Please try again in a moment. El motivo técnico se escribe en el registro.
El webhook funciona mientras la tienda está en modo de mantenimiento y no está bloqueado por la restricción de países de tu tienda.
El módulo acepta pagos únicos en la página de PayMongo. No tiene campos de tarjeta en tu propia página de checkout, ni tarjetas guardadas, ni suscripciones o pagos recurrentes, ni pagos a plazos, ni autorización y captura por separado.
Pedidos y reembolsos
Estados de pedido
No order yet: el cliente fue enviado a PayMongo y no ha pagado, o PayMongo todavía no ha confirmado el pago. Solo existe el carrito.
Payment accepted or Delivered: el pago fue confirmado. El estado sigue a Order status after payment. El pago se registra con el ID de pago de PayMongo (pay_...) como ID de transacción, y una nota muestra el pago, el importe, el método, el modo y cómo se confirmó (webhook o regreso).
Awaiting PayMongo payment: el cliente volvió mientras PayMongo todavía procesaba el pago. El pedido pasa al estado de pagado cuando PayMongo lo confirma.
PayMongo payment on hold: el importe o la moneda pagados no coinciden con el total del carrito (por ejemplo, el carrito se cambió en otra pestaña después de iniciar el pago); o se hizo un pago en modo de prueba mientras la tienda estaba en modo real, así que no se recibió dinero y no se registra ningún pago; o el pago llegó después de que el pedido se hubiera cancelado. La nota lo explica. Revisa el pedido y tramítalo o reembolsa el pago.
Payment error: un webhook firmado payment.failed indicó que el último intento de pago de un pedido en Awaiting PayMongo payment falló. La nota muestra el código y el mensaje de error de PayMongo. Si el mismo pago se completa más tarde, el pedido pasa al estado de pagado.
Refunded: el pago se reembolsó por completo a través del módulo.
Si llega un segundo pago para un pedido que ya está pagado, por ejemplo mediante un enlace de checkout antiguo, el pedido no cambia. Una nota te pide que reembolses el pago duplicado en el panel de PayMongo. Un pedido que se pagó y después se canceló o se reembolsó nunca se vuelve a abrir.
Bloque PayMongo payment
La página del pedido muestra un bloque PayMongo payment con el ID y el método del pago de PayMongo, el payment intent, el checkout, el modo, el estado, el importe pagado y el importe reembolsado, una insignia Test mode para los pagos de prueba, las notas de PayMongo del pedido y el historial de reembolsos.
Reembolsos
En el bloque PayMongo payment introduce el importe (se rellena el importe que aún no se ha reembolsado), opcionalmente un motivo, y haz clic en Refund via PayMongo. Confirma la pregunta Refund this amount through PayMongo? This cannot be undone. Se admiten reembolsos totales y parciales, con dos decimales como máximo. Necesitas el derecho a editar pedidos; no hace falta acceso a las páginas de Módulos. Los reembolsos se limitan al importe que PayMongo cobró realmente, de modo que tras una discrepancia de importe puedes reembolsar hasta lo que pagó el cliente, no el total del pedido. El reembolso se envía con la clave secreta del modo en que se hizo el pago (prueba o real), así que esa clave debe estar configurada. El motivo que introduces se envía a PayMongo como nota del reembolso. Si PayMongo no acepta el reembolso, el bloque muestra el error y no se registra ningún reembolso. Un reembolso correcto se añade al historial de reembolsos y a las notas, con el ID y el estado del reembolso de PayMongo. Un reembolso total pone el pedido en Refunded. Un reembolso parcial no cambia el estado.
El módulo no crea abonos. Los botones de reembolso estándar de PrestaShop en la página del pedido no devuelven dinero a través de PayMongo. Los reembolsos realizados en el panel de PayMongo no se copian a PrestaShop. Haz el reembolso desde el bloque del pedido o actualiza el pedido manualmente.
Clave de licencia
El módulo funciona con una clave de licencia de VibeFox de vibefox.net. El bloque de licencia License — VibeFox PayMongo Payment Gateway es el primer bloque de Modules > Module Manager > VibeFox PayMongo Payment Gateway > Configure, por 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 quitar la clave de esta tienda. Debajo están la línea Product: presta-payment-paymongo y el enlace Manage licenses and domains in your account, que abre tu cuenta de vibefox.net. Solo los empleados con el permiso Configure del 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 un hueco de dominio en tu cuenta, haz clic en Check now. Si no se puede contactar con el servidor de licencias, 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 hueco de dominio. Libéralo en tu cuenta de vibefox.net.
Sin una clave activa, PayMongo no se muestra a los clientes en el checkout. Si se inicia un pago de todos modos, el cliente ve This payment method is not available. Please choose another one. La tienda 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 el checkout. 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 y los reembolsos funcionan.
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 por semana. No se necesita ninguna tarea cron. Desinstalar o restablecer el módulo siempre elimina la clave de licencia y el estado de la licencia.
Solución de problemas
PayMongo no aparece en el checkout: comprueba que la licencia está activa, que Enable/Disable está activado, que el modo actual tiene una clave secreta (Test secret key en modo de prueba, Live secret key en modo real), que el carrito está en PHP y que el total es de al menos ₱100.00. 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 realizó, pero no se creó ningún pedido: el webhook no funciona y el cliente no volvió a la tienda. En el panel de PayMongo comprueba que existe un webhook en el modo que usas, que su URL es exactamente la que aparece en Webhook URL y que los tres eventos están seleccionados. Comprueba que su secreto de firma está en el campo correspondiente (Test webhook secret o Live webhook secret).
El webhook responde Invalid signature: falta el secreto de firma de ese modo o pertenece a otro webhook. Pega el secreto de firma del webhook en el campo de su modo.
El webhook responde Mode mismatch: un evento de prueba se firmó como real o al revés. Comprueba que cada webhook pertenece al modo correcto.
El webhook responde Temporary error: no se pudo comprobar el pago a través de la API de PayMongo, por ejemplo porque falta la clave secreta del modo del pago. PayMongo reintenta el webhook automáticamente.
El webhook responde Busy, retry: otra solicitud estaba confirmando el pedido en el mismo momento, o no se pudo crear el pedido (por ejemplo, porque el módulo está desactivado). PayMongo reintenta el webhook automáticamente. El motivo está en el Log.
El webhook responde Ignored: el evento pertenece a un pago que no se inició en esta tienda, o a otro modo. No se cambia nada.
La URL del webhook muestra Method not allowed en el navegador: es normal. La URL solo acepta solicitudes de PayMongo.
El valor no se guardó: una clave se pegó en el campo equivocado. Las claves secretas empiezan por sk_test_ o sk_live_, y los secretos de webhook por whsk_.
El cliente ve un error al elegir PayMongo: mira el campo Log en la página del módulo. Una clave secreta incorrecta da el mensaje de que el método de pago no está disponible temporalmente. Un método de pago que no está activado en tu cuenta de PayMongo hace que PayMongo rechace el checkout; elimínalo de Payment methods.
Pagos de prueba en una tienda en modo real: un pago de prueba que llega mientras la tienda está en modo real pone el pedido en PayMongo payment on hold con una nota que indica que no se recibió dinero. Los pagos reales siempre se reconocen, también después de volver al modo de prueba, y se reembolsan con la clave real.
El pedido está en PayMongo payment on hold tras el pago: lee las notas del bloque PayMongo payment (ver Estados de pedido) y después tramita el pedido o reembolsa el pago.
El reembolso falla con un mensaje sobre el modo: el pago se hizo en modo de prueba o real, y la clave secreta de ese modo no está configurada. Introdúcela e inténtalo de nuevo.
Los desarrolladores pueden modificar los datos de la Checkout Session con el hook actionPaymongoPCheckoutSessionData.
Desinstalación
Ve a Modules > Module Manager, abre el menú junto a VibeFox PayMongo Payment Gateway y elige Uninstall. La clave de licencia y el estado de la licencia de este módulo siempre se eliminan. Si Delete data on uninstall está activado, se eliminan los ajustes y el registro. Si está desactivado, todos los ajustes se conservan para una reinstalación posterior. Los ID de PayMongo de los pedidos, los reembolsos y los estados de pedido Awaiting PayMongo payment y PayMongo payment on hold siempre se conservan, de modo que los pedidos pagados antes se pueden reembolsar después de reinstalar. Los pedidos existentes conservan sus notas de pago e ID de transacción.
PayMongo es una marca comercial de su titular. Este módulo no está afiliado ni respaldado por PayMongo.