VibeFox SimplePay for PrestaShop — Ayuda
Requisitos
PrestaShop: 8.0 a 9.x.
PHP: 8.0 o posterior. El módulo se niega a instalarse en versiones anteriores de PHP.
Moneda de la tienda: HUF, EUR o USD. SimplePay no acepta otras monedas, y el método de pago no se ofrece para carritos en ellas.
Cuentas de comerciante de SimplePay: SimplePay da una cuenta de comerciante separada para cada moneda, y cuentas separadas para producción y sandbox. Para cada cuenta necesitas su MERCHANT y SECRET KEY del panel de comerciante de SimplePay (admin.simplepay.hu para producción, sandbox.simplepay.hu para sandbox), account > Technical data. Si vendes solo en HUF, la cuenta HUF es suficiente. No se necesitan otras claves.
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 SimplePay 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 (véase Clave de licencia).
4. Introduce el MERCHANT y la SECRET KEY de tus cuentas de SimplePay para cada moneda en la que vendes: cuentas sandbox para pruebas y cuentas de producción para pagos reales (consulta Configuración).
5. Copia la IPN URL que aparece en la página Configure en cada cuenta de comerciante (producción y sandbox) del panel de comerciante de SimplePay.
6. Activa Enable/Disable y haz clic en Save. Prueba un pago con Sandbox mode activado, y luego desactiva Sandbox mode para cobrar pagos reales.
Al instalarse, el módulo crea el estado de pedido SimplePay payment on hold. PrestaShop ofrece un nuevo módulo de pago para todas las monedas, países y grupos de clientes. Puedes limitarlos en Payment > Preferences.
Configuración
Todos los ajustes están en la página del módulo: Modules > Module Manager > VibeFox SimplePay 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 la moneda predeterminada de la tienda no es compatible con SimplePay, o cuando no tiene cuenta de comerciante en el modo actual. En ambos casos, el método de pago no se ofrece para carritos en esa moneda. Mientras el modo sandbox está activado, la página muestra Sandbox mode is on: payments go to the SimplePay sandbox, no real money is charged.
SimplePay (OTP)
Enable/Disable: Enable SimplePay Gateway 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 guardado en el pedido. Predeterminado: SimplePay (Card Payment). Obligatorio.
Description: el texto que se muestra debajo del método de pago en la finalización de compra. Predeterminado: Pay securely with your credit or debit card via SimplePay. Los comerciantes húngaros pueden poner aquí la declaración de transferencia de datos de SimplePay (con su enlace).
Sandbox mode: usa el sandbox de SimplePay para los pagos de prueba con las cuentas sandbox. Cambia tanto la dirección de la API como las cuentas de comerciante. No se cobra dinero real. Predeterminado: activado. Desactívalo para cobrar pagos reales con las cuentas de producción. Mientras esté activado, los clientes ven Sandbox mode: no real payment is taken. debajo del método de pago. Los pedidos iniciados en el sandbox siempre se reembolsan en el sandbox.
Cuentas de comerciante en producción
Las cuentas que se usan cuando Sandbox mode está desactivado. Rellena las cuentas de las monedas en las que vende tu tienda. Los valores de MERCHANT y SECRET KEY están en el panel de comerciante de SimplePay (admin.simplepay.hu), account > Technical data. Una cuenta solo se usa cuando ambos campos están rellenos.
HUF account — Merchant ID: el MERCHANT de tu cuenta HUF de producción.
HUF account — Secret key: la SECRET KEY de tu cuenta HUF de producción.
EUR account — Merchant ID y EUR account — Secret key: lo mismo para tu cuenta EUR de producción.
USD account — Merchant ID y USD account — Secret key: lo mismo para tu cuenta USD de producción.
Cuentas de comerciante sandbox
Las cuentas que se usan cuando Sandbox mode está activado. Los campos son los mismos que para las cuentas de producción: HUF account — Merchant ID, HUF account — Secret key y los mismos pares para EUR y USD. Toma los valores del panel de comerciante sandbox de SimplePay (sandbox.simplepay.hu), account > Technical data.
Las secret keys 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.
IPN URL
El IPN es el mensaje que SimplePay envía a tu tienda cuando cambia el estado del pago. Es la forma habitual de crear un pedido. La sección muestra la URL IPN de tu tienda. Con URLs amigables tiene este aspecto: https://your-shop/module/wcp_simplepay_gateway/ipn, posiblemente con un código de idioma como /en/. Configura esta URL en cada cuenta de comerciante, de producción y sandbox, en el panel de comerciante de SimplePay. Copia la URL exactamente como la muestran los ajustes, porque un IPN redirigido se pierde.
El IPN debe estar firmado con la SECRET KEY de la cuenta de comerciante que nombra, en el modo (sandbox o producción) en el que se inició el pago. Los IPN sin firma válida se rechazan. El módulo confirma cada IPN válido a SimplePay en la forma firmada que SimplePay exige. Se usan estos estados de IPN:
Los estados rechazado, cancelado y caducado solo se registran para el último intento de pago de un carrito que aún no tiene pedido. Los demás estados se registran y no cambian nada. Sin IPN, el pedido solo se crea cuando el cliente vuelve a la tienda tras un pago correcto.
Clear saved secret keys: marca una secret key y haz clic en Save para eliminarla. Un campo vacío mantiene el valor guardado.
Pedidos
Order Status After Payment: el estado del pedido que se asigna tras un pago correcto.
Un pago por un importe o una moneda distintos a los del pedido siempre pasa a SimplePay payment on hold.
Avanzado
Logging: escribe las llamadas a la API, los IPN y los retornos en logs/simplepay_op_debug.log.php de la carpeta del módulo. El archivo no se puede abrir desde la web. Las claves y los datos del cliente no se registran. Los errores siempre se registran, incluso cuando esto está desactivado. Predeterminado: desactivado.
Log: muestra el tamaño y las entradas más recientes del registro. Haz clic en Clear log para vaciarlo.
Delete Data on Uninstall: cuando está activado, desinstalar el módulo elimina los ajustes del gateway y el registro. Los datos de pedidos (transacciones y reembolsos de SimplePay) siempre se conservan. Predeterminado: desactivado.
Finalización de compra
En el paso de pago el cliente elige el método de pago (predeterminado: SimplePay (Card Payment)) y ve la nota You will be redirected to the SimplePay payment page to pay by card. Tras confirmar, el módulo inicia un pago con tarjeta de SimplePay por el total del carrito en la moneda del carrito, con la cuenta de comerciante de esa moneda en el modo actual, y envía al cliente a la página de pago de SimplePay. El e-mail del cliente y, cuando está completa, la dirección de facturación se pasan a SimplePay. La página de pago usa el idioma de la tienda cuando SimplePay lo admite; si no, inglés. Un pago iniciado puede completarse en un plazo de 30 minutos. En este punto todavía no existe ningún pedido.
Tras un pago correcto, el cliente vuelve a tu tienda. El retorno por sí solo nunca paga un pedido: el módulo pide a SimplePay el estado de la transacción con una solicitud firmada, así que el pedido se crea aunque el IPN llegue tarde. El pedido se marca como pagado solo después de que SimplePay lo confirme. Entonces el cliente ve la página estándar de confirmación del pedido con Successful transaction. SimplePay transaction ID: y el ID. Si SimplePay todavía no ha confirmado el pago, una página Payment confirmation muestra Your payment is being confirmed by SimplePay. SimplePay transaction ID: con el ID y un botón Check again; el IPN crea el pedido en cuanto llega.
Si el pago falla, se cancela o caduca, el cliente vuelve a la finalización de compra con el mensaje de SimplePay y el ID de transacción, por ejemplo Cancelled payment. You cancelled the payment o Timeout. The time allowed to complete the payment has expired. Un pago fallido pide al cliente que revise los datos introducidos y que contacte con el banco emisor de la tarjeta. El carrito se conserva y el cliente puede volver a intentarlo. Cada nuevo intento recibe su propia referencia de SimplePay: PS, el número de carrito y el número de intento, por ejemplo PS123-1, PS123-2.
Si SimplePay no puede iniciar el pago, el cliente ve The SimplePay payment could not be started. Please try again or choose another payment method. Si la moneda del carrito no tiene cuenta de comerciante, el mensaje es SimplePay is not available for the currency of this order. Please choose another payment method. El motivo técnico se escribe en el registro.
El IPN funciona mientras la tienda está en modo mantenimiento y no está bloqueado por la restricción de países de tu tienda.
El módulo acepta solo pagos únicos con tarjeta, cobrados en la página de SimplePay. No tiene tarjetas guardadas ni pagos con un clic, ni suscripciones o pagos recurrentes, ni autorización y captura por separado.
Pedidos y reembolsos
Estados del pedido
Todavía sin pedido: el cliente fue enviado a SimplePay y no ha pagado, el pago falló, fue cancelado o caducó, o SimplePay todavía no ha confirmado el pago. Solo existe el carrito.
Payment accepted or Delivered: el pago fue confirmado. El estado sigue a Order Status After Payment. El pago se registra con el ID de transacción de SimplePay, y una nota muestra el ID de transacción y si lo confirmó el IPN o la consulta de estado.
SimplePay payment on hold: el total o la moneda del carrito se cambiaron después de iniciar el pago, así que el importe pagado no coincide con el pedido. No se registra ningún pago. La nota muestra ambos importes. Revisa el pedido y tramítalo, o reembolsa el pago en el panel de comerciante de SimplePay. Si después se paga otro intento del mismo carrito por el importe correcto, el pedido pasa al estado de pagado.
Refunded: el pago fue reembolsado en su totalidad a través del módulo.
Un pedido pagado, reembolsado o entregado nunca vuelve a abrirse por un IPN tardío. Si un segundo pago se completa para un pedido que ya está pagado, el pedido no cambia. Una nota te pide que lo revises en el panel de SimplePay y lo reembolses si es un duplicado.
Bloque de pago de SimplePay
La página del pedido muestra un bloque SimplePay payment con el ID de transacción, la referencia del pedido (orderRef), la cuenta de comerciante y el modo, el estado de SimplePay, los importes pagados y reembolsados, una insignia Sandbox para los pagos sandbox, los intentos de pago del carrito (cuando hubo más de uno), el historial de reembolsos y las SimplePay notes del pedido.
Reembolsos
En el bloque SimplePay payment introduce el importe (se rellena el importe aún no reembolsado), opcionalmente un motivo, y haz clic en Refund via SimplePay (OTP). Confirma la pregunta Refund this amount via SimplePay? This cannot be undone. Se admiten reembolsos totales y parciales. Necesitas el permiso para editar pedidos; no hace falta acceso a las páginas de Módulos. Los reembolsos en HUF deben ser forintos enteros. El reembolso se envía a la transacción de SimplePay que pagó el pedido, con su importe y moneda, con la cuenta de comerciante y en el modo (sandbox o producción) de ese pago, así que esa cuenta debe seguir en los ajustes. Si SimplePay no acepta el reembolso, el bloque muestra el error y no se registra ningún reembolso. Un reembolso correcto se añade al historial de reembolsos y a las notas, con el ID de transacción de reembolso de SimplePay y el motivo, si lo introdujiste. Un reembolso total pone el pedido en Refunded. Un reembolso parcial no cambia el estado. Un pedido en espera por una diferencia de importe no se puede reembolsar desde el bloque: reembólsalo en el panel de comerciante de SimplePay.
El módulo no crea notas de crédito. Los botones estándar de reembolso de PrestaShop de la página del pedido no devuelven dinero a través de SimplePay. Los reembolsos hechos en el panel de comerciante de SimplePay no se sincronizan con PrestaShop. Regístralos manualmente.
Clave de licencia
El módulo funciona con una clave de licencia de VibeFox de vibefox.net. El bloque de licencia License — VibeFox SimplePay Gateway es el primer bloque de Modules > Module Manager > VibeFox SimplePay Gateway > Configure, por 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 quitar la clave de esta tienda. Debajo aparecen la línea Product: presta-payment-simplepay y el enlace Manage licenses and domains in your account, que abre tu cuenta de vibefox.net. Solo los empleados con el permiso Configure para el 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. 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, SimplePay 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. 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 mediante el IPN 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
SimplePay no aparece en la finalización de compra: comprueba que la licencia está activa, que Enable/Disable está activado, que la moneda del carrito es HUF, EUR o USD, y que esa moneda tiene Merchant ID y Secret key en el modo actual: las cuentas sandbox mientras Sandbox mode está activado, las cuentas de producción mientras está desactivado. 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 IPN no llegó a la tienda. En el panel de comerciante de SimplePay comprueba la URL IPN de la cuenta de comerciante que usas (producción o sandbox, según la moneda del carrito). Debe ser exactamente la URL que aparece en los ajustes, y tu servidor debe ser accesible desde internet. El pedido también se crea cuando el cliente vuelve a la tienda después de pagar.
El IPN responde Invalid signature: el IPN nombra una cuenta de comerciante que no está en los ajustes, su Secret key es incorrecta, o está firmado con la cuenta del otro modo distinto al del pago. Introduce el MERCHANT y la SECRET KEY exactamente como los muestra el panel de comerciante de SimplePay. SimplePay repite los IPN no confirmados.
El IPN responde Order not found o Unknown transaction: el IPN corresponde a un pago que esta tienda no inició. No se cambia nada.
El IPN responde Busy, retry: otra solicitud estaba procesando el carrito en ese mismo momento, o no se pudo crear el pedido (por ejemplo, porque el módulo está desactivado). SimplePay reintenta el IPN. El motivo se escribe en el registro.
El cliente ve The SimplePay payment could not be started: revisa el campo Log de la página del módulo. Una secret key incorrecta da Invalid response signature from SimplePay. Check the secret key of the merchant account. Los errores de SimplePay se registran con sus códigos de error.
Tras cambiar entre sandbox y producción: los nuevos pagos usan las cuentas del nuevo modo. Los pagos iniciados antes conservan la cuenta de comerciante y el modo con los que se iniciaron: sus IPN, consultas de estado y reembolsos usan esa cuenta. Mantén las cuentas del modo anterior en los ajustes mientras existan pagos abiertos o que puedan reembolsarse.
El pedido queda en SimplePay payment on hold tras el pago: lee las notas del bloque SimplePay payment. El total o la moneda del carrito se cambiaron después de iniciar el pago. Tramita el pedido o reembolsa el pago en el panel de comerciante de SimplePay.
Fallo en el reembolso: lee el mensaje del bloque. SimplePay refunds in HUF must be whole amounts. significa que el importe en HUF tenía decimales. Si el mensaje dice que la cuenta de comerciante de este pago no está configurada, introduce de nuevo la cuenta (moneda y modo) con la que se hizo el pago. Si SimplePay reembolsó un importe distinto, el mensaje te pide que revises el reembolso en el panel de SimplePay.
Desinstalación
Ve a Modules > Module Manager, abre el menú junto a VibeFox SimplePay 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 los ajustes del gateway y el registro. Si está desactivado, todos los ajustes se conservan para una reinstalación posterior. Las transacciones y reembolsos de SimplePay y el estado de pedido SimplePay payment on hold siempre se conservan, así 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.
SimplePay es una marca comercial de su respectivo titular. Este módulo no está afiliado a SimplePay ni cuenta con su respaldo.