VibeFox Wompi for PrestaShop — Ayuda
Requisitos
PrestaShop: 8.0 a 9.x.
PHP: 8.0 o posterior. El módulo no se instala en versiones anteriores de PHP.
Moneda: peso colombiano (COP). Wompi Colombia cobra en COP, y el método de pago se oculta en los carritos con otras monedas. La página de configuración te avisa cuando la moneda predeterminada de la tienda no es COP.
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 API diferentes y no se admiten.
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 Wompi Payment más tarde en la lista de módulos y haz clic en Configure.
3. Pega tu clave de licencia de VibeFox en License key en el bloque de licencia de la parte superior de la página Configure y haz clic en Activate (ver Clave de licencia).
4. Pega las claves de sandbox y de producción del panel de comerciante de Wompi y configura la URL de eventos en Wompi (ver Configuración).
5. Activa Enable/Disable y haz clic en Save. Prueba un pago en modo sandbox y luego desactiva Sandbox mode para aceptar pagos reales.
Al instalarse, el módulo crea dos estados de pedido, Awaiting Wompi payment y Wompi payment on hold. PrestaShop ofrece un nuevo módulo de pago para las monedas, países y grupos de clientes que existen en ese momento. Comprueba que COP esté permitido en Payment > Preferences. Un país que añadas más tarde debe marcarse allí antes de que sus clientes vean Wompi.
Configuración
Toda la configuración está en la página del módulo: Modules > Module Manager > VibeFox Wompi Payment > Configure. Cada sección con campos tiene su propio botón Save, que guarda toda la página. 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 y explica 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 módulo advierte si una clave no empieza con el prefijo de su sección, y si Wompi está activado pero oculto en la finalización de compra porque faltan claves.
Wompi
Enable/Disable: Enable Wompi activa o desactiva el método de pago. Predeterminado: off.
Title: el nombre del método de pago que ven los clientes en la finalización de compra. También es el nombre del método de pago guardado en el pedido. Predeterminado: Wompi. Si lo dejas vacío, se usa el nombre del módulo.
Description: el texto que se muestra debajo del método de pago en la finalización de compra. Predeterminado: 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), sección de desarrolladores. Cada entorno tiene su propia clave pública, clave privada, secreto de eventos y secreto de integridad.
Sandbox mode: usa el sandbox de Wompi (claves de sandbox, sin dinero real). Cambia tanto las claves como la API de Wompi (sandbox.wompi.co o production.wompi.co). Los intentos de pago conservan el entorno en el que se hicieron. Predeterminado: on. Desactívalo para aceptar pagos reales. Mientras esté activado, los clientes ven Modo sandbox: no se realiza ningún pago real. debajo del método de pago.
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 de sandbox (pub_test_...). Identifica tu cuenta en Wompi Web Checkout.
Private key: la clave privada de sandbox (prv_test_...). Se usa para leer transacciones de la API de Wompi.
Events secret: el secreto de eventos de sandbox (test_events_...). Verifica la firma de los eventos de Wompi.
Integrity secret: el secreto de integridad de 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_...).
Las claves públicas se muestran en sus campos. Las claves privadas y los secretos guardados nunca se vuelven a mostrar. El campo queda vacío y muestra Guardado: déjalo vacío para conservarlo. Escribe un valor nuevo solo si quieres cambiarlo.
Clear saved secrets: marca una clave privada o un secreto de cualquiera de los entornos y haz clic en Save para eliminarlo. Un campo vacío conserva el valor guardado.
URL de eventos (webhook)
Los eventos de Wompi informan a tu tienda de que una transacción ha cambiado. En el panel de comerciante de Wompi, sección de desarrolladores, configura la URL de eventos que se muestra en esta sección, tanto para sandbox como para producción. Con URLs amigables tiene este aspecto https://your-shop/module/wcp_wompi_payment/webhook, posiblemente con un código de idioma como /es/. Copia la URL exactamente como la muestra la configuración.
El módulo usa este evento:
Los demás eventos reciben como respuesta Ignored. Cada evento se verifica con el secreto de eventos de su entorno (sandbox o producción). Los webhooks sin firma válida se rechazan. Tras la verificación, la transacción se lee de la API de Wompi con la clave privada de ese entorno, y solo se usan esos datos. Sin la URL de eventos, el pedido se crea solo cuando el cliente vuelve a la tienda después de pagar.
Avanzado
Debug log: escribe la actividad de pagos y webhooks en logs/wompi_p_debug.log.php dentro de la carpeta del módulo. El archivo no se puede abrir desde la web. Los errores y las advertencias siempre se registran, incluso cuando esta opción está desactivada. Las claves, los secretos y los datos de los clientes nunca se registran. Predeterminado: off.
Log: muestra el tamaño y las últimas entradas del registro. Haz clic en Clear log para vaciarlo.
Delete data on uninstall: si está activado, al desinstalar el módulo se eliminan su configuración y el registro. Los intentos de pago de Wompi y los estados de pedido del módulo siempre se conservan, así los pedidos existentes mantienen sus datos de Wompi. Predeterminado: off.
Finalización de compra
En el paso de pago, el cliente elige el método de pago (de forma predeterminada Wompi) y confirma. El módulo crea un intento de pago con su propia referencia (PS-, el número del carrito y una marca de tiempo), lo firma con el secreto de integridad y envía al cliente a Wompi Web Checkout con el total del carrito en COP. El correo electrónico del cliente y el nombre de la dirección de facturación se pasan a Wompi. En este punto aún no existe ningún pedido.
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 tu tienda. El pedido se marca como pagado solo cuando Wompi lo confirma: mediante un evento firmado o mediante una solicitud del servidor a la API de Wompi cuando el cliente regresa. El número de transacción de la propia dirección de retorno no es de confianza, y solo se aceptan las transacciones creadas para ese carrito en el entorno de su intento. Al recargar la página, la transacción se vuelve a comprobar como máximo una vez cada 20 segundos.
Cuando la transacción se aprueba, se crea el pedido y el cliente ve la página estándar de confirmación del pedido. En caso de pago pendiente (por ejemplo, PSE, Nequi o un pago en efectivo), la página muestra Tu pago de Wompi está pendiente de confirmación (por ejemplo, PSE, Nequi o un pago en efectivo). Procesaremos el pedido en cuanto Wompi confirme el pago. Para un pedido en espera, muestra Hemos recibido tu pago de Wompi y lo estamos revisando. Te contactaremos si hace falta algo. Si un pago pendiente se rechaza más tarde, la página muestra Tu pago de Wompi no fue aprobado. Ponte en contacto con nosotros. Si se anula, la página muestra Tu pago de Wompi fue anulado y este pedido fue cancelado. Ponte en contacto con nosotros.
Si Wompi aún no ha confirmado la transacción cuando el cliente regresa, aparece una página con Estamos esperando a que Wompi confirme tu pago. Recibirás un correo electrónico en cuanto se confirme. y un botón Check again. El evento de Wompi crea el pedido en cuanto llega.
Si el pago se rechaza, no se crea ningún pedido y el carrito se conserva. El cliente vuelve a la finalización de compra con Tu pago de Wompi no fue aprobado (...). Puedes intentarlo de nuevo o elegir otro método de pago., con el motivo indicado por Wompi. Un pago anulado muestra Tu pago de Wompi fue anulado. Puedes intentarlo de nuevo o elegir otro método de pago. Si el cliente sale de Web Checkout sin pagar, el mensaje es Tu pago de Wompi no se completó. Puedes intentarlo de nuevo o elegir otro método de pago. Cada nuevo intento recibe una referencia nueva. Cuando el carrito ya tiene un pedido (pagado, pendiente, Error de pago o Cancelado), no se puede volver a pagar: el cliente es llevado a la página de confirmación del pedido.
El método de pago solo se muestra cuando la licencia está activa, las cuatro claves del modo actual están configuradas, la moneda del carrito es COP y está permitida para el módulo, y el total es de al menos COP 1.500. Si el pago no puede iniciarse, el cliente permanece en la finalización de compra con un mensaje breve:
La URL de eventos funciona mientras la tienda está en modo de mantenimiento y no se ve bloqueada por la restricción de países de tu tienda.
El módulo no realiza reembolsos desde PrestaShop. 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
Todavía sin pedido: el cliente fue enviado a Wompi y no ha pagado, el pago fue rechazado o Wompi aún no ha confirmado la transacción. Solo existe el carrito.
Awaiting Wompi payment: Wompi indica la transacción como pendiente, por ejemplo pagos PSE, Nequi o en efectivo que esperan confirmación. El pedido espera hasta que Wompi lo apruebe o lo rechace. Cuando se aprueba, el pago se registra y el pedido pasa a Payment accepted.
Payment accepted: la transacción fue aprobada por el importe del carrito en COP. El pago se registra con el ID de transacción de Wompi, y una nota muestra la transacción, el tipo de método de pago (por ejemplo CARD, PSE o NEQUI), la referencia, el importe y el entorno.
Wompi payment on hold: Wompi aprobó un importe o una moneda distintos del total del pedido (por ejemplo, el carrito se modificó 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 lo explica. Revisa el pago en el panel de Wompi y procesa el pedido o reembolsa el pago.
Payment error: una transacción pendiente 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.
Canceled: una transacción pendiente del último intento de pago fue anulada en Wompi.
Si llega un segundo pago aprobado para un pedido que ya está pagado, el pedido no cambia. Una nota te pide reembolsar 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 y regresos repetidos nunca duplican notas, correos electrónicos ni pagos.
Bloque de pago de Wompi
La página del pedido muestra un bloque Wompi payment con la referencia, el ID de transacción, el estado (con el estado de Wompi), el importe solicitado, el importe de la transacción, el método de pago, el mensaje de Wompi, una etiqueta SANDBOX para los pagos de sandbox, los Payment attempts del carrito cuando hubo varios, y las Wompi notes del pedido.
Reembolsos
Los reembolsos no se envían desde PrestaShop. Reembolsa o anula el pago en el panel de comerciante de Wompi y después registra el reembolso en PrestaShop manualmente. Una anulación de la transacción de pago hecha en Wompi se añade al pedido como nota.
Clave de licencia
El módulo funciona con una clave de licencia de VibeFox de vibefox.net. El bloque de licencia License — VibeFox Wompi Payment es el primer bloque de Modules > Module Manager > VibeFox Wompi Payment > Configure, por encima de la configuración. Pega 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 eliminar la clave de esta tienda. Debajo aparecen la línea Product: presta-payment-wompi 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 una plaza 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. Eliminar la clave de la tienda no libera su plaza de dominio. Libérala en tu cuenta de vibefox.net.
Sin una clave activa, Wompi 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. La tienda de 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 la finalización de compra. Aparece un recordatorio en Modules > Module Manager, en la pestaña Alerts. Los pedidos existentes no se ven afectados: los pagos ya iniciados siguen siendo confirmados por los eventos de Wompi y cuando el cliente vuelve a la tienda.
Cuando una licencia caduca, el módulo sigue funcionando, pero las actualizaciones y el soporte necesitan 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 a la semana. No se necesita ningún cron job. Desinstalar o restablecer el módulo elimina siempre la clave de licencia y el estado de la licencia.
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 configuración enumera las claves que faltan). Comprueba también que la moneda del carrito sea COP y que el total sea de al menos COP 1.500. En Payment > Preferences, comprueba que el módulo esté permitido para COP, el país del cliente y el grupo del cliente.
El pago se realizó, pero no se creó ningún pedido: la URL de eventos no funciona. En el panel de Wompi, comprueba que la URL de eventos esté configurada para el entorno que usas (sandbox o producción) y que sea exactamente la que muestra la configuración. Comprueba que el secreto de eventos de ese entorno esté en la sección correspondiente. El pedido también se crea cuando el cliente vuelve a la tienda después de pagar.
La URL de eventos responde Not configured: el secreto de eventos del entorno del evento está vacío. Pégalo en la configuración.
La URL de eventos responde Invalid signature: el secreto de eventos pertenece a otro entorno u otra cuenta. Cópialo de nuevo desde el panel de Wompi.
La URL de eventos 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 envía el evento de nuevo más tarde.
La URL de eventos responde Retry: el pedido estaba siendo confirmado por otra solicitud en ese mismo momento, o no se pudo crear el pedido (por ejemplo, el módulo está desactivado). Wompi envía el evento de nuevo más tarde. Consulta el campo Log para ver el motivo.
La URL de eventos 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.
La URL de eventos responde Unknown reference: la referencia de la transacción no fue emitida por esta tienda, por ejemplo porque la misma cuenta de Wompi la usa otra tienda. Las referencias de otros sistemas reciben como respuesta Ignored.
La URL del webhook muestra Method not allowed en el navegador: es normal. La URL acepta solo solicitudes de Wompi.
Advertencia al guardar de que la clave no empieza por ...: 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 Wompi payment on hold: lee las notas del bloque Wompi payment (ver Estados del pedido) y después procesa el pedido o reembolsa el pago en el panel de Wompi.
Otros errores: revisa el campo Log en la página del módulo y las Wompi notes del pedido. Los errores siempre se registran. Activa Debug log para ver más detalles.
Desinstalación
Ve a Modules > Module Manager, abre el menú junto a VibeFox Wompi Payment 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 la configuración del módulo y el registro. Si está desactivado, toda la configuración se conserva para una reinstalación posterior. Los intentos de pago de Wompi y los estados de pedido Awaiting Wompi payment y Wompi payment on hold siempre se conservan, de modo que un evento tardío de un pago antiguo sigue reconociéndose tras una reinstalación. Los pedidos existentes conservan sus notas de pago y sus ID de transacción.
Wompi es una marca comercial de su respectivo titular. Este módulo no está afiliado a Wompi ni cuenta con su respaldo.