VibeFox Flow 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 chileno (CLP) o dólar estadounidense (USD). Para carritos en otras monedas, el método de pago se oculta en la finalización de compra. Para CLP, configura la precisión de la moneda CLP en 0 en International > Localization > Currencies, porque Flow cobra pesos enteros.
Cuenta de Flow: necesitas la API Key y la Secret Key de tu cuenta de Flow, en Flow, en Mis datos, Datos técnicos. Para las pruebas, crea una cuenta de sandbox independiente en sandbox.flow.cl y usa sus claves. Las claves de sandbox y de producción son diferentes. No hay que configurar nada en la cuenta de Flow.
Sitio web público: las URL de confirmación, retorno y reembolso de tu tienda deben ser accesibles desde internet, sin protección con contraseña ni cortafuegos que bloquee a Flow. El modo mantenimiento de la tienda no las bloquea.
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 Flow 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 del bloque de licencia de la parte superior de la página Configure y haz clic en Activate (consulta Clave de licencia).
4. Introduce la API Key y la Secret Key del sandbox, activa Enable / Disable, haz clic en Save y realiza un pedido de prueba.
5. Para aceptar pagos reales, rellena las claves de producción y desactiva Sandbox mode.
Al instalar, el módulo crea dos estados de pedido, Awaiting Flow payment y Flow payment on hold. PrestaShop ofrece un nuevo módulo de pago para todas las monedas, países y grupos de clientes. Puedes limitarlo en Payment > Preferences.
Configuración
Todos los ajustes están en la página del módulo: Modules > Module Manager > VibeFox Flow Gateway > Configure. Cada sección con campos 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 vacías (Flow se oculta entonces en la finalización de compra), cuando la moneda predeterminada de la tienda no es CLP ni USD y cuando la moneda CLP tiene decimales (pon su precisión en 0 para que los precios, los totales y los reembolsos coincidan exactamente). En modo sandbox muestra Sandbox mode — payments go to sandbox.flow.cl, no real money is charged.
Flow.cl
Enable / Disable: Enable Flow.cl payments activa o desactiva el método de pago. Por defecto: off.
Title: el nombre del método de pago que ve el cliente en la finalización de compra. También es el nombre del método de pago guardado en el pedido. Por defecto: Flow. Obligatorio.
Description: el texto que se muestra debajo del método de pago en la finalización de compra. Por defecto: Pay with Webpay, credit or debit card, bank transfer and other methods. You will be redirected to Flow to complete the payment.
Credenciales de la API de Flow
Copia la API Key y la Secret Key de tu cuenta de Flow (Mis datos, Datos técnicos): las de producción en www.flow.cl, las de sandbox en sandbox.flow.cl (una cuenta de sandbox independiente).
Sandbox mode: usa el sandbox de Flow (sandbox.flow.cl) y las claves de sandbox. En modo sandbox no se cobra dinero real. Por defecto: on. Desactívalo y rellena las claves de producción para aceptar pagos reales. Los reembolsos usan siempre el entorno en el que se pagó el pedido.
Sandbox API Key: la API Key de tu cuenta de sandbox.flow.cl.
Sandbox Secret Key: la Secret Key de tu cuenta de sandbox.flow.cl. Se usa para firmar cada solicitud.
Live API Key: la API Key de tu cuenta de www.flow.cl.
Live Secret Key: la Secret Key de tu cuenta de www.flow.cl. Mantenla privada.
Las claves guardadas nunca se vuelven a mostrar. El campo queda vacío y muestra Saved — leave empty to keep it. Escribe un valor nuevo solo para cambiarla.
Clear saved keys: marca una clave y haz clic en Save para eliminarla. Un campo vacío mantiene el valor guardado.
Notificaciones
El módulo envía tres URL a Flow con cada pago y reembolso, así que no hay que configurar nada en la cuenta de Flow. El campo Flow URLs de esta sección las muestra. Con URL amigables tienen este aspecto:
La confirmación contiene solo un token de pago. El módulo busca el token entre los pagos que ha creado, pide a Flow el estado del pago con una solicitud firmada en el entorno en el que se creó el pago y aplica solo la respuesta de Flow. Un pago que esta tienda no ha creado se rechaza sin consultar a Flow. Sin la confirmación, el pedido se crea cuando el cliente vuelve desde Flow.
Avanzado
Debug log: escribe las llamadas a la API y las notificaciones en logs/flw_p_debug.log.php dentro de la carpeta del módulo. El archivo no se puede abrir desde la web. Las claves y los datos del cliente nunca se registran. Los errores siempre se registran, incluso con esta opción desactivada. Por defecto: 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 sus ajustes y el registro. Los datos de Flow guardados en los pedidos se conservan. Por defecto: off.
Finalización de compra
En el paso de pago, el cliente elige el método de pago (por defecto Flow) y ve la descripción. En modo sandbox muestra SANDBOX MODE — los pagos van al sandbox de Flow. No hay cargos reales. Tras confirmar, el módulo crea un pago de Flow por el total del carrito en la moneda del carrito, con el asunto Cart # seguido del número de carrito y el nombre de la tienda, y envía al cliente a la página de pago de Flow. El correo electrónico del cliente se pasa a Flow. Allí, el cliente elige un método de pago habilitado en tu cuenta de Flow. En este momento todavía no existe ningún pedido.
Tras pagar, el cliente vuelve a tu tienda. El pedido se marca como pagado solo cuando Flow lo confirma: mediante la confirmación o mediante una solicitud de estado firmada cuando el cliente regresa. Entonces se crea el pedido y el cliente ve la página estándar de confirmación del pedido con Your payment with Flow has been received. Si el cliente generó un cupón de Servipag o Multicaja, el pedido se crea en Awaiting Flow payment y la página muestra Your Flow payment coupon was generated. The order will be processed as soon as Flow confirms the payment. Si el pago de un pedido con cupón falla o se cancela más tarde, la página muestra Your Flow payment was not completed. Please contact us about this order. Si el importe no coincidía, la página muestra Your Flow payment was received and is being reviewed by the shop.
Si Flow no responde cuando el cliente regresa, o si otra solicitud está creando el pedido en ese momento, una página Payment confirmation pide al cliente que no pague de nuevo y ofrece Check again y Back to checkout.
Si el pago fue rechazado, el cliente vuelve a la finalización de compra con Your Flow payment was rejected. Please try again or choose another payment method. Si el cliente salió de la página de Flow sin pagar, el mensaje es The Flow payment was not completed. You can try again or choose another payment method. Si no se pudo comprobar el resultado, el mensaje es We could not confirm your Flow payment yet. If you completed it, you will receive a confirmation e-mail shortly; otherwise please try again. El carrito se conserva, y cada nuevo intento crea un nuevo pago de Flow vinculado al carrito.
Si Flow no puede iniciar el pago, el cliente permanece en la finalización de compra con un mensaje breve, por ejemplo Could not connect to Flow. Please try again in a moment. Los detalles están en el registro.
Si un cupón del carrito deja de ser válido entre el pago y su confirmación, PrestaShop lo elimina del pedido. El pedido pasa entonces a Flow payment on hold con una nota, porque el cliente pagó el precio con el descuento.
El módulo acepta solo pagos únicos. No tiene tarjetas guardadas, suscripciones, cargos recurrentes ni enlaces de pago, y no preselecciona un método de pago de Flow. Flow no puede cancelar un enlace de pago ya creado: si un cliente paga un enlace antiguo después de que el carrito ya estaba pagado, el pedido recibe una nota que te pide reembolsar el duplicado en Flow.
Pedidos y reembolsos
Estados del pedido
No order yet: el cliente fue enviado a Flow y no ha pagado, o Flow todavía no ha confirmado el pago. Solo existe el carrito.
Payment accepted: Flow informó que el pago está realizado y que el importe y la moneda coinciden. El pago se registra con el número de pedido de Flow como ID de transacción, y una nota muestra el importe, el número de pedido de Flow y el método de pago.
Awaiting Flow payment: el cliente generó un cupón de pago de Servipag o Multicaja. El pedido pasa a Payment accepted cuando Flow confirma el pago.
Flow payment on hold: Flow informó un importe o una moneda distintos del total del pedido (por ejemplo, el carrito se cambió después de iniciar el pago), se eliminó un cupón o llegó un pago para un pedido que había sido cancelado. El pago que cobró Flow queda registrado y la nota lo explica. Revisa el pedido y envíalo o reembolsa el pago.
Payment error: Flow rechazó el pago con cupón de un pedido en espera.
Canceled: el pago con cupón de un pedido en espera fue anulado en Flow.
Refunded: el pago fue reembolsado por completo a través del módulo.
Si llega otro pago para un pedido que ya está pagado, el pedido no cambia. Una nota te pide reembolsar el duplicado en tu cuenta de Flow. Un pedido reembolsado nunca se vuelve a abrir.
Bloque de pago de Flow
La página del pedido muestra un bloque Flow payment con el número de pedido de Flow y el método de pago, la referencia commerceOrder, el estado del pago, el importe pagado y reembolsado, una insignia Sandbox para los pagos de sandbox, el historial de reembolsos y las Flow notes del pedido.
Reembolsos
En el bloque Flow payment introduce el importe (se rellena el importe que aún no se ha reembolsado), opcionalmente un motivo, y haz clic en Refund via Flow. Confirma la pregunta Refund this amount via Flow? Flow e-mails the customer to complete the refund. Se admiten reembolsos totales y parciales. Necesitas el permiso para editar pedidos. Los reembolsos están limitados al importe que Flow realmente cobró, así que tras una discrepancia de importes puedes reembolsar hasta lo que pagó el cliente, no el total del pedido. Los reembolsos en CLP deben ser importes enteros. El reembolso se envía al entorno en el que se realizó el pago (sandbox o producción), por lo que las claves de ese entorno deben estar configuradas, y el cliente necesita un correo electrónico válido. Si Flow rechaza el reembolso, el bloque muestra el error y no se registra ningún reembolso. Una solicitud correcta se añade al historial de reembolsos y a las notas, con el número y el estado del reembolso de Flow. Un reembolso total pone el pedido en Refunded. Un reembolso parcial no cambia el estado. Los reembolsos están disponibles una vez que Flow ha confirmado el pago.
Los cambios de estado posteriores del reembolso que informe Flow se añaden a las notas. Si Flow rechaza o cancela después un reembolso, la nota indica que el dinero no se devolvió al cliente, y el importe puede reembolsarse de nuevo. El módulo no crea notas de crédito. Los botones de reembolso estándar de PrestaShop en la página del pedido no devuelven dinero a través de Flow. Los reembolsos creados en el panel de Flow no se importan a PrestaShop.
Clave de licencia
El módulo funciona con una clave de licencia de VibeFox de vibefox.net. El bloque de licencia License — VibeFox Flow Gateway es el primer bloque de Modules > Module Manager > VibeFox Flow 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 están la línea Product: presta-payment-flow 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. Tras cambiar la dirección de la tienda, o después de liberar un hueco 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 hueco de dominio. Libéralo en tu cuenta de vibefox.net.
Sin una clave activa, Flow 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 y los reembolsos funcionan.
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 tras 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
Flow no aparece en la finalización de compra: comprueba que la licencia esté activa, que Enable / Disable esté activado, que las claves del modo actual estén rellenas (claves de sandbox en modo sandbox, claves de producción en modo producción) y que la moneda del carrito sea CLP o USD. 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: la confirmación de Flow no llega a tu tienda y el cliente no regresó. Comprueba que la URL de confirmación que aparece en Flow URLs se abra desde internet y que no la bloquee una contraseña o un cortafuegos. Activa Debug log y revisa el campo Log en la página del módulo.
La confirmación responde Payment does not belong to the order: el token no es un pago creado por esta tienda, o Flow informó otra referencia para él. No se cambia nada.
La confirmación responde Gateway not configured: las claves del entorno del pago están vacías. Introdúcelas de nuevo. Flow reintenta la confirmación.
La confirmación responde Flow API unavailable or Busy, retry: la solicitud de estado a Flow falló, o el pedido lo estaba creando otra solicitud en ese mismo momento. Flow reintenta la confirmación.
El cliente ve Flow payments are not available at the moment: faltan las claves o Flow las rechazó. Comprueba la API Key y la Secret Key del modo actual.
El cliente ve A valid billing email is required for Flow payments: Flow necesita el correo electrónico del cliente.
El cliente ve The order total is too small to be paid with Flow: el total del carrito se redondea a cero en la moneda del carrito.
El cliente pagó, pero el pedido está en Awaiting Flow payment o Flow payment on hold: lee las notas del bloque Flow payment. El cliente generó un cupón de pago en efectivo que aún no está pagado, o el importe o la moneda informados por Flow no coinciden con el pedido. Los totales de CLP con decimales se redondean a pesos enteros, así que configura la precisión de CLP en 0.
El reembolso falla con un mensaje sobre las claves de sandbox o de producción: el pedido se pagó en ese entorno y sus claves están vacías. Introdúcelas e inténtalo de nuevo.
El reembolso falla con Flow accepts CLP refunds in whole units only: introduce un importe entero.
Para desarrolladores, el README enumera los hooks actionWcpFlowSupportedCurrencies (monedas para las que se ofrece el método de pago) y actionWcpFlowPaymentSubject (el asunto del pago enviado a Flow).
Desinstalación
Ve a Modules > Module Manager, abre el menú junto a VibeFox Flow 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 módulo y el registro. Si está desactivado, todos los ajustes se conservan para una reinstalación posterior. Los registros de pagos y reembolsos de Flow y los estados de pedido Awaiting Flow payment y Flow payment on hold siempre se conservan, así que los pedidos pagados antes pueden reembolsarse tras una reinstalación. Los pedidos existentes conservan sus notas de pago y sus ID de transacción.
Flow es una marca registrada de su respectivo titular. Este módulo no está afiliado a Flow ni cuenta con su aprobación.