VibeFox Conekta 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: la moneda de la tienda debe ser MXN o USD. Para otras monedas, el método de pago se oculta.
Cuenta de Conekta: necesitas las claves privadas de la API de tu cuenta de Conekta (de prueba y de producción) y un webhook en el panel de Conekta (ver Configuración). Solo se usan las claves privadas. La clave pública no es necesaria, porque el pago se realiza en la página de pago alojada de Conekta.
Clave de licencia de VibeFox: se compra en vibefox.net. Una clave funciona en un solo 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_conekta_gateway a /wp-content/plugins/ por FTP.
2. Haz clic en Activate.
3. Abre los ajustes: WooCommerce > Settings > Payments > Conekta > Manage, o haz clic en Settings debajo del nombre del plugin en la página de 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. Introduce tus claves privadas de prueba y de producción, elige el modo y añade el webhook en el panel de Conekta (ver Configuración).
6. Activa Enable / Disable y guarda. Haz un pago de prueba en modo de prueba y luego desmarca Test mode.
Configuración
Todos los ajustes están en una sola página: WooCommerce > Settings > Payments > Conekta. Encima de los campos, la página te avisa cuando Conekta está activado pero la clave privada del modo actual está vacía (en ese caso el método de pago se oculta en la finalización de compra) y cuando la moneda de la tienda no es MXN ni USD. Mientras el modo de prueba está activado, muestra Test mode is on: payments are simulated with the test private key. Al guardar una pasarela activada sin la clave del modo actual, aparece un mensaje de error que te pide introducirla.
General
Enable / Disable: Enable Conekta payments activa o desactiva el método de pago. Por defecto: desactivado.
Title: el nombre del método de pago que ve el cliente en la finalización de compra. Por defecto: Conekta.
Description: el texto que se muestra debajo del método de pago en la finalización de compra. Por defecto: Pay securely with card, OXXO cash or SPEI transfer. You will be redirected to Conekta to complete your payment.
Payment methods: los métodos que se ofrecen en la página de pago de Conekta. Por defecto: tarjeta, efectivo y transferencia bancaria. El efectivo, SPEI y BNPL están disponibles solo para pedidos en MXN (los pedidos en USD solo admiten tarjetas) y deben estar activados en tu cuenta de Conekta. Si no se selecciona nada, se usa la tarjeta.
Claves API
Copia tus claves privadas desde el panel de Conekta en Developers > API keys. Las claves de prueba y de producción son distintas.
Test mode: Enable test mode usa la clave privada de prueba. No se cobra dinero real y en la finalización de compra aparece el distintivo TEST MODE. Los reembolsos siempre usan la clave del modo en el que se hizo el pago. Por defecto: activado.
Test private key: la clave privada de la API del modo de prueba de tu cuenta de Conekta.
Live private key: la clave privada de la API del modo de producción de tu cuenta de Conekta. Mantenla en secreto.
Cada pedido de Conekta recuerda su modo: las notificaciones y los reembolsos usan la clave correspondiente. Mantén ambas claves rellenadas mientras haya pedidos de prueba antiguos abiertos.
Webhook
El webhook informa a tu tienda de los pagos realizados después de que el cliente salió de la página de Conekta, por ejemplo los pagos en OXXO o SPEI. En el panel de Conekta ve a Developers > Webhooks y añade la URL que aparece en esta sección, tanto para el modo de prueba como para el de producción. Tiene este aspecto: https://your-site/wc-api/webhook_wc_conekta/.
Selecciona estos eventos:
El cuerpo del webhook solo indica al plugin qué pedido de Conekta cambió. Cada notificación se verifica volviendo a leer el pedido desde la API de Conekta con la clave privada de su modo; la cabecera de firma Digest del webhook no se usa. Las notificaciones de pedidos de Conekta que esta tienda no creó para ese pedido se aceptan y se ignoran. Sin el webhook, un pedido solo se confirma cuando el cliente vuelve a la tienda tras pagar, o en el siguiente intento de pago del mismo pedido.
Avanzado
Debug log: Log API calls and notifications escribe los detalles en WooCommerce > Status > Logs, origen wcp_conekta_gateway. Los errores siempre se registran. Los registros nunca contienen claves API ni datos de contacto de clientes. Por defecto: desactivado.
Delete data on uninstall: Remove the settings, Conekta order references and logs when the plugin is deleted. Por defecto: desactivado.
Finalización de compra
El cliente elige el método de pago (por defecto Conekta) y realiza el pedido. El plugin crea un pedido de Conekta por el total del pedido en la moneda del pedido, con los artículos, el envío, los impuestos y los descuentos, y envía al cliente a la página de pago alojada de Conekta. Allí el cliente paga con uno de los métodos permitidos.
Tras pagar, el cliente vuelve a tu tienda. El pedido se marca como pagado solo cuando Conekta lo confirma: el plugin lee el pedido desde la API de Conekta cuando llega el webhook y cuando el cliente vuelve. Si el pago todavía no se puede confirmar, la página de pedido recibido muestra We are confirming your payment with Conekta. The order will be updated automatically — please do not pay again. Cuando el cliente eligió OXXO o SPEI y recibió una referencia de pago, el pedido pasa a «En espera» y la página muestra Your Conekta payment reference has been issued. The order will be confirmed as soon as the payment is received.
Si el pago es rechazado, el pedido se marca como «Fallido» y el cliente vuelve a la página Pay for order con The Conekta payment was not completed. Please try again or choose another payment method. Si la página de pago caducó o se canceló, el cliente ve The Conekta payment has expired or was cancelled. Please place the order again. Cuando el cliente vuelve a pagar un pedido, se reutiliza una página de pago abierta de Conekta con el mismo importe; si no, la anterior se cancela en Conekta antes de crear una nueva, de modo que un enlace antiguo no pueda pagarse dos veces. Si la página anterior ya estaba pagada, el pago se registra en lugar de volver a cobrarlo.
Si Conekta no puede iniciar el pago, el cliente ve un mensaje breve, por ejemplo The payment could not be started. Please try again in a moment or choose another payment method. El motivo técnico se escribe en el registro.
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). Los textos están traducidos al español (México).
El plugin solo acepta pagos en la página de Conekta. No tiene formulario de tarjeta en tu página de finalización de compra, ni tarjetas guardadas, suscripciones, preautorización y captura, ni pagos a plazos mensuales (MSI).
Pedidos y reembolsos
Estados del pedido
Pending payment: el cliente fue enviado a Conekta y todavía no ha pagado. La nota del pedido muestra el pedido de Conekta y el modo.
Processing: Conekta confirmó el pago con el mismo importe y la misma moneda (los pedidos con solo productos virtuales descargables pasan a «Completado», el valor predeterminado de WooCommerce). La nota del pedido muestra el método de pago (por ejemplo, la marca de la tarjeta y sus cuatro últimos dígitos, OXXO / efectivo o transferencia SPEI), el pedido de Conekta y el cargo. El ID de transacción del pedido es el ID del cargo de Conekta.
On hold, waiting for OXXO or SPEI: el cliente recibió una referencia de pago. El pedido pasa a «Procesando» cuando Conekta informa del pago.
On hold after payment: el importe o la moneda recibidos de Conekta no coinciden con el pedido, llegó un pago de modo de prueba mientras la tienda estaba en modo de producción (no se cobró dinero real) o el pago llegó para un pedido que ya estaba cancelado. La nota del pedido lo explica. Revisa el pago y después completa el pedido o reembólsalo. Un pedido que en Conekta solo está preautorizado también pasa a «En espera», con una nota para capturarlo o anularlo en el panel de Conekta.
Failed: el pago fue rechazado. La nota muestra el motivo. El cliente puede volver a pagar.
Cancelled: la página de pago actual de Conekta caducó o se canceló.
Un pedido pagado o reembolsado nunca se degrada ni se vuelve a abrir. Si llega otro pago de Conekta para un pedido que ya está pagado, una nota WARNING te pide reembolsarlo en el panel de Conekta.
Reembolsos
Abre el pedido, haz clic en Refund, introduce el importe y haz clic en Refund via Conekta (el botón muestra el título del método de pago). Se admiten reembolsos totales y parciales. El reembolso va al pedido de Conekta que contiene el pago y usa la clave del modo en el que se hizo el pago, por lo que esa clave debe estar configurada. Si Conekta 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 importe, el modo, el pedido de Conekta, el ID del reembolso y el motivo.
Los reembolsos hechos en el panel de Conekta llegan mediante el webhook y se añaden como nota con el importe reembolsado en Conekta y en WooCommerce. No se registran automáticamente como reembolsos de WooCommerce. Regístralos manualmente sin usar Refund via Conekta. Un contracargo notificado por Conekta también se añade como nota.
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 > Conekta. 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 solo dominio. Quitar la clave de un sitio no libera su plaza de dominio. Libera la plaza en tu cuenta de vibefox.net.
Sin una clave activa, Conekta no se muestra a los clientes en la finalización de compra. Si de todos modos se inicia un pago, el cliente ve This payment method is not available. Please choose another one. Los administradores de la tienda que hayan iniciado sesión siguen viendo el método de pago, marcado con (unlicensed — visible to admins only), para que puedas configurar y probar el plugin antes de comprar una clave. Un recordatorio aparece en la página de 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 renovación. El estado se vuelve a comprobar automáticamente en segundo plano.
Solución de problemas
Conekta no aparece en la finalización de compra: comprueba que la licencia esté activa, que Enable / Disable esté activado, que la clave privada del modo actual esté rellenada (Test private key en modo de prueba, Live private key en modo de producción) y que la moneda de la tienda sea MXN o USD. La página de ajustes muestra un aviso para cada una de estas condiciones.
El pago se realizó, pero el pedido sigue en Pending payment: el webhook no funciona. En el panel de Conekta comprueba que el webhook exista para el modo que usas (prueba o producción), que su URL sea exactamente la que aparece en los ajustes y que estén seleccionados los eventos. Comprueba que la clave privada de ese modo esté configurada, porque cada notificación se verifica con ella. El pedido también se confirma cuando el cliente vuelve a la tienda o cuando intenta pagar de nuevo el mismo pedido.
El webhook responde Temporarily unavailable: no se pudo contactar con la API de Conekta, falta la clave privada del modo del pedido, o el pedido lo estaba procesando otra solicitud. Conekta reintenta el webhook.
El webhook responde Verification failed, Invalid payload o Invalid order id: la API de Conekta no confirmó el pedido, o la notificación no era un evento de pedido de Conekta válido.
El webhook responde Ignored: la notificación pertenece a un pedido de Conekta que esta tienda no creó para ese pedido (por ejemplo, otra tienda o un enlace de pago de la misma cuenta), o a un objeto distinto de un pedido.
El cliente ve el mensaje We could not check the status of your previous payment attempt: no se pudo leer la página de pago de Conekta anterior del pedido, así que no se crea una nueva para evitar un doble pago. Vuelve a intentarlo en un momento.
El cliente ve el mensaje Payment gateway is not configured: falta la clave privada del modo actual.
El pedido está en On hold: lee las notas del pedido. El cliente todavía no ha pagado la referencia de OXXO o SPEI, el importe o la moneda no coincidieron, o llegó un pago de modo de prueba mientras la tienda estaba en modo de producción.
El reembolso falla con un mensaje sobre el modo de prueba o de producción: el pago se hizo en ese modo y su clave privada 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 una plaza en tu cuenta de vibefox.net y haz clic en Check now. Si cambió la dirección del sitio, haz clic en Check now para activar la clave en el nuevo dominio. Si no se puede contactar con el servidor de licencias, el plugin sigue funcionando con el último estado conocido.
Para desarrolladores, el readme incluye el filtro wc_ckt_supported_currencies para la lista de monedas.
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, las referencias de Conekta guardadas en los pedidos y los registros se eliminan solo si Delete data on uninstall estaba activado. Si no, se conservan para una reinstalación posterior. Los pedidos existentes conservan sus notas de pago y sus ID de transacción.
Conekta es una marca comercial de su respectivo titular. Este plugin no está afiliado a Conekta ni recibe su respaldo.