VibeFox Quickpay 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.
Cuenta de Quickpay: necesitas dos valores del gestor de Quickpay: la clave de API de un usuario de API (para crear pagos, cobrar y reembolsar) y la clave privada de la cuenta (para comprobar la firma de los callbacks de Quickpay). No hay que configurar nada más en Quickpay. Tu tienda debe ser accesible desde internet, sin protección con contraseña, para que los callbacks de Quickpay puedan llegar.
Clave de licencia de VibeFox: se compra en vibefox.net. Una clave funciona en un solo 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 Quickpay Gateway más tarde en la lista de módulos y haz clic en Configure.
3. Introduce 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 la clave de API y la clave privada del gestor de Quickpay y haz clic en Test API key (consulta Configuración).
5. Elige el modo de cobro y el estado del pedido tras el pago, activa Enable/Disable y haz clic en Save. Mientras tu cuenta de Quickpay esté en modo de prueba, activa Test payments y haz un pago con una tarjeta de prueba de Quickpay.
Al instalarse, el módulo crea un estado de pedido, Quickpay payment on hold. PrestaShop activa el nuevo módulo de pago para todas las monedas, países y grupos de clientes. El módulo se vincula a los países activos en el momento de la instalación. Puedes cambiarlos todos en Payment > Preferences.
Configuración
Todos los ajustes están en la página del módulo: Modules > Module Manager > VibeFox Quickpay Gateway > Configure. Cada sección tiene su propio botón Save, que guarda toda la página. Hasta que se guarden la clave de API y la clave privada, la página muestra Quickpay necesita configuración: introduce la clave de API y la clave privada. Hasta que se guarden ambas, el método de pago no se muestra en la finalización de compra. Mientras Test payments esté activado, la página te recuerda desactivarlo cuando tu cuenta de Quickpay pase a producción.
Quickpay
Enable/Disable: Enable Quickpay activa o desactiva el método de pago. Por defecto: desactivado.
Title: nombre del método de pago que ven los clientes al finalizar la compra. También es el nombre del método de pago guardado en el pedido. Por defecto: Quickpay. Obligatorio: no se guarda un título vacío.
Description: texto que aparece debajo del método de pago al finalizar la compra. Por defecto: Pay securely by card or MobilePay on the Quickpay payment page.
Credenciales de la API de Quickpay
En el gestor de Quickpay (manage.quickpay.net) abre Settings > Integration. Copia la clave de API de un usuario de API (Settings > Users) y la clave privada de la cuenta.
Callback URL: muestra la URL de callback de tu tienda. Con URL amigables tiene este aspecto: https://your-shop/module/wcp_quickpay_gateway/callback. Quickpay la llama después de cada operación de pago (autorización, cobro, reembolso, cancelación). Se envía automáticamente con cada pago, así que no hay que configurar nada en Quickpay.
API key: la clave de API de un usuario de API de Quickpay. Se usa para crear pagos, cobrar y reembolsar.
Private key: la clave privada de la cuenta. Se usa para comprobar la firma (HMAC-SHA256) de los callbacks de Quickpay. Sin ella no se puede confirmar ningún pago, y los callbacks se rechazan.
Las claves guardadas no se vuelven a mostrar. El campo queda vacío y muestra Guardada: déjalo vacío para conservarla. Escribe un valor nuevo solo si quieres cambiarlo.
Borrar claves guardadas: marca API key o Private key y haz clic en Save para eliminarla. Un campo vacío conserva el valor guardado.
Test payments: acepta pagos realizados con tarjetas de prueba de Quickpay. Quickpay no tiene un sandbox separado: mientras tu cuenta de Quickpay esté en modo de prueba, los pagos se hacen con tarjetas de prueba y se marcan como de prueba. Actívalo solo durante las pruebas. Cuando está desactivado, un pago de prueba nunca marca un pedido como pagado. Mientras está activado, la finalización de compra muestra Modo de prueba: se aceptan tarjetas de prueba de Quickpay. debajo del método de pago. Por defecto: desactivado.
Test API key: este botón comprueba la clave escrita en el campo API key (o la guardada, si el campo está vacío) mediante una solicitud autenticada a Quickpay, sin guardarla. Responde Conexión correcta: la clave de API es válida., Quickpay ha rechazado la clave de API., La clave de API no está configurada. o Error de conexión: seguido del motivo.
Pago
Capture: cuándo se cobra el dinero de la tarjeta.
Order status after payment: el estado del pedido una vez que Quickpay ha confirmado el pago cobrado.
Avanzado
Debug log: escribe en logs/qpg_debug.log.php, en la carpeta del módulo. El archivo no se puede abrir desde la web. Los errores y las advertencias, como los callbacks rechazados y los errores de la API de Quickpay, siempre se registran. Actívalo para registrar también los detalles de cada solicitud y callback. Las claves de API, los datos de la tarjeta y los datos de los clientes nunca se registran. Por defecto: desactivado.
Log: muestra el tamaño y las últimas entradas del registro. Haz clic en Clear log para vaciarlo.
Delete data: si está activado, al desinstalar el módulo se eliminan los ajustes de la pasarela y el registro. Los datos de los pedidos (pagos, reembolsos y notas de Quickpay) y el estado de pedido Quickpay payment on hold siempre se conservan. Por defecto: desactivado.
Finalización de compra
En el paso de pago el cliente elige el método de pago (por defecto Quickpay, con un icono de tarjeta) y confirma. El módulo crea un pago de Quickpay para el carrito en la moneda del carrito y un enlace de pago por el total del carrito, y envía al cliente a la ventana de pago de Quickpay. En este punto todavía no existe ningún pedido. El cliente paga allí con uno de los métodos activados en tu ventana de pago de Quickpay. El correo electrónico del cliente se pasa a Quickpay. La ventana de pago se abre en el idioma del cliente cuando Quickpay lo ofrece (danés, alemán, inglés, español, finés, francés, italiano, neerlandés, noruego, polaco, sueco); en caso contrario, en inglés.
Tras pagar, el cliente vuelve a tu tienda. El regreso en sí no marca nada como pagado. El pedido se marca como pagado solo después de que Quickpay lo confirme: el callback firmado crea el pedido cuando el importe cobrado y la moneda coinciden con el carrito. Después, el cliente ve la página estándar de confirmación del pedido. Con Authorize only, el pedido se crea en Quickpay payment on hold en su lugar, y cobras el pago más tarde. Si el callback todavía no ha llegado cuando el cliente vuelve, una página de Payment confirmation muestra Quickpay está confirmando tu pago. Recibirás un correo electrónico en cuanto se confirme el pedido. con los botones Check again y Back to checkout.
Si el cliente cancela en la ventana de pago, el enlace de pago se elimina en Quickpay y el cliente vuelve a la finalización de compra con el mensaje El pago se ha cancelado. Puedes intentarlo de nuevo o elegir otro método de pago. Si la tarjeta fue rechazada, el mensaje es El pago no se ha completado. Puedes intentarlo de nuevo o elegir otro método de pago. El carrito se conserva. Un nuevo intento reutiliza el pago de Quickpay del carrito con un enlace nuevo, así que un enlace antiguo nunca puede pagarse en paralelo. Mientras un pago del carrito está autorizado y espera su cobro, no se inicia un segundo pago; el cliente ve la página de Payment confirmation.
Si no se puede iniciar el pago, el cliente permanece en la finalización de compra con el mensaje No se pudo iniciar el pago de Quickpay. Inténtalo de nuevo o elige otro método de pago. El motivo técnico se escribe en el registro. Si faltan las claves, el mensaje es Quickpay no está disponible en este momento. Elige otro método de pago.
El callback funciona aunque la tienda esté en modo de mantenimiento y no se bloquea por la restricción de países de tu tienda.
El módulo solo admite pagos únicos. No tiene suscripciones ni pagos recurrentes, ni tarjetas guardadas, ni cobro parcial, no envía a Quickpay líneas de carrito ni de factura y no tiene métodos separados de MobilePay, Apple Pay o Klarna: el cliente elige entre los métodos de tu ventana de pago de Quickpay.
Pedidos y reembolsos
Estados del pedido
No order yet: el cliente fue enviado a Quickpay y no ha pagado, la tarjeta fue rechazada o el pago está autorizado y espera el cobro automático. Solo existe el carrito.
Payment accepted or Delivered: Quickpay confirmó el pago cobrado con el importe y la moneda correctos. El estado sigue a Order status after payment. El pago se registra con el ID de pago de Quickpay como ID de transacción, y una nota muestra el pago (marcado como TEST en los pagos de prueba).
Quickpay payment on hold: el pago solo está autorizado y espera Capture Quickpay payment; o Quickpay informó de un importe o una moneda distintos del total del pedido (por ejemplo, el carrito se modificó después de iniciar el pago, o se cobró un importe distinto en el gestor de Quickpay); o el cobro automático falló y el importe sigue solo reservado. La nota lo explica. Cuando se cobró dinero por un importe distinto, el pago se registra en el pedido por el importe que cobró Quickpay.
Canceled: tú cancelaste el pedido, o el pago de un pedido en espera se canceló en el gestor de Quickpay.
Refunded: el pago se reembolsó por completo a través del módulo.
Un pago que llega para un pedido que ya está pagado, cancelado o reembolsado no cambia el pedido. Una nota te pide que revises el pago en el gestor de Quickpay, por ejemplo para reembolsar un pago duplicado.
Cuando cancelas un pedido no pagado, su enlace de pago se elimina en Quickpay. Cancelar un pedido autorizado no libera automáticamente el importe reservado: una nota te recuerda que canceles el pago en el gestor de Quickpay; si no, la reserva termina cuando caduca la autorización.
Bloque de Quickpay
La página del pedido muestra un bloque Quickpay payment con el ID del pago, el estado del pago, el importe y el importe reembolsado, una insignia Test payment en los pagos de prueba, la lista de todos los pagos de Quickpay del carrito (si hay más de uno), el historial de reembolsos y las Quickpay notes del pedido. Para cobrar y reembolsar se necesita el permiso para editar pedidos; no hace falta acceso a las páginas de módulos.
Cobro
Con Authorize only, haz clic en Capture Quickpay payment en el bloque de Quickpay y confirma ¿Cobrar el total del pedido a través de Quickpay? Se cobra el total del pedido; el cobro parcial no está disponible. Si Quickpay confirma de inmediato, el pedido pasa al estado de Order status after payment. Si no, una nota indica que se solicitó el cobro, y el pedido se marca como pagado cuando el callback de Quickpay lo confirma. Un cobro rechazado se muestra en el bloque y se anota en el pedido.
Reembolsos
En el bloque de Quickpay introduce el importe (se rellena el importe aún no reembolsado), opcionalmente un motivo, y haz clic en Refund via Quickpay. Confirma la pregunta ¿Reembolsar este importe a través de Quickpay? Esta acción no se puede deshacer. Se admiten reembolsos totales y parciales de pagos cobrados. Los reembolsos se hacen por el importe y la moneda que cobró Quickpay, así que tras una diferencia de importe o de moneda puedes reembolsar hasta lo que el cliente realmente pagó, no el total del pedido. Quickpay procesa los reembolsos de forma asíncrona: el historial de reembolsos muestra requested, y el callback lo cambia a confirmed o failed y añade el resultado a las notas. Si Quickpay rechaza el reembolso de inmediato, el bloque muestra el error y no se registra ningún reembolso. Un reembolso total pone el pedido en Refunded; un reembolso parcial no cambia el estado. Un pago autorizado que nunca se cobró no se puede reembolsar; cancélalo en el gestor de Quickpay.
El módulo no crea facturas rectificativas (credit slips). Los botones de reembolso estándar de PrestaShop en la página del pedido no devuelven el dinero a través de Quickpay.
Los reembolsos hechos directamente en el gestor de Quickpay solo se añaden a las notas. El estado del pedido y las facturas rectificativas no se cambian automáticamente. Actualízalos manualmente si hace falta.
Clave de licencia
El módulo funciona con una clave de licencia de VibeFox de vibefox.net. El bloque de licencia License — VibeFox Quickpay Gateway es el primer bloque de Modules > Module Manager > VibeFox Quickpay Gateway > Configure, por encima de los ajustes. Introduce 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 están la línea Product: presta-payment-quickpay 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 solo 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. Libera la plaza en tu cuenta de vibefox.net.
Sin una clave activa, Quickpay no se muestra a los clientes al finalizar la compra. Si de todos modos se inicia un pago, 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 el cobro 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 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
Quickpay no aparece en la finalización de compra: comprueba que la licencia esté activa, que Enable/Disable esté activado y que API key y Private key estén guardadas. Sin ambas claves el método se oculta. En Payment > Preferences comprueba que el módulo esté permitido para la moneda del carrito, el país del cliente y el grupo del cliente.
El pago se realizó, pero no se creó ningún pedido: el callback de Quickpay no llegó a tu tienda o fue rechazado. Comprueba que tu tienda sea accesible desde internet (sin protección con contraseña) y que Private key sea la clave privada de la misma cuenta de Quickpay. Los callbacks rechazados siempre se escriben en el registro de la página del módulo. Activa Debug log para ver cada callback.
El registro muestra Callback rejected: invalid checksum.: la clave privada de los ajustes no pertenece a la cuenta que envió el callback. Cópiala de nuevo desde Settings > Integration en el gestor de Quickpay.
El registro muestra Callback rejected: the private key is not configured.: introduce la clave privada. Los callbacks nunca se aceptan sin ella.
El registro muestra Callback: no cart found for payment …: el callback pertenece a un pago de Quickpay que esta tienda no creó, por ejemplo un pago realizado fuera de PrestaShop.
El registro muestra Could not lock the cart o Cannot create the order: otro callback del mismo carrito se estaba aplicando en ese momento, o no se pudo crear el pedido (por ejemplo, porque el módulo está desactivado). El callback recibe una respuesta de error, así que Quickpay lo vuelve a enviar.
Un pago de prueba no marcó el pedido como pagado: Test payments está desactivado. El registro (y la nota, si el pedido existe) indica que el pago de prueba no se aceptó. Actívalo durante las pruebas y desactívalo cuando tu cuenta pase a producción.
El pedido está en Quickpay payment on hold tras el pago: lee las notas del bloque de Quickpay. Es posible que el pago solo esté autorizado y esperando Capture Quickpay payment, que el importe o la moneda pagados no coincidan con el pedido, o que el cobro haya fallado. Cobra el pago, procesa el pedido o reembolsa el pago.
Test API key muestra «Quickpay ha rechazado la clave de API.»: la clave es incorrecta o pertenece a un usuario sin acceso a la API. Copia la clave de API de un usuario de API desde el gestor de Quickpay.
El cliente ve «No se pudo iniciar el pago de Quickpay.»: mira el campo Log de la página del módulo. Muestra el error de Quickpay, por ejemplo una moneda que tu cuenta de Quickpay no acepta.
El reembolso falla: el pedido debe tener un pago de Quickpay cobrado. El mensaje El pago de Quickpay de este pedido no se ha cobrado: no hay nada que reembolsar. significa que el pago solo está autorizado; cóbralo o cancélalo en el gestor de Quickpay. Importe de reembolso no válido: máximo … significa que el importe supera lo que queda del pago cobrado.
Los desarrolladores pueden cambiar los parámetros del enlace de pago de Quickpay mediante el hook actionQpgQuickpayLinkData.
Desinstalación
Ve a Modules > Module Manager, abre el menú junto a VibeFox Quickpay Gateway y elige Uninstall. La clave de licencia y el estado de licencia de este módulo siempre se eliminan. Si Delete data está activado, se eliminan los ajustes de la pasarela y el registro. Si está desactivado, todos los ajustes se conservan para una reinstalación posterior. Los pagos de Quickpay, los reembolsos y el estado de pedido Quickpay payment on hold siempre se conservan, de modo que los pedidos pagados antes pueden seguir reembolsándose tras una reinstalación. Los pedidos existentes conservan sus notas de pago y sus ID de transacción.
Quickpay es una marca comercial de su respectivo titular. Este módulo no está afiliado a Quickpay ni cuenta con su respaldo.