VibeFox OpenPay 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.
HTTPS: tu sitio debe usar HTTPS, porque el formulario de tarjeta está en tu página de finalización de compra.
Cuenta de OpenPay: una cuenta de OpenPay de México, Colombia o Perú. Necesitas su ID de comerciante, la clave privada (sk_...) y la clave pública (pk_...). Los paneles del sandbox y de producción tienen ID de comerciante y claves distintos, y el plugin los mantiene separados.
Clave de licencia de VibeFox: se compra en vibefox.net. Una clave funciona en un dominio.
La tarjeta se escribe en tu página de finalización de compra, pero el navegador la lee y la tokeniza con openpay.js. Los campos de la tarjeta no tienen nombre y nunca se envían a tu servidor. Como el formulario de tarjeta está en tu página, el alcance de tu PCI DSS es SAQ A-EP; consúltalo con tu adquirente.
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_openpay_gateway a /wp-content/plugins/ por FTP.
2. Haz clic en Activate.
3. Abre la configuración: WooCommerce > Settings > Payments > OpenPay > 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. Elige el Account country e introduce las claves de sandbox y de producción (consulta Configuración).
6. Recomendado: añade la URL del webhook en el panel de OpenPay (consulta Configuración).
7. Activa Enable / Disable y guarda. Prueba un pago con las tarjetas de prueba del sandbox de OpenPay y, después, desmarca Sandbox mode para cobrar pagos reales.
Configuración
Todos los ajustes están en una sola página: WooCommerce > Settings > Payments > OpenPay. Encima de los campos, la página te avisa cuando las claves del modo actual están incompletas (en ese caso el método de pago se oculta en la finalización de compra), cuando la moneda de la tienda no la acepta el país de la cuenta seleccionado, y muestra Sandbox mode is enabled — no real charges are made. mientras el modo sandbox está activo. En la lista de métodos de pago, OpenPay aparece como pendiente de configuración hasta que el modo actual tenga las tres claves, y se muestra una insignia de modo de prueba mientras el modo sandbox esté activo.
Al guardar, las claves se verifican. Un ID de comerciante solo puede contener letras y dígitos, una clave privada debe empezar por sk_ y una clave pública por pk_. Un valor no válido no se guarda: se conserva el valor anterior y aparece un error, por ejemplo Sandbox: The private key must start with sk_. Si el método de pago está activado pero las claves del modo actual están incompletas, también verás un mensaje indicando que la pasarela permanece oculta en la finalización de compra.
General
Enable / Disable: Enable OpenPay card payments 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: Credit or debit card (OpenPay).
Description: el texto que se muestra encima del formulario de tarjeta en la finalización de compra. Por defecto: Pay securely with your credit or debit card. Your bank may ask you to confirm the payment (3D Secure).
Cuenta de OpenPay
El ID de comerciante, la clave privada (sk_) y la clave pública (pk_) están en tu panel de OpenPay, en Settings (Configuración). La sección incluye enlaces a los paneles de sandbox y de producción de México, Colombia y Perú.
Account country: el país de tu cuenta de OpenPay. Determina la API de OpenPay, la biblioteca openpay.js de ese país y las monedas aceptadas. Por defecto: Mexico.
Sandbox mode: Use the OpenPay sandbox (test keys, no real charges) cambia tanto las claves como la API al sandbox. Mientras está activo, se muestra una insignia SANDBOX MODE en la finalización de compra. Por defecto: activado. Desmárcalo para cobrar pagos reales.
Sandbox Merchant ID: el ID de comerciante del panel sandbox, Settings (Configuración), claves de API.
Sandbox Private Key: la clave privada del sandbox. Empieza por sk_. Solo se usa en el servidor; nunca la compartas.
Sandbox Public Key: la clave pública del sandbox. Empieza por pk_. openpay.js la usa en el navegador para tokenizar la tarjeta.
Live Merchant ID: el ID de comerciante del panel de producción, Settings (Configuración), claves de API.
Live Private Key: la clave privada de producción (sk_...).
Live Public Key: la clave pública de producción (pk_...).
Las claves de la versión 1.0 del plugin (un solo juego de claves y un indicador de sandbox) se trasladan automáticamente a los campos de sandbox o de producción.
Webhook
El webhook no es obligatorio, pero se recomienda. Confirma los pagos cuando el cliente no regresa de la página de 3D Secure, por ejemplo si cierra el navegador. En el panel de OpenPay ve a Settings > Webhooks y añade la URL que aparece en esta sección de la configuración. Tiene este aspecto: https://your-site/wc-api/webhook_wc_openpay/. Cópiala exactamente como la muestran los ajustes. Añade el webhook en el panel de cada modo que uses (sandbox y producción).
Al añadir el webhook, OpenPay envía un código de verificación a esta URL. El código aparece en esta sección con la fecha en que llegó, para que puedas confirmar el webhook en el panel de OpenPay.
Selecciona estos eventos:
OpenPay no firma los webhooks, así que el plugin nunca confía en la notificación en sí. Solo la usa para localizar el cargo y luego lo lee de la API de OpenPay con la clave privada del modo en el que se pagó el pedido. Se ignora cualquier notificación de un cargo que esta tienda no creó.
Avanzado
Debug log: Log payment steps (errors are always logged) escribe los pasos del pago en WooCommerce > Status > Logs, origen wcp_openpay_gateway. Los errores y advertencias se registran aunque esté desactivado. Las claves, los datos de la tarjeta y los datos del cliente nunca se registran. Por defecto: desactivado.
Delete data on uninstall: Remove the gateway settings and logs when the plugin is deleted. Por defecto: desactivado.
Finalización de compra
El cliente elige el método de pago (por defecto Credit or debit card (OpenPay)) y completa Cardholder name, Card number, Expiry (MM/YY) y Card code (CVV). Al realizar el pedido, openpay.js convierte la tarjeta en un token de un solo uso en el navegador, y la biblioteca antifraude de OpenPay añade un ID de sesión del dispositivo. Solo estos dos valores se envían a tu tienda.
Después, el plugin crea el cargo con 3D Secure por el total del pedido en la moneda del pedido y envía al cliente a la página 3D Secure de su banco, servida por OpenPay. Cada intento recibe su propia referencia de pedido en OpenPay (el número de pedido y un sufijo corto). La descripción del cargo es Order #, el número de pedido y el nombre de tu sitio. El nombre, el correo electrónico y el teléfono del cliente se envían a OpenPay; no se crea ninguna cuenta de cliente en OpenPay. El pedido permanece en Pendiente de pago mientras el cliente está en la página 3D Secure.
Cuando el cliente regresa, el plugin lee el cargo de la API de OpenPay. El pedido se marca como pagado solo después de que OpenPay lo confirme: el cargo debe pertenecer a este pedido, estar completado y coincidir exactamente con el total y la moneda del pedido. Si todavía no se conoce el resultado, la página de pedido recibido muestra We are confirming your card payment with OpenPay. The order will be updated automatically — please do not pay again. Después, el webhook actualiza el pedido.
Si la tarjeta es rechazada o el 3D Secure falla, el cliente regresa a la página Pay for order con el mensaje The card payment was not completed (declined or 3-D Secure failed). Please try again or use another card. y puede volver a pagar. Antes de un nuevo intento, el plugin comprueba el cargo anterior del pedido: si en realidad estaba pagado, el pedido se marca como pagado sin un segundo cobro; si todavía se está procesando, el cliente ve que hay un pago anterior en curso y no debe volver a pagar; si no se puede comprobar su estado, no se hace ningún nuevo intento y se pide al cliente que lo intente de nuevo en unos minutos.
Las tarjetas rechazadas reciben un mensaje claro, por ejemplo The card has insufficient funds. Please use another card., The card has expired. Please use another card. o The security code (CVV) is not valid. Please check it and try again. Los errores técnicos de OpenPay nunca se muestran a los clientes; van a las notas del pedido y al 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). Se oculta en la finalización de compra cuando está desactivado, cuando las claves del modo actual están incompletas o cuando la moneda del pedido no la acepta el país de la cuenta.
El plugin solo acepta pagos con tarjeta, con captura inmediata. No tiene tarjetas guardadas, suscripciones, meses sin intereses (MSI) ni pagos a plazos, pagos con puntos de tarjeta, efectivo, SPEI, PSE o CoDi, ni autorización y captura por separado.
Pedidos y reembolsos
Estados del pedido
Pendiente de pago: el cliente está en la página 3D Secure o no ha terminado el pago. Una nota muestra el ID del cargo.
Procesando: el pago se confirmó. Es el estado habitual de WooCommerce tras el pago; los pedidos con solo productos virtuales descargables pasan a Completado. La nota del pedido muestra el ID del cargo y el modo (producción o sandbox). El ID de transacción es el ID de cargo de OpenPay.
En espera: el cargo está en curso y aún no se ha capturado; o OpenPay informa de un cargo completado con un importe o una moneda distintos a los del pedido (el pedido no se marca como pagado y la nota muestra la diferencia); o llegó un pago para un pedido que ya se había cancelado. Revisa el pedido en el panel de OpenPay y cúmplelo o reembólsalo allí.
Fallido: la tarjeta fue rechazada al crear el cargo, o el último intento falló, se canceló o caducó. El cliente puede volver a pagar.
Si llega un segundo cargo completado para un pedido que ya está pagado, el pedido no cambia. Una nota que empieza por WARNING te pide que reembolses el duplicado en el panel de OpenPay.
Reembolsos
Para cuentas de México y Perú: abre el pedido, haz clic en Refund, introduce el importe y haz clic en Refund via Credit or debit card (OpenPay) (el botón muestra el título de tu método de pago). Se admiten reembolsos totales y parciales. El reembolso se envía en el modo y el país de cuenta con los que se pagó el pedido, así que mantén rellenas las claves del sandbox mientras tengas pedidos de sandbox pendientes de reembolso. Si OpenPay no acepta el reembolso, WooCommerce muestra el error, por ejemplo OpenPay refund failed: ..., y no se registra ningún reembolso. Un reembolso correcto se añade a las notas del pedido con el ID de reembolso de OpenPay.
OpenPay Colombia no admite reembolsos de tarjeta a través de la API, igual que en los plugins oficiales de OpenPay. Para Colombia no se ofrece el botón de reembolso; reembolsa el cargo en el panel de OpenPay.
Los reembolsos y contracargos hechos en el panel de OpenPay llegan por webhook y se añaden una sola vez a las notas del pedido. No se registran automáticamente como reembolsos de WooCommerce. Si lo necesitas, crea un reembolso manual en WooCommerce sin usar el botón de OpenPay.
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 > OpenPay. 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 plaza de dominio. Libera la plaza en tu cuenta de vibefox.net.
Sin una clave activa, OpenPay no se muestra a los clientes en la finalización de compra. Si un pago se inicia 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. Aparece un recordatorio en la página de Plugins y en las páginas de WooCommerce. Los pedidos existentes no se ven afectados: los pagos ya iniciados se siguen confirmando, 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
OpenPay no aparece en la finalización de compra: comprueba que la licencia está activa, que Enable / Disable está activado y que el modo actual tiene las tres claves: las del sandbox en modo sandbox, y las de producción en modo producción. Comprueba que la moneda de la tienda la acepta el Account country (México: MXN, USD; Colombia: COP, USD; Perú: PEN, USD). La página de configuración muestra un aviso en cada caso.
El pago se realizó, pero el pedido sigue en Pendiente de pago: el cliente no regresó de la página 3D Secure y el webhook no funciona. Comprueba que la URL del webhook está añadida en el panel de OpenPay del modo que usas, exactamente como la muestran los ajustes, con los eventos indicados arriba. Comprueba que las claves del modo con el que se pagó el pedido están rellenas: sin ellas, el webhook responde not configured y OpenPay lo reintenta más tarde.
El webhook responde ignored (unknown order): el cargo no fue creado por esta tienda para este pedido, por ejemplo un cargo de otra tienda en la misma cuenta de OpenPay. No se cambia nada.
El webhook responde verification failed: no se pudo acceder a la API de OpenPay para leer el cargo. OpenPay reintenta el webhook.
El webhook responde busy: otra solicitud estaba actualizando el pedido en el mismo momento. OpenPay reintenta el webhook.
El cliente ve «The secure card form could not be loaded»: openpay.js o la biblioteca antifraude de OpenPay no se cargaron en el navegador, o no se pudo crear el ID de sesión del dispositivo. Pide al cliente que recargue la página y lo intente de nuevo.
El cliente ve «The payment could not be processed right now»: OpenPay rechazó la solicitud o no respondió. El motivo está en las notas del pedido y en el registro, origen wcp_openpay_gateway. Una causa típica es un ID de comerciante o una clave privada incorrectos. Si OpenPay no respondió, revisa el cargo en el panel de OpenPay antes de que el cliente vuelva a pagar.
«This test card cannot be used for real payments»: se usó una tarjeta de prueba del sandbox con el modo sandbox desactivado.
El pedido está en espera después del pago: lee la nota del pedido. El cargo sigue en curso, el importe o la moneda pagados no coinciden con el pedido, o el pago llegó después de cancelar el pedido.
El reembolso falla con un mensaje sobre el modo: el pedido se pagó en modo sandbox o de producción, y las claves de ese modo no están configuradas. Introdúcelas y vuelve a intentarlo.
El bloque de licencia muestra un error: sigue el mensaje del bloque. Por ejemplo, si la clave ya está usada 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 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 la licencia de este plugin siempre se eliminan. La configuración de la pasarela, el código de verificación del webhook guardado y los registros del plugin solo se eliminan si Delete data on uninstall estaba activado. En caso contrario se conservan para una reinstalación posterior. Los datos de los pedidos siempre se conservan: los pedidos existentes mantienen sus notas de pago, sus ID de transacción y los datos del cargo necesarios para los reembolsos tras una reinstalación.
OpenPay es una marca registrada de su respectivo propietario. Este plugin no está afiliado a OpenPay ni cuenta con su respaldo.