VibeFox Vindi 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 de la tienda: real brasileño (BRL). Vindi cobra solo en BRL, así que el método de pago se oculta en los carritos con cualquier otra moneda.
Cuenta de Vindi: necesitas la clave de API de tu cuenta de Vindi. El sandbox de Vindi es una cuenta de prueba de Vindi con su propia clave. Boleto, PIX y BolePix también deben estar activados en tu cuenta de Vindi si quieres ofrecerlos.
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 carga, haz clic en Configure, o busca VibeFox Vindi Gateway más tarde en la lista de módulos y haz clic en Configure.
3. Introduce tu clave de licencia de VibeFox en el campo 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. Pega la Sandbox API key y, cuando estés listo, la Live API key. Elige los Offered methods.
5. Copia la URL del webhook desde la configuración en Vindi (véase Configuración).
6. 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 Vindi payment y Vindi 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; el módulo debe estar permitido para BRL allí.
Configuración
Todos los ajustes están en la página del módulo: Modules > Module Manager > VibeFox Vindi Gateway > Configure. Cada sección tiene su propio botón Save, que guarda la página completa. Encima de los campos, la página te avisa cuando la moneda de la tienda no es BRL o cuando la clave de API del modo actual está vacía. En ambos casos, el método de pago no se muestra en la finalización de compra. Al guardar, las claves se recortan (se eliminan los espacios sobrantes). Si no se selecciona ningún método de pago, se selecciona tarjeta de crédito y la página muestra Choose at least one payment method — credit card was selected. Un Title vacío no se guarda: la página muestra Enter a title for the payment method.
Vindi
Enable / Disable: Enable Vindi payments activa o desactiva el método de pago. Predeterminado: desactivado.
Title: el nombre del método de pago que se muestra en la finalización de compra. También es el nombre del método de pago guardado en el pedido. Predeterminado: Vindi. Obligatorio.
Description: el texto que se muestra debajo del método de pago en la finalización de compra. Predeterminado: Pay by credit card on the secure Vindi page, or by boleto / PIX.
Claves de API
Crea las claves en el panel de Vindi en Settings > API keys: en app.vindi.com.br para producción y en sandbox-app.vindi.com.br para el sandbox. Producción y sandbox tienen hosts y claves separados. Cada pago recuerda dónde se creó su factura, así que las comprobaciones, cancelaciones y reembolsos siempre usan ese entorno.
Sandbox mode: crea nuevos pagos en el sandbox de Vindi, usando sandbox-app.vindi.com.br con la clave de API del sandbox. Los clientes ven una nota TEST MODE en la finalización de compra: Vindi sandbox: no real charges. Predeterminado: activado. Desactívalo para aceptar pagos reales.
Live API key: la clave privada de la cuenta de Vindi de producción. Solo se envía a la API de Vindi.
Sandbox API key: la clave privada de la cuenta sandbox de Vindi.
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 si quieres cambiarlo.
Clear saved keys: marca una clave y haz clic en Save para eliminarla. Un campo vacío mantiene el valor guardado.
Métodos de pago
Offered methods: los métodos que pueden elegir los clientes. Predeterminado: tarjeta de crédito. Los métodos también deben estar activados en tu cuenta de Vindi.
El boleto, PIX y BolePix requieren el CPF o CNPJ del cliente, que se pide en la finalización de compra.
Notificaciones de pago (webhook)
El webhook informa a tu tienda de que una factura ha sido pagada, cancelada, rechazada o reembolsada. El campo Webhook URL de esta sección muestra la URL. Con URLs amigables tiene este aspecto: https://your-shop/module/wcp_vindi_gateway/webhook?token=... y contiene un token secreto creado por el módulo. Cópiala exactamente como aparece en la configuración. En Vindi ve a Settings > Webhooks, tanto en la cuenta de producción como en la de sandbox, añade esta URL y selecciona estos eventos:
Vindi no firma sus notificaciones, así que las solicitudes con un token ausente o incorrecto se rechazan, y cada notificación solo hace que el módulo vuelva a leer la factura a través de la API de Vindi antes de que cambie un pedido. Sin el webhook, un pago con tarjeta solo se detecta cuando el cliente vuelve a realizar el pedido con el mismo carrito (entonces se encuentra la factura pagada y se crea el pedido), y un pago con boleto o PIX cuando el cliente vuelve a abrir la página de confirmación del pedido.
Avanzado
Debug log: registra las llamadas a la API y las notificaciones en logs/wc_vdi_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 está desactivado. Las claves, el token del webhook y los datos de los clientes nunca se registran. Predeterminado: desactivado.
Log: muestra el tamaño y las últimas entradas del registro. Haz clic en Clear log para vaciarlo.
Delete data on uninstall: cuando está activado, al desinstalar el módulo se eliminan los ajustes, el token del webhook y los registros. Los pedidos y las referencias de las facturas de Vindi de los pedidos se conservan. Predeterminado: desactivado.
Finalización de compra
El cliente elige el método de pago (por defecto Vindi). Cuando se ofrece más de un método, el recuadro de pago muestra Pay with y una elección entre tarjeta de crédito, boleto, PIX o BolePix. Cuando se ofrece boleto, PIX o BolePix, el recuadro también tiene un campo CPF or CNPJ. Es obligatorio cuando no se ofrece tarjeta de crédito; en caso contrario muestra Required for boleto and PIX. El campo se rellena con el Identification number o el número de IVA de la dirección de facturación cuando contienen un CPF o CNPJ válido. El número se comprueba mediante sus dígitos de control. Si falta algo, el cliente ve Please choose how you want to pay with Vindi., Please enter a valid CPF or CNPJ. o Please enter your CPF or CNPJ — it is required for boleto and PIX.
Cuando el cliente confirma el pedido, el módulo crea un cliente de Vindi para este carrito a partir de la dirección de facturación y una factura de Vindi por el total del carrito, en una sola cuota. En Vindi, la factura se llama Order # seguido del número del carrito.
Credit card: el cliente es enviado a la página de factura de Vindi y paga allí. Todavía no existe ningún pedido en este punto. Vindi no tiene URL de retorno para las facturas, así que el cliente no vuelve automáticamente a la tienda. El pedido se crea cuando Vindi confirma el pago mediante el webhook. Si el cliente vuelve a realizar el pedido con el mismo carrito, se le ofrece de nuevo la factura pendiente o, si ya está pagada, el pedido se crea de inmediato.
Boleto, PIX and BolePix: la factura se emite de inmediato, el pedido se crea con el estado Awaiting Vindi payment y el cliente llega a la página de confirmación del pedido. Allí, y en los detalles del pedido de su cuenta, una sección Payment muestra el código QR de PIX, el código de PIX para copiar y pegar con un botón Copy code y su fecha de caducidad, y un botón Open boleto. El correo de confirmación del pedido contiene el código PIX y el enlace del boleto. Si Vindi no devuelve los datos del boleto o del PIX, la factura se cancela y el cliente ve un error.
El pedido solo se marca como pagado después de que Vindi lo confirme: el módulo lee la factura desde la API de Vindi y comprueba la moneda, que la factura pertenece al carrito (código del carrito y cliente de Vindi) y que el importe pagado es igual al total del pedido. La página de confirmación del pedido vuelve a comprobar a través de la API un pedido pendiente, como máximo cada 15 segundos. Cuando el pago se ha recibido, muestra Your payment with Vindi has been received. Mientras Vindi revisa la factura, muestra We are confirming your payment with Vindi. The order will be updated automatically — please do not pay again. En el caso de un pedido cancelado, muestra This order was cancelled and its Vindi bill can no longer be paid. Please contact us if you have already paid.
Un nuevo intento de pago para el mismo carrito reutiliza la factura pendiente de Vindi si el método, el importe y el entorno son los mismos. En caso contrario, la factura anterior se cancela en Vindi antes de crear una nueva, así que el cliente no puede pagar dos veces el mismo carrito. Si la factura anterior se pagó mientras tanto, se crea el pedido y no se emite ninguna factura nueva.
Si Vindi no puede iniciar el pago, el cliente se queda en la finalización de compra con un mensaje breve, por ejemplo para revisar el CPF / CNPJ, la dirección de facturación (la calle, el código postal, la ciudad y el estado son obligatorios para el boleto), el correo electrónico o el teléfono, o para indicar que Vindi no está disponible temporalmente. El motivo técnico se escribe en el registro.
El webhook funciona mientras la tienda está en modo de mantenimiento y no está bloqueado por la restricción de países de tu tienda.
El módulo admite solo pagos únicos en una sola cuota. No tiene suscripciones ni facturación recurrente, ni tarjetas guardadas, ni pagos en cuotas, ni formulario de tarjeta en tu sitio: la tarjeta siempre se introduce en la página de Vindi.
Pedidos y reembolsos
Estados del pedido
No order yet: se inició un pago con tarjeta y Vindi aún no lo ha confirmado. Solo existe el carrito.
Awaiting Vindi payment: un pago con boleto, PIX o BolePix está pendiente (nota Awaiting ... payment at Vindi.). El pedido pasa a Payment accepted cuando Vindi informa de que la factura está pagada.
Payment accepted: el pago fue confirmado. El pago se registra con el ID de la factura de Vindi como ID de transacción, y una nota muestra la factura de Vindi, el importe y el entorno.
Vindi payment on hold: la factura de Vindi está en revisión, la factura pagada no coincide con el pedido (moneda, importe, código del carrito o cliente de Vindi), o la factura se pagó después de que el pedido se hubiera cancelado. La nota lo explica y se registra en el pedido el importe pagado. Revisa el pedido y el stock, y después completa el pedido o reembolsa el pago.
Payment error: Vindi rechazó el intento de pago de un pedido pendiente. La nota muestra el motivo del adquirente si lo hay. El cliente todavía puede pagar la misma factura, y un pago posterior pasa el pedido a Payment accepted.
Canceled: la factura de un pedido pendiente se canceló en Vindi. Cuando cancelas un pedido en la tienda, su factura pendiente de Vindi también se cancela, así que ya no se puede pagar. Si eso no es posible, una nota te pide cancelar la factura en el panel de Vindi.
Refunded: el pago fue reembolsado por completo a través del módulo.
Si se paga una segunda factura de un pedido que ya está pagado, el pedido no se modifica. Una nota te pide reembolsar un pago en Vindi.
Bloque de pago de Vindi
La página del pedido muestra un bloque Vindi payment con la factura y el cargo de Vindi, el entorno (con una insignia Sandbox para los pagos en sandbox), el método de pago, el estado, el importe pagado y reembolsado, el historial de reembolsos, todas las Bills of this cart y las Vindi notes del pedido.
Reembolsos
En el bloque Vindi payment introduce el importe (se rellena el importe que aún no se ha reembolsado), opcionalmente un motivo, y haz clic en Refund via Vindi. Confirma la pregunta Refund this amount through Vindi? This cannot be undone. Se admiten reembolsos totales y parciales de pagos con tarjeta y PIX. Necesitas el derecho a editar pedidos; el acceso a las páginas de módulos no es necesario. Los reembolsos se limitan al importe que Vindi cobró realmente, así que, tras una discrepancia, puedes reembolsar hasta lo que pagó el cliente, no el total del pedido. El reembolso se envía en el entorno del pago (producción o sandbox), por lo que la clave de API de ese entorno debe estar configurada. Un reembolso total también cancela la factura en Vindi y pone el pedido en Refunded; un reembolso parcial no cambia el estado. Un reembolso correcto se añade al historial de reembolsos y a las notas, con el cargo de Vindi y el estado. Si Vindi o el adquirente rechazan el reembolso, el bloque muestra el error y no se registra ningún reembolso. Los reembolsos están disponibles una vez que Vindi informa de que la factura está pagada.
Vindi no puede reembolsar pagos con boleto. El bloque muestra Vindi cannot refund boleto payments. Return the money to the customer by bank transfer and record the refund manually.
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 Vindi. Los reembolsos hechos en el panel de Vindi llegan mediante el webhook charge_refunded y se añaden a las notas. El estado del pedido no cambia automáticamente; regístralos en PrestaShop con un reembolso manual 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 Vindi Gateway es el primer bloque de Modules > Module Manager > VibeFox Vindi 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 aparecen la línea Product: presta-payment-vindi 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 el inglés y el 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 tras 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 dominio. Libera el hueco en tu cuenta de vibefox.net.
Sin una clave activa, Vindi 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 queda oculto 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: las facturas ya creadas siguen confirmándose mediante el webhook de Vindi, 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 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
Vindi 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 BRL, que al menos un método está seleccionado en Offered methods y que el modo actual tiene una clave de API: Sandbox API key en modo sandbox, Live API key en modo producción. La página de ajustes muestra una advertencia cuando falta la clave o la moneda no es BRL. En Payment > Preferences comprueba que el módulo está permitido para BRL, para el país del cliente y para su grupo de clientes.
El pago se realizó, pero no se creó ningún pedido o el pedido sigue en Awaiting Vindi payment: el webhook no funciona. En Vindi comprueba que el webhook existe en la cuenta que usas (producción o sandbox), que su URL es exactamente la que aparece en la configuración, incluido el token, y que los cuatro eventos están seleccionados.
El webhook responde Forbidden: el token de la URL falta o es incorrecto. Copia de nuevo la URL desde la configuración.
El webhook responde Verification failed, retry later: la factura no se pudo leer desde la API de Vindi (por ejemplo, se eliminó la clave de API de ese entorno), el carrito estaba siendo actualizado por otra solicitud en ese mismo momento, o el pedido no se pudo crear (por ejemplo, el módulo está desactivado). Vindi vuelve a enviar la notificación. El registro muestra el motivo.
La URL del webhook muestra Method not allowed en el navegador: es normal. La URL solo acepta solicitudes de Vindi.
El cliente ve This payment method is temporarily unavailable: Vindi rechazó la clave de API. Comprueba la clave del modo actual.
El cliente ve un error al realizar el pedido: mira el campo Log en la página del módulo. Los errores se registran incluso cuando Debug log está desactivado. En el caso del boleto, la dirección de facturación debe tener la calle, el código postal, la ciudad y el estado.
El pedido está en Vindi payment on hold: lee las notas del bloque Vindi payment (véase Estados del pedido) y, después, completa el pedido o reembolsa el pago.
Pedidos sandbox antiguos tras cambiar a producción: cada pago conserva el entorno de su factura. Las comprobaciones, cancelaciones y reembolsos de los pedidos sandbox siguen usando la clave sandbox mientras esté en la configuración.
El reembolso falla: lee el mensaje. Los pagos con boleto no se pueden reembolsar a través de Vindi, y la clave de API del entorno del pago debe estar configurada.
Desinstalación
Ve a Modules > Module Manager, abre el menú junto a VibeFox Vindi 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, el token del webhook y los registros. Si está desactivado, todos los ajustes se conservan para una reinstalación posterior. Las facturas y los reembolsos de Vindi de los pedidos, así como los estados de pedido Awaiting Vindi payment y Vindi payment on hold, siempre se conservan, de modo que los pedidos pagados antes se pueden reembolsar tras una reinstalación. Los pedidos existentes conservan sus notas de pago y sus ID de transacción.
Vindi es una marca registrada de su respectivo propietario. Este módulo no está afiliado ni respaldado por Vindi.