VibeFox Wompi for WooCommerce — Ayuda

Requisitos

WordPress: 5.8 o posterior.

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

PHP: 8.0 o posterior.

Moneda de la tienda: peso colombiano (COP). Wompi Colombia cobra en COP, y el método de pago se oculta en pedidos con otras monedas.

Cuenta de Wompi: una cuenta de comerciante de Wompi Colombia. Cada entorno (sandbox y producción) tiene cuatro claves: clave pública, clave privada, secreto de eventos y secreto de integridad. Las encuentras en el panel de comerciante de Wompi (comercios.wompi.co), en la sección de desarrolladores. Wompi El Salvador y Panamá usan APIs distintas y no son compatibles.

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_wompi_payment a /wp-content/plugins/ por FTP.

2. Haz clic en Activate.

3. Configura la moneda de la tienda como peso colombiano (COP) en WooCommerce > Settings > General.

4. Abre los ajustes: WooCommerce > Settings > Payments > Wompi, o haz clic en Settings debajo del nombre del plugin en la página de Plugins.

5. 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.

6. Pega las claves de sandbox y de producción del panel de comerciante de Wompi y configura la Events URL en Wompi (consulta Configuración).

7. Activa Enable/Disable. Prueba un pago en modo sandbox y luego desmarca Sandbox mode para aceptar pagos reales.

Configuración

Todos los ajustes están en una sola página: WooCommerce > Settings > Payments > Wompi. Encima de los campos, un cuadro de estado muestra el modo actual, SANDBOX o PRODUCTION. Cuando falta una clave de este modo, el cuadro la enumera e indica que el método de pago está oculto en la finalización de compra hasta que se configuren todas las claves de este entorno. Cuando todas las claves están configuradas, indica si se cobran pagos reales. Al guardar, el plugin te avisa si una clave no empieza por el prefijo de su sección, y si Wompi está activado pero oculto en la finalización de compra porque faltan claves. En la lista de métodos de pago, Wompi aparece marcado como «requiere configuración» hasta que el modo actual tenga las cuatro claves. Las claves de la versión 1.0 se trasladan automáticamente a la sección Sandbox o Production correspondiente al actualizar.

General

Enable/Disable: Enable Wompi 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: Wompi.

Description: el texto que se muestra debajo del método de pago en la finalización de compra. Por defecto: Pay securely with Wompi: cards, PSE, Nequi, Bancolombia and more.

Cuenta de Wompi

Copia las claves del panel de comerciante de Wompi (comercios.wompi.co), en la sección de desarrolladores. Cada entorno tiene su propia clave pública, clave privada, secreto de eventos y secreto de integridad.

Sandbox mode: Use the Wompi sandbox (sandbox keys, no real money). Cambia tanto las claves como la API de Wompi (sandbox.wompi.co o production.wompi.co). Los pedidos conservan el entorno en el que se pagaron. Por defecto: activado. Desmárcalo para aceptar pagos reales.

Claves de sandbox

Las cuatro claves del sandbox de Wompi. Empiezan por pub_test_, prv_test_, test_events_ y test_integrity_.

Public key: la clave pública del sandbox (pub_test_...). Identifica tu cuenta en Wompi Web Checkout.

Private key: la clave privada del sandbox (prv_test_...). Se usa para leer las transacciones desde la API de Wompi.

Events secret: el secreto de eventos del sandbox (test_events_...). Verifica la firma de los eventos de Wompi.

Integrity secret: el secreto de integridad del sandbox (test_integrity_...). Firma la solicitud de pago enviada a Web Checkout.

Claves de producción

Las cuatro claves del entorno de producción de Wompi. Empiezan por pub_prod_, prv_prod_, prod_events_ y prod_integrity_.

Public key: la clave pública de producción (pub_prod_...).

Private key: la clave privada de producción (prv_prod_...).

Events secret: el secreto de eventos de producción (prod_events_...).

Integrity secret: el secreto de integridad de producción (prod_integrity_...).

URL de eventos (webhook)

Los eventos de Wompi avisan a tu tienda de que una transacción ha cambiado. En el panel de comerciante de Wompi, sección de desarrolladores, configura la Events URL que se muestra en esta sección de los ajustes, tanto para sandbox como para producción. Tiene este aspecto: https://your-site/wc-api/wompi_p/. Copia la URL exactamente como la muestran los ajustes.

El plugin usa este evento:

Los demás eventos reciben la respuesta Ignored. Cada evento se comprueba con el secreto de eventos de su entorno (sandbox o producción). Los eventos sin una firma válida se rechazan. Tras la comprobación, la transacción se lee desde la API de Wompi, y solo se usan esos datos. Sin la Events URL, un pedido solo se confirma cuando el cliente vuelve a la tienda después de pagar.

Avanzado

Debug log: Log payment and webhook activity escribe la actividad de pagos y eventos en WooCommerce > Status > Logs, fuente wcp_wompi_payment. Los errores siempre se registran, incluso cuando esta opción está desactivada. Las claves, los secretos y los datos de los clientes nunca se registran. Por defecto: desactivado.

Delete data on uninstall: Remove the plugin settings and logs when the plugin is deleted. Desactivar el plugin nunca borra nada. Los datos de los pedidos siempre se conservan. Por defecto: desactivado.

Finalización de compra

El cliente elige el método de pago (por defecto Wompi) y realiza el pedido. En modo sandbox, la finalización de compra muestra Sandbox mode: no real payment is made. debajo de la descripción. El plugin crea un intento de pago con su propia referencia (WC-, el número de pedido y una marca de tiempo), la firma con el secreto de integridad y envía al cliente a Wompi Web Checkout con el total del pedido en COP. El correo de facturación y el nombre del cliente se envían a Wompi. Una nota en el pedido registra el entorno, la referencia y el importe.

En la página de Wompi, el cliente paga con cualquier método de pago habilitado en tu cuenta de Wompi. Después, Wompi devuelve al cliente a la página de pedido recibido de tu tienda. El pedido se marca como pagado solo después de que Wompi lo confirme: mediante un evento firmado o mediante una solicitud del servidor a la API de Wompi cuando el cliente llega a esa página. El número de transacción de la propia dirección de retorno no es de confianza. Al recargar la página, la transacción se vuelve a comprobar como máximo una vez cada 20 segundos.

Solo las transacciones creadas para ese pedido pueden pagarlo, y solo en el entorno del intento. Un cliente puede volver a pagar un pedido no pagado, por ejemplo desde la página Pay for order. Cada intento recibe una nueva referencia.

El método de pago se muestra solo cuando la licencia está activa, las cuatro claves del modo actual están configuradas, la moneda del pedido es COP y el total es de al menos COP 1.500. Si no se puede iniciar el pago, el cliente ve un mensaje breve y puede elegir otro método de pago:

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). Incluye traducciones al español para Colombia y España.

El plugin no realiza reembolsos desde WooCommerce. No tiene tarjetas guardadas, suscripciones ni campos de tarjeta en tu sitio: todos los datos de pago se introducen en Wompi.

Pedidos

Estados del pedido

Pending payment: el cliente fue enviado a Wompi y aún no ha pagado, o Wompi aún no ha confirmado la transacción.

On hold (pending payment): Wompi informa de que la transacción está pendiente, por ejemplo pagos PSE, Nequi o en efectivo a la espera de confirmación. El pedido permanece en espera hasta que Wompi lo apruebe o lo rechace.

Processing or Completed: la transacción fue aprobada. Se aplica el estándar de WooCommerce: Procesando, o Completado para pedidos con solo productos virtuales descargables. La nota del pedido muestra la transacción de Wompi, el tipo de método de pago (por ejemplo, tarjeta, PSE o Nequi) y la referencia. El ID de transacción del pedido es el ID de la transacción de Wompi.

On hold after payment: Wompi aprobó un importe o una moneda distintos del total del pedido (por ejemplo, el pedido se editó después de iniciar el pago), o el pago se aprobó después de que el pedido se hubiera cancelado. El pedido no se marca como pagado. La nota del pedido lo explica. Revisa el pago en el panel de Wompi y completa el pedido o reembolsa el pago.

Failed: la transacción del último intento de pago fue rechazada o terminó con un error. El mensaje de Wompi se añade a la nota. Los resultados de intentos anteriores no cambian el pedido.

Cancelled: la transacción del último intento de pago fue anulada en Wompi antes de que el pedido se pagara.

Si llega un segundo pago aprobado para un pedido que ya está pagado, el pedido no cambia. Una nota te pide que reembolses el duplicado en el panel de Wompi. Si la transacción de pago se anula en Wompi, una nota te pide revisar el pedido. Un pago tardío de un pedido reembolsado solo añade una nota. Los eventos repetidos y las vueltas a la tienda nunca duplican notas, correos ni cambios de stock.

Reembolsos

Los reembolsos no se envían desde WooCommerce. Reembolsa o anula el pago en el panel de comerciante de Wompi y, después, registra un reembolso manual en WooCommerce. Una anulación hecha en Wompi se añade al pedido 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 > Wompi. 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 eliminarla 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. Eliminar la clave de un sitio no libera su plaza de dominio. Libera la plaza en tu cuenta de vibefox.net.

Sin una clave activa, Wompi 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 gestores de la tienda con sesión iniciada 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 siguen confirmándose mediante los eventos de Wompi y las vueltas de los clientes a la tienda.

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

Wompi no aparece en la finalización de compra: comprueba que la licencia esté activa, que Enable/Disable esté activado y que las cuatro claves del modo actual estén configuradas (el cuadro de estado de la página de ajustes enumera las claves que faltan). Comprueba también que la moneda del pedido sea COP y que el total sea de al menos COP 1.500.

El pago se realizó, pero el pedido sigue en Pending payment: la Events URL no funciona. En el panel de Wompi, comprueba que la Events URL esté configurada para el entorno que usas (sandbox o producción) y que sea exactamente la que se muestra en los ajustes. Comprueba que el secreto de eventos de ese entorno esté en la sección correspondiente. El pedido también se confirma cuando el cliente vuelve a la tienda después de pagar.

La Events URL responde Not configured: el secreto de eventos del entorno del evento está vacío. Pégalo en los ajustes.

La Events URL responde Invalid signature: el secreto de eventos pertenece a otro entorno u otra cuenta. Cópialo de nuevo desde el panel de Wompi.

La Events URL responde Transaction lookup failed: la API de Wompi no devolvió la transacción, por ejemplo por una clave privada incorrecta o un problema de red. Wompi vuelve a enviar el evento más tarde.

La Events URL responde Busy, retry: el pedido se estaba actualizando con otra solicitud en ese mismo momento. Wompi vuelve a enviar el evento más tarde.

La Events URL responde Environment mismatch: llegó una transacción de sandbox para un intento de pago de producción, o al revés. Los pagos de sandbox nunca confirman pedidos de producción.

Aviso al guardar «The key does not start with ...»: una clave se pegó en la sección equivocada. Las claves de sandbox empiezan por pub_test_, prv_test_, test_events_ y test_integrity_; las de producción, por pub_prod_, prv_prod_, prod_events_ y prod_integrity_.

El pedido está en On hold con una nota sobre el importe: el importe o la moneda aprobados no coinciden con el total del pedido. Revisa el pago en el panel de Wompi y completa o reembolsa el pedido manualmente.

Otros errores: abre las notas del pedido o WooCommerce > Status > Logs, fuente wcp_wompi_payment. Los errores siempre se registran. Activa Debug log para más detalle. Los desarrolladores pueden permitir otra moneda con el filtro wompi_p_supported_currencies si su cuenta de Wompi la acepta.

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 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 y los registros del plugin solo se eliminan si Delete data on uninstall estaba activado. Si no, se conservan para una reinstalación posterior. Los pedidos existentes conservan sus notas de pago, los datos de Wompi y los ID de transacción.

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