VibeFox Vindi for WooCommerce — Ayuda
Requisitos
WordPress: 6.0 o posterior.
WooCommerce: 8.0 o posterior, instalado y activo. El plugin no se activa sin él.
PHP: 8.0 o posterior.
Moneda de la tienda: real brasileño (BRL). Vindi cobra solo en BRL, así que el método de pago se oculta para 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 aparte, 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 WordPress ve a Plugins > Add New > Upload Plugin, elige el archivo ZIP del plugin, haz clic en Install Now y luego en Activate. También puedes subir la carpeta wcp_vindi_gateway a /wp-content/plugins/ por FTP.
2. Abre la configuración: WooCommerce > Settings > Payments > Vindi > Manage, o haz clic en Settings debajo del nombre del plugin en la página de Plugins.
3. Introduce tu clave de licencia de VibeFox en el bloque de licencia de la parte superior de la página y haz clic en Activate.
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 a Vindi (consulta Configuración).
6. Activa Enable / Disable y guarda. Prueba un pago en modo sandbox y luego desmarca Sandbox mode para aceptar pagos reales.
Configuración
Todos los ajustes están en una sola página: WooCommerce > Settings > Payments > Vindi. 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 aparece en la finalización de compra. En la lista de métodos de pago, Vindi aparece marcado como pendiente de configuración hasta que el modo actual tenga una clave de API. Al guardar, las claves se recortan, y si no hay ningún método de pago seleccionado, se selecciona tarjeta de crédito y la página muestra Choose at least one payment method — credit card was selected.
General
Enable / Disable: Enable Vindi payments activa o desactiva el método de pago. Por defecto: off.
Title: el nombre del método de pago que se muestra en la finalización de compra. Por defecto: Vindi.
Description: el texto que se muestra debajo del método de pago en la finalización de compra. Por defecto: Pay by credit card on the secure Vindi page, or by boleto / PIX.
API keys
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. Cada pedido recuerda dónde se creó su factura, así que las comprobaciones, las cancelaciones y los reembolsos siempre usan ese entorno.
Sandbox mode: Create new payments in the Vindi sandbox usa 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. Por defecto: on. Desmárcalo 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 de sandbox de Vindi.
Métodos de pago
Offered methods: los métodos que el cliente puede elegir. Por defecto: credit card. Los métodos también deben estar activados en tu cuenta de Vindi.
Notificaciones de pago (webhook)
El webhook avisa a tu tienda de que una factura se ha pagado, cancelado o reembolsado. Esta sección de la configuración muestra la URL del webhook. Tiene este aspecto: https://your-site/wc-api/webhook_wc_vindi/?token=... y contiene un token secreto creado por el plugin. 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:
Las solicitudes con un token ausente o incorrecto se rechazan. Cada notificación solo hace que el plugin vuelva a leer la factura a través de la API de Vindi antes de cambiar un pedido. Sin el webhook, los pagos con tarjeta, boleto y PIX solo se confirman cuando el cliente abre la página de pedido recibido.
Avanzado
Debug log: Log API calls and notifications escribe los detalles en WooCommerce > Status > Logs, origen wcp_vindi_gateway. Los errores y las advertencias siempre se registran, aunque esta opción esté desactivada. Las claves y los datos de los clientes nunca se registran. Por defecto: off.
Delete data on uninstall: Remove the settings, webhook token and logs when the plugin is deleted. Por defecto: off.
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 solo se ofrecen esos métodos; si no, muestra Required for boleto and PIX. El número se valida con sus dígitos de control. En la finalización de compra clásica, el campo no aparece cuando Brazilian Market on WooCommerce está activo, porque ese plugin ya pide el CPF / CNPJ. En ese caso se usan su CPF / CNPJ, el número de casa y el barrio. 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.
Al realizar el pedido, el plugin crea un cliente de Vindi para ese pedido a partir de los datos de facturación, y una factura de Vindi por el total del pedido, en una sola cuota.
Credit card: el cliente es enviado a la página de factura de Vindi y paga allí. Vindi no tiene URL de retorno para las facturas, así que el cliente no vuelve a la tienda automáticamente. El pedido se confirma con el webhook o cuando el cliente abre la página de pedido recibido. Mientras el pago no esté completo, esa página y el pedido en My account muestran Your payment has not been completed yet. y un botón Pay at Vindi.
Boleto, PIX and BolePix: la factura se emite de inmediato, el pedido pasa a En espera y el cliente llega a la página de pedido recibido. Allí, y en My account > Orders, una sección Payment muestra el código QR de PIX, el código PIX de copiar y pegar con un botón Copy code y su fecha de vencimiento, y un botón Open boleto. El correo de pedido en espera del cliente y el correo de la factura contienen el código PIX y el enlace del boleto.
El pedido solo se marca como pagado después de que Vindi lo confirme: el plugin lee la factura desde la API de Vindi y comprueba que pertenece al pedido (código del pedido y cliente de Vindi) y que el importe pagado coincide con el total del pedido.
Un cliente puede volver a pagar un pedido no pagado desde la página Pay for order. Si el método, el importe y el entorno son los mismos, se reutiliza la factura pendiente de Vindi. Si no, se cancela en Vindi antes de crear una nueva, de modo que el cliente no pueda pagar dos veces el mismo pedido. Si la factura anterior se pagó mientras tanto, el pedido se marca como pagado y no se crea ninguna factura nueva.
Si Vindi no puede iniciar el pago, el cliente ve un mensaje breve, por ejemplo para que revise el CPF / CNPJ, la dirección de facturación, el correo electrónico o el teléfono, o para indicar que Vindi no está disponible temporalmente. Si otra solicitud está procesando el mismo pedido en ese momento, se pide al cliente que espere un momento y lo intente de nuevo.
El método de pago funciona en la finalización de compra clásica, en el bloque de Finalizar compra y en la página Pay for order. Es compatible con el almacenamiento de pedidos de alto rendimiento de WooCommerce (HPOS).
El plugin admite pagos únicos en una sola cuota. No tiene suscripciones ni facturación recurrente, ni tarjetas guardadas, ni 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
Pending payment: se inició un pago con tarjeta y Vindi todavía no lo ha confirmado.
On hold: un pago con boleto, PIX o BolePix está esperando (nota Awaiting ... payment at Vindi.), o la factura de Vindi está en revisión.
Processing or Completed: el pago se confirmó. El estado se asigna de la forma estándar de WooCommerce: Procesando, o Completado para pedidos con solo productos virtuales descargables. La nota del pedido muestra la factura de Vindi, el importe y el entorno. El ID de la transacción es el ID de la factura de Vindi.
On hold after payment: la factura pagada no coincide con el pedido (importe, código del pedido o cliente de Vindi), o la factura se pagó después de que el pedido se hubiera cancelado. La nota del pedido lo explica. Revisa el pedido y el stock, y luego completa el pedido o reembolsa el pago.
Failed: Vindi rechazó el intento de pago. La nota muestra el motivo del adquirente si lo hay. El cliente todavía puede pagar la misma factura, y un pago posterior completa el pedido.
Cancelled: la factura se canceló en Vindi, o el pedido fue cancelado por ti, por el cliente o por el tiempo de espera de la reserva de stock de WooCommerce. Cuando un pedido se cancela 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 que canceles la factura en el panel de Vindi. Antes de que el tiempo de espera de la reserva de stock cancele un pedido, la factura se comprueba: si se pagó mientras tanto, el pedido se marca como pagado.
Si se paga una segunda factura de un pedido que ya está pagado, el pedido no se vuelve a modificar. Una nota te pide que reembolses un pago en Vindi.
Reembolsos
Abre el pedido, haz clic en Refund, introduce el importe y haz clic en Refund via Vindi. Se admiten reembolsos totales y parciales de pagos con tarjeta y PIX. Un reembolso total también cancela la factura en Vindi. El reembolso se envía en el entorno del pago (producción o sandbox), así que la clave de API de ese entorno debe estar configurada. Un reembolso correcto se añade a las notas del pedido con el cargo de Vindi y el estado. Si Vindi o el adquirente rechazan el reembolso, WooCommerce muestra el error y no se registra ningún reembolso.
Vindi no puede reembolsar pagos con boleto. El plugin muestra Vindi cannot refund boleto payments. Return the money to the customer by bank transfer and record the refund manually.
Los reembolsos hechos en el panel de Vindi llegan mediante el webhook charge_refunded y se añaden a las notas del pedido. No se registran automáticamente como reembolsos de WooCommerce. Si hace falta, crea un reembolso manual en WooCommerce sin usar Refund via Vindi.
Clave de licencia
El plugin funciona con una clave de licencia de VibeFox de vibefox.net. El bloque de licencia está en la parte superior de WooCommerce > Settings > Payments > Vindi. Pega la clave en License key y haz clic en Activate. El bloque muestra el estado, por ejemplo la fecha hasta la que la licencia está activa, y tu dominio. Usa Check now para volver a comprobar el estado, Change key para introducir otra clave y Remove key para eliminarla de este sitio. El enlace Manage licenses and domains in your account abre tu cuenta de vibefox.net.
Una clave funciona en un solo dominio. Quitar la clave de un sitio no libera su plaza de dominio. Libérala en tu cuenta de vibefox.net.
Sin una clave activa, Vindi no se muestra a los clientes en la finalización de compra. Si un pago se inicia de todos modos, el cliente ve This payment method is not available. Please choose another one. Los administradores de la tienda que han iniciado sesión siguen viendo el método de pago, marcado como (unlicensed — visible to admins only), para que puedas configurar y probar el plugin antes de comprar una clave. Un recordatorio aparece en la página de Plugins y en las páginas de WooCommerce. Los pedidos existentes no se ven afectados: los pagos ya iniciados se siguen confirmando y los reembolsos funcionan.
Cuando una licencia caduca, el plugin sigue funcionando, pero las actualizaciones y el soporte necesitan una renovación. El estado se vuelve a comprobar automáticamente en segundo plano.
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 de la tienda sea BRL, que al menos un método esté seleccionado en Offered methods y que el modo actual tenga una clave de API: Sandbox API key en modo sandbox, Live API key en modo producción. La página de configuración muestra una advertencia cuando falta la clave o la moneda no es BRL.
El pago se realizó, pero el pedido sigue en Pending payment u On hold: el webhook no funciona. En Vindi comprueba que el webhook exista en la cuenta que usas (producción o sandbox), que su URL sea exactamente la que aparece en la configuración, incluido el token, y que se hayan seleccionado los cuatro eventos. El pedido también se confirma cuando el cliente abre la página de pedido recibido.
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 o Order busy, retry later: la factura no se pudo leer desde la API de Vindi (por ejemplo, la clave de API de ese entorno se eliminó), o el pedido estaba siendo actualizado por otra solicitud en ese mismo momento. Vindi envía la notificación de nuevo.
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: abre las notas del pedido o el registro en WooCommerce > Status > Logs, origen wcp_vindi_gateway. Los errores se registran aunque Debug log esté desactivado. Para el boleto, la dirección de facturación debe tener calle, código postal, ciudad y estado.
El pedido está On hold después del pago: lee la nota del pedido. El importe pagado, el código del pedido o el cliente de Vindi no coincidían con el pedido, o el pago llegó después de que el pedido se cancelara. Completa el pedido o reembolsa el pago.
Pedidos antiguos de sandbox tras cambiar a producción: cada pedido conserva el entorno de su factura. Las comprobaciones, cancelaciones y reembolsos de los pedidos de sandbox siguen usando la clave del 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.
El bloque de licencia muestra un error: sigue el mensaje del bloque. Por ejemplo, si la clave ya se usa en otro dominio, libera una plaza en tu cuenta de vibefox.net y haz clic en Check now. Si cambió la dirección del sitio, haz clic en Check now para activar la clave en el nuevo dominio. Si no se puede acceder al servidor de licencias, el plugin sigue funcionando con el último estado conocido.
Desinstalación
Desactivar el plugin conserva todos los datos. Para eliminarlo, desactívalo y bórralo en la página Plugins. La clave de licencia y el estado de licencia de este plugin siempre se eliminan. La configuración de la pasarela, el token del webhook, los demás datos guardados del plugin y los registros solo se eliminan si Delete data on uninstall estaba activado. Si no, se conservan para una reinstalación posterior. Los pedidos existentes conservan sus notas de pago, IDs de transacción y datos de Vindi.
Vindi es una marca registrada de su respectivo titular. Este plugin no está afiliado a Vindi ni cuenta con su respaldo.