VibeFox OpenPay for PrestaShop — Ayuda
Requisitos
PrestaShop: 8.0 a 9.x.
PHP: 8.0 o posterior. El módulo no se instala con versiones anteriores de PHP.
HTTPS: tu tienda 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 de sandbox y de producción tienen ID de comerciante y claves distintos, y el módulo 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 la lee y la tokeniza en el navegador 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, tu alcance de PCI DSS es SAQ A-EP; consulta con tu adquirente.
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 OpenPay Gateway 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, dentro del bloque de licencia de la parte superior de la página Configure, y haz clic en Activate (ver Clave de licencia).
4. Elige el Account country e introduce las claves de sandbox y de producción (ver Configuración).
5. Recomendado: añade la URL del webhook en el panel de OpenPay (ver Configuración).
6. Activa Enable / Disable y haz clic en Save. Prueba un pago con las tarjetas de prueba del sandbox de OpenPay y, después, desactiva Sandbox mode para cobrar pagos reales.
Al instalar, el módulo crea dos estados de pedido, Awaiting OpenPay payment y OpenPay payment on hold. PrestaShop ofrece un nuevo módulo de pago para las monedas, los países y los grupos de clientes de tu tienda. Puedes limitarlos en Payment > Preferences.
Configuración
Todos los ajustes están en la página del módulo: Modules > Module Manager > VibeFox OpenPay Gateway > Configure. Cada sección tiene su propio botón Save, que guarda toda la página. Encima de los campos, la página te avisa cuando las claves del modo actual están incompletas (el método de pago se oculta entonces en la finalización de compra), cuando la moneda predeterminada de tu tienda no la acepta el país de cuenta seleccionado, y muestra Sandbox mode is enabled — no real charges are made. mientras el modo sandbox está activado.
Al guardar, las claves se comprueban. El ID de comerciante solo puede contener letras y dígitos, la clave privada debe empezar por sk_ y la clave pública por pk_. Un valor no válido no se guarda: se mantiene 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 que indica que la pasarela permanece oculta en la finalización de compra. Un Title vacío no se acepta y aparece Enter a title for the payment method.
OpenPay
Enable / Disable: Enable OpenPay card payments activa o desactiva el método de pago. Predeterminado: desactivado.
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 que se guarda en el pedido. Predeterminado: Credit or debit card (OpenPay). Obligatorio.
Description: el texto que se muestra encima del formulario de tarjeta en la finalización de compra. Predeterminado: 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 tiene 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. Predeterminado: Mexico.
Sandbox mode: usa el sandbox de OpenPay (claves de prueba, sin cargos reales) y cambia tanto las claves como la API al sandbox. Mientras está activado, la finalización de compra muestra una insignia SANDBOX MODE. Predeterminado: activado. Desactívalo para cobrar pagos reales.
Sandbox Merchant ID: el ID de comerciante del panel de sandbox, Settings (Configuración), claves 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 API.
Live Private Key: la clave privada de producción (sk_...).
Live Public Key: la clave pública de producción (pk_...).
Las claves privadas guardadas nunca se vuelven a mostrar. El campo queda vacío y muestra Saved — leave empty to keep it. Escribe un valor nuevo solo si quieres cambiarlo.
Clear saved secrets: marca una clave privada y haz clic en Save para eliminarla. Un campo vacío mantiene el valor guardado.
Webhook
El webhook no es obligatorio, pero se recomienda. Confirma los pagos cuando el cliente no vuelve de la página de 3D Secure, por ejemplo al cerrar el navegador. En el panel de OpenPay ve a Settings > Webhooks y añade la URL que aparece en Webhook URL en esta sección. Con URL amigables tiene este aspecto: https://your-shop/module/wcp_openpay_gateway/webhook, posiblemente con un código de idioma como /en/. Cópiala exactamente como aparece en la configuración. 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 (también aparecen en esta sección):
OpenPay no firma los webhooks, así que el módulo nunca confía en la notificación en sí. Solo la usa para localizar el cargo y después lee el cargo de la API de OpenPay con la clave privada del modo y del país de cuenta con los que se hizo el pago. Se ignora la notificación de un cargo que esta tienda no creó. El webhook funciona mientras la tienda está en modo de mantenimiento y no se ve afectado por la restricción por país de tu tienda.
Avanzado
Debug log: registra los pasos del pago en logs/wc_opy_debug.log.php, dentro de la carpeta del módulo. El archivo no se puede abrir desde la web. Los errores y las advertencias se registran aunque esté desactivado. Nunca se registran claves, datos de tarjeta ni datos del cliente. Predeterminado: desactivado.
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 la configuración de la pasarela, el código de verificación guardado del webhook y los registros. Los registros de cargos de OpenPay de los pedidos son historial de pagos y siempre se conservan, así que los pedidos pueden reembolsarse después de reinstalar. Predeterminado: desactivado.
Finalización de compra
En el paso de pago, el cliente elige el método de pago (por defecto Credit or debit card (OpenPay)) y rellena Cardholder name, Card number, Expiry (MM/YY) y Card code (CVV). En modo sandbox, el formulario muestra SANDBOX MODE — Test environment. No real charges will be made. Cuando el cliente confirma, openpay.js convierte la tarjeta en un token de un solo uso en el navegador, y la biblioteca antifraude añade un ID de sesión del dispositivo. Solo se envían a tu tienda estos dos valores y el ID del carrito. Si el formulario está incompleto, aparece Please fill in all card fields. debajo del formulario.
A continuación, el módulo crea el cargo con 3D Secure por el total del carrito en la moneda del carrito y envía al cliente a la página de 3D Secure de su banco, servida por OpenPay. Cada intento obtiene su propia referencia de pedido en OpenPay. La descripción del cargo es Cart #, el número del carrito y el nombre de tu tienda. 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. En este punto todavía no existe ningún pedido.
Cuando el cliente regresa, el módulo 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 carrito, estar completado y coincidir exactamente con el total y la moneda del carrito. Entonces se crea el pedido y el cliente ve la página de confirmación con Your card payment has been received. Si OpenPay indica que el cargo está en curso, el pedido se crea en Awaiting OpenPay payment y la página muestra We are confirming your card payment with OpenPay. The order will be updated automatically — please do not pay again. Si todavía no se conoce el resultado, una página Payment confirmation muestra el mismo texto con un botón Check again y un botón Back to checkout; el webhook crea el pedido en cuanto llega. Si un cargo en curso falla más tarde, la página de confirmación del pedido muestra Your OpenPay card payment was not completed. Please contact us about this order.
Si la tarjeta es rechazada o falla 3D Secure, el cliente vuelve a la finalización de compra con The card payment was not completed (declined or 3-D Secure failed). Please try again or use another card. y puede pagar de nuevo. El carrito se conserva. Antes de un nuevo intento, el módulo comprueba el cargo anterior del carrito: si en realidad se pagó, el pedido se crea a partir de él sin un segundo cargo; si sigue en curso, el pedido se crea en Awaiting OpenPay payment; si no se puede comprobar su estado, no se realiza ningún cargo nuevo y el cliente ve We could not confirm the status of your previous payment attempt. Please try again in a few minutes. Un carrito que ya tiene un pedido nunca se vuelve a cobrar.
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; se envían al registro.
Si un vale de descuento del carrito deja de ser válido entre el pago y su confirmación, se elimina del pedido. El pedido pasa entonces a OpenPay payment on hold con una nota, porque el cliente pagó el precio con descuento.
El método de pago 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 carrito no la acepta el país de cuenta.
El módulo acepta solo pagos con tarjeta, con captura inmediata. No tiene tarjetas guardadas, suscripciones, meses sin intereses (MSI) ni pagos a plazos, pagos con puntos de tarjeta, pagos en efectivo, SPEI, PSE ni CoDi, y tampoco autorización y captura por separado.
Pedidos y reembolsos
Estados del pedido
Sin pedido todavía: el cliente está en la página de 3D Secure, no ha terminado el pago o la tarjeta fue rechazada. Solo existe el carrito.
Payment accepted: el pago se confirmó. El pago se registra con el ID del cargo de OpenPay como ID de transacción, y una nota muestra el ID del cargo y el modo (producción o sandbox).
Awaiting OpenPay payment: OpenPay indica que el cargo está en curso (aún no capturado). El pedido pasa a Payment accepted cuando el cargo se completa, o a Payment error si falla.
OpenPay payment on hold: OpenPay indica un cargo completado con un importe o una moneda distintos a los del carrito (el pedido no se marca como pagado y la nota muestra la diferencia), se eliminó un vale de descuento, o llegó un pago para un pedido que ya estaba cancelado o reembolsado (el pago se registra). Revisa el pedido y procésalo, o reembolsa el pago en el panel de OpenPay.
Payment error: un cargo en curso falló, se canceló o expiró.
Refunded: el cargo se reembolsó por completo a través del módulo.
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.
Bloque de pago de OpenPay
La página del pedido muestra un bloque OpenPay payment con el ID del cargo, el estado del cargo, el entorno y el país de cuenta, el importe cobrado y el total del pedido, el importe reembolsado, una insignia Sandbox para los pagos de sandbox, el historial de reembolsos y las OpenPay notes del pedido.
Reembolsos
Para cuentas de México y Perú: en el bloque OpenPay payment, introduce el importe (se rellena el importe aún no reembolsado), opcionalmente un motivo, y haz clic en Refund via OpenPay. Confirma la pregunta Refund this amount through OpenPay? This cannot be undone. Se admiten reembolsos totales y parciales, hasta el importe que cobró OpenPay. Necesitas permiso para editar pedidos. El reembolso se envía con las claves del modo y del país de cuenta con los que se hizo el cargo, así que las claves de ese modo deben estar configuradas: conserva las claves de sandbox mientras puedas reembolsar pedidos de sandbox. Si OpenPay no acepta el reembolso, el bloque muestra el error, por ejemplo OpenPay refund failed: ..., y no se registra ningún reembolso. Un reembolso correcto se añade al historial de reembolsos y a las notas, con el ID del reembolso de OpenPay. Un reembolso total pone el pedido en Refunded. Un reembolso parcial no cambia el estado. Los reembolsos solo están disponibles cuando OpenPay ha confirmado el pago; un pedido retenido tras una diferencia de importe no se reembolsa mediante el módulo.
OpenPay Colombia no admite reembolsos de tarjetas a través de la API, igual que en los plugins oficiales de OpenPay. Para los cargos colombianos, el bloque no ofrece formulario de reembolso; reembolsa el cargo en el panel de OpenPay.
El módulo no crea facturas de abono. Los botones de reembolso estándar de PrestaShop de la página del pedido no devuelven dinero a través de OpenPay.
Los reembolsos y contracargos hechos en el panel de OpenPay llegan por webhook y se añaden a las notas una sola vez. El estado del pedido y las facturas de abono no cambian automáticamente. Actualízalos manualmente si es necesario.
Clave de licencia
El módulo funciona con una clave de licencia de VibeFox de vibefox.net. El bloque de licencia License — VibeFox OpenPay Gateway es el primer bloque de Modules > Module Manager > VibeFox OpenPay Gateway > Configure, encima de los ajustes. 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-openpay 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 de liberar una plaza de dominio en tu cuenta, haz clic en Check now. Si no se puede acceder al 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. Quitar la clave de la tienda no libera su plaza de dominio. Libérala en tu cuenta de vibefox.net.
Sin una clave activa, OpenPay 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 se siguen confirmando y los reembolsos funcionan.
Cuando una licencia caduca, el módulo sigue funcionando, pero las actualizaciones y el soporte requieren 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 tras introducir la clave, y después una vez por 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
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 claves de sandbox en modo sandbox, las de producción en modo producción. Comprueba que la moneda del carrito 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. En Payment > Preferences comprueba que el módulo está permitido para la moneda del carrito, el país del cliente y el grupo de clientes.
El pago se realizó, pero no se creó ningún pedido: el cliente no volvió de la página de 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 aparece en la configuración, con los eventos indicados arriba. Comprueba que las claves del modo con el que se hizo el pago están rellenadas: sin ellas, el webhook responde not configured y OpenPay lo reintenta más tarde. El pedido también se crea cuando el cliente vuelve a la tienda o cuando intenta pagar de nuevo el mismo carrito.
El webhook responde ignored (unknown order): el cargo no lo creó esta tienda, 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: el carrito estaba siendo actualizado por otra solicitud en el mismo momento, o no se pudo crear el pedido (por ejemplo, porque el módulo está desactivado). OpenPay reintenta el webhook. Activa Debug log para ver el motivo.
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 vuelva a intentarlo.
El cliente ve The payment could not be processed right now: OpenPay rechazó la solicitud o no respondió. El motivo está en el registro. Una causa típica es un ID de comerciante o una clave privada incorrectos. Si OpenPay no respondió, comprueba el cargo en el panel de OpenPay antes de que el cliente vuelva a pagar.
El cliente ve This test card cannot be used for real payments: se usó una tarjeta de prueba del sandbox mientras el modo sandbox estaba desactivado.
El pedido está en OpenPay payment on hold tras el pago: lee las OpenPay notes del bloque (ver Estados del pedido) y después procesa el pedido o reembolsa el pago.
El reembolso falla con un mensaje sobre el modo: el pedido se pagó en modo sandbox o en producción, y las claves de ese modo no están configuradas. Introdúcelas y vuelve a intentarlo.
El reembolso falla con The order is being updated right now: un webhook u otra solicitud estaba actualizando el pedido en ese mismo momento. Inténtalo de nuevo en unos instantes.
Desinstalación
Ve a Modules > Module Manager, abre el menú junto a VibeFox OpenPay Gateway 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 de la pasarela, el código de verificación guardado del webhook y los registros. Si está desactivado, se conservan todos los ajustes para una reinstalación posterior. Los registros de cargos y reembolsos de OpenPay y los estados de pedido Awaiting OpenPay payment y OpenPay payment on hold siempre se conservan, así que los pedidos pagados antes pueden reembolsarse después de reinstalar. Los pedidos existentes conservan sus notas de pago y sus ID de transacción.
OpenPay es una marca registrada de su respectivo titular. Este módulo no está afiliado ni respaldado por OpenPay.