VibeFox PayMongo for WooCommerce — Ayuda

Requisitos

WordPress: 6.0 o posterior.

WooCommerce: 8.0 o posterior, instalado y activo. El plugin no se activa sin él.

PHP: 8.0 o posterior.

Moneda: peso filipino (PHP). El método de pago se oculta cuando la moneda de la tienda, o la moneda del pedido en la página Pay for order, no es PHP.

Cuenta de PayMongo: necesitas las claves API secretas de tu cuenta de PayMongo y un webhook para cada modo (consulta Configuración). Solo se usan las claves secretas (sk_test_..., sk_live_...) y los secretos de firma de los webhooks (whsk_...). Las claves públicas no son necesarias, 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 WordPress, ve a Plugins > Add New > Upload Plugin, elige el archivo ZIP del plugin y haz clic en Install Now. También puedes subir la carpeta wcp_paymongo_payment_gateway a /wp-content/plugins/ por FTP.

2. Haz clic en Activate.

3. Abre los ajustes: WooCommerce > Settings > Payments > PayMongo > Manage, o haz clic en Settings debajo del nombre del plugin en la página Plugins.

4. Introduce tu clave de licencia de VibeFox en el bloque de licencia de la parte superior de la página y haz clic en Activate.

5. Pega tus claves secretas de PayMongo, crea los webhooks y pega sus secretos de firma (consulta Configuración).

6. Selecciona los métodos de pago, activa Enable/Disable y guarda. Prueba un pago con Test mode activado y, después, desactívalo.

Configuración

Todos los ajustes están en una sola página: WooCommerce > Settings > Payments > PayMongo. Encima de los campos, la página te avisa cuando la moneda de la tienda no es PHP, cuando el modo actual no tiene clave secreta (entonces PayMongo no se muestra en la finalización de compra) o no tiene secreto de webhook (entonces los pagos solo se confirman cuando el cliente regresa), y muestra Test mode is on: no real payments are made. mientras el modo de prueba esté activado. En la lista de métodos de pago, PayMongo aparece marcado como pendiente de configuración hasta que el modo actual tenga una clave secreta.

General

Enable/Disable: Enable PayMongo 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. Por defecto: PayMongo (Card, GCash, GrabPay, Maya).

Description: el texto que se muestra debajo del método de pago en la finalización de compra. Por defecto: 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 pago de PayMongo. Selecciona solo los métodos activados en tu cuenta de PayMongo; de lo contrario, PayMongo rechaza la finalización de compra. Por defecto: 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 por 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. Por defecto: activado. Desactívalo para aceptar 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_.

Webhook

El webhook informa a tu tienda de que se ha realizado un pago, también cuando el cliente cierra el navegador tras 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 esta sección de la configuración. Tiene este aspecto: https://your-site/?wc-api=paymongo_p_webhook.

Selecciona estos eventos:

Copia el secreto de firma (whsk_...) de cada webhook en Test webhook secret o en Live webhook secret. Los webhooks sin firma válida se rechazan, y el modo del evento debe coincidir con el modo de la firma. Cada evento se vuelve a comprobar mediante la API de PayMongo antes de cambiar el pedido. PayMongo envía los eventos de toda la cuenta a cada webhook; los eventos de pagos que no crea esta tienda se ignoran. Sin el webhook, los pagos solo se confirman cuando el cliente regresa a tu tienda.

Pedidos

Estado del pedido tras el pago: el estado que se asigna al pedido tras un pago correcto. El estado se asigna de inmediato, sin un segundo cambio de estado.

Avanzado

Debug log: Log API calls and webhook events las escribe en WooCommerce > Status > Logs, origen wcp_paymongo_payment_gateway. Los errores siempre se registran. Las claves y los datos de los clientes nunca se registran. Por defecto: desactivado.

Delete data on uninstall: Delete the settings and logs when the plugin is deleted. Los ID de PayMongo guardados en los pedidos se conservan, porque se necesitan para reembolsos y contabilidad. Por defecto: desactivado.

Finalización de compra

El cliente elige el método de pago (por defecto, PayMongo (Card, GCash, GrabPay, Maya)) y realiza el pedido. En modo de prueba, la finalización de compra muestra Test mode: no real payment will be made. El plugin crea una sesión de pago de PayMongo por el total del pedido en PHP, con una línea Order # y el número de pedido, y envía al cliente a la página de pago de PayMongo. El nombre, el correo electrónico, el teléfono y la dirección de facturación del cliente se transmiten a PayMongo. Allí el cliente elige uno de los métodos seleccionados y paga.

El método de pago solo se muestra para pedidos de al menos ₱100.00. Un importe total menor no puede pagarse con PayMongo.

Después de pagar, el cliente vuelve a la página de pedido recibido de tu tienda. El pedido solo se marca como pagado cuando PayMongo lo confirma: el plugin consulta a la API de PayMongo sobre el pago cuando el cliente regresa y cuando llega el webhook. Si PayMongo sigue procesando el pago o no se puede contactar con él, el cliente llega igualmente a la página de pedido recibido, y el webhook completa el pedido más tarde.

Si el cliente cancela en la página de PayMongo o no termina el pago, llega a la página Pay for order con el mensaje 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 pedido sigue sin pagar. Un nuevo intento primero comprueba el anterior: si entretanto se pagó, el pedido se completa sin un nuevo pago; si no, el enlace de pago anterior de PayMongo caduca, de modo que el cliente no 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 ve 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 añade a las notas del pedido.

El método de pago funciona en la finalización de compra clásica, en el bloque de Finalizar compra y en la página Pay for order. Es compatible con WooCommerce High-Performance Order Storage (HPOS).

El plugin acepta pagos únicos en la página de PayMongo. No tiene campos de tarjeta en tu propia página de pago, ni tarjetas guardadas, ni suscripciones o pagos recurrentes, ni pagos a plazos, ni autorización y captura por separado.

Pedidos y reembolsos

Estados del pedido

Pending payment: el cliente fue enviado a PayMongo y aún no ha pagado, o PayMongo aún no ha confirmado el pago. Una nota registra cada sesión de pago de PayMongo creada para el pedido. Mientras PayMongo procesa un pago, una nota lo indica.

Processing or Completed: el pago fue confirmado. El estado sigue a Order status after payment. La nota del pedido muestra el pago de PayMongo, el importe, el método y el modo. El ID de transacción es el ID de pago de PayMongo (pay_...). La pantalla del pedido muestra la sesión de pago, la intención de pago y el modo de PayMongo debajo de la dirección de facturación.

On hold: el importe o la moneda pagados no coinciden con el pedido (nota amount/currency mismatch); o se realizó un pago en modo de prueba mientras la tienda está en modo real, así que no se recibió dinero; o el pago llegó después de que el pedido se hubiera cancelado, por ejemplo por el tiempo de espera de la reserva de stock. La nota del pedido lo explica. Revisa el pedido y procésalo o reembolsa el pago.

Failed: un webhook de payment.failed firmado informó de que el último intento de pago de un pedido pendiente falló. La nota muestra el código y el mensaje de error de PayMongo. El cliente puede volver a pagar.

Si llega un segundo pago para un pedido que ya está pagado, por ejemplo por un enlace de pago antiguo, el pedido no cambia. Una nota te pide que reembolses el pago duplicado en el panel de PayMongo. Un pedido cancelado o reembolsado que había sido pagado nunca se reabre.

Reembolsos

Abre el pedido, haz clic en Refund, introduce el importe y haz clic en Refund via PayMongo (Card, GCash, GrabPay, Maya) (el botón muestra el título de tu método de pago). Se admiten reembolsos totales y parciales. 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. Si PayMongo no acepta el reembolso, WooCommerce muestra el error y no se registra ningún reembolso. Un reembolso correcto se añade a las notas del pedido con el ID y el estado del reembolso de PayMongo.

Los reembolsos realizados en el panel de PayMongo no se copian a WooCommerce. Reembolsa desde el pedido de WooCommerce o crea un reembolso manual en WooCommerce.

Clave de licencia

El plugin funciona con una clave de licencia de VibeFox de vibefox.net. El bloque de licencia está en la parte superior de WooCommerce > Settings > Payments > PayMongo. Pega la clave en License key y haz clic en Activate. El bloque muestra el estado, por ejemplo la fecha hasta la que la licencia está activa, y tu dominio. Usa Check now para volver a comprobar el estado, Change key para introducir otra clave y Remove key para quitarla de este sitio. El enlace Manage licenses and domains in your account abre tu cuenta de vibefox.net.

Una clave funciona en un dominio. Quitar la clave de un sitio no libera su espacio de dominio. Libéralo en tu cuenta de vibefox.net.

Sin una clave activa, PayMongo no se muestra a los clientes en la finalización de compra. Si se inicia un pago de todos modos, el cliente ve This payment method is not available. Please choose another one. Los gestores de la tienda que han iniciado sesión siguen viendo el método de pago, marcado como (unlicensed — visible to admins only), para que puedas configurar y probar el plugin antes de comprar una clave. Un aviso aparece en la página Plugins y en las páginas de WooCommerce. Los pedidos existentes no se ven afectados: los pagos ya iniciados siguen confirmándose y los reembolsos funcionan.

Cuando una licencia caduca, el plugin sigue funcionando, pero las actualizaciones y el soporte requieren una renovación. El estado se vuelve a comprobar automáticamente en segundo plano.

Solución de problemas

PayMongo no aparece en la finalización de compra: comprueba que la licencia esté activa, que Enable/Disable esté activado, que el modo actual tenga una clave secreta (Test secret key en modo de prueba, Live secret key en modo real), que la moneda de la tienda sea PHP y que el total del pedido sea de al menos ₱100.00. Los desarrolladores pueden cambiar el mínimo con el filtro paymongo_p_minimum_amount.

El pago se realizó, pero el pedido sigue en Pendiente de pago: 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 los ajustes 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 pertenezca al modo correcto.

El webhook responde Temporary error: no se pudo verificar el pago a través de la API de PayMongo, o el pedido lo estaba procesando otra petición al mismo tiempo. PayMongo vuelve a intentar el webhook automáticamente.

El valor no se guardó: se pegó una clave 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 realizar el pedido: abre las notas del pedido o consulta WooCommerce > Status > Logs, origen wcp_paymongo_payment_gateway. 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 la finalización de compra; elimínalo de Payment methods.

Pagos de prueba en una tienda real: un pago de prueba que llega mientras la tienda está en modo real pone el pedido en espera 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á On hold tras el pago: lee la nota del pedido. El importe o la moneda pagados no coincidían con el pedido, el pago era de prueba o llegó después de que el pedido se cancelara. Procesa 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 y vuelve a intentarlo.

El bloque de licencia muestra un error: sigue el mensaje del bloque. Por ejemplo, si la clave ya se usa en otro dominio, libera un espacio en tu cuenta de vibefox.net y haz clic en Check now. Si la dirección del sitio cambió, haz clic en Check now para activar la clave en el nuevo dominio. Si no se puede acceder al servidor de licencias, el plugin sigue funcionando con el último estado conocido.

Desinstalación

Desactivar el plugin conserva todos los datos. Para eliminarlo, desactívalo y bórralo en la página Plugins. La clave de licencia y el estado de licencia de este plugin siempre se eliminan. Los ajustes de la pasarela, los datos temporales y los registros solo se eliminan si Delete data on uninstall estaba activado; en caso contrario, se conservan para una reinstalación posterior. Los pedidos existentes conservan sus notas de pago, los ID de transacción y los ID de PayMongo.

PayMongo es una marca comercial de su respectivo propietario. Este plugin no está afiliado a PayMongo ni cuenta con su respaldo.