VibeFox PagSeguro 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: real brasileño (BRL). El método de pago no aparece en la finalización de compra cuando la moneda de la tienda (o, en la página Pay for order, la del pedido) no es BRL.
HTTPS: tu sitio debe ser accesible desde Internet por HTTPS para que PagBank pueda enviar las notificaciones de pago.
Cuenta de PagBank: un token de producción para los pagos reales y un token de sandbox para las pruebas. Producción: inicia sesión en tu cuenta de PagBank, abre Venda online > Integrações y haz clic en Gerar token; PagBank envía el token por correo electrónico. Sandbox: crea una cuenta de sandbox en el portal de desarrolladores de PagBank y copia su token. Los tokens de sandbox y de producción solo funcionan en su propio entorno.
Clave de licencia de VibeFox: se compra en vibefox.net. Una clave funciona en un dominio.
Instalación
1. En WordPress, ve a Plugins > Add New > Upload Plugin, elige el archivo ZIP del plugin y haz clic en Install Now. También puedes subir la carpeta wcp_pagseguro_gateway a /wp-content/plugins/ por FTP.
2. Haz clic en Activate.
3. Abre los ajustes: WooCommerce > Settings > Payments > PagSeguro / PagBank > Manage, o haz clic en Settings debajo del nombre del plugin en la página Plugins.
4. 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.
5. Introduce el token de sandbox y, para cobrar pagos reales, el token de producción.
6. Activa Enable / Disable y guarda. Haz pagos de prueba con Sandbox Mode activado y desactívalo después para aceptar pagos reales.
Configuración
Todos los ajustes están en una sola página: WooCommerce > Settings > Payments > PagSeguro / PagBank. Debajo del título, la página muestra el modo actual: SANDBOX MODE (los pagos se crean en el sandbox de PagBank, sin cargos reales) o LIVE (los pagos se crean con el token de producción). Avisa cuando falta el token del modo actual (el método de pago se oculta entonces en la finalización de compra) y cuando la moneda de la tienda no es BRL. En la lista de métodos de pago, PagBank aparece como pendiente de configuración hasta que se introduce el token del modo actual, y se muestra una insignia de modo de prueba mientras el modo sandbox está activado.
General
Enable / Disable: Enable PagSeguro/PagBank payments activa o desactiva el método de pago. Por defecto: desactivado.
Title: el nombre del método de pago que ven los clientes en la finalización de compra. Por defecto: PagSeguro / PagBank.
Description: el texto que se muestra debajo del método de pago en la finalización de compra. Por defecto: Pay securely via PagSeguro/PagBank. You will be redirected to complete your payment.
Cuenta de PagBank
La sección explica dónde obtener los tokens y enlaza con tu cuenta de PagBank y con la página de PagBank sobre tokens.
Sandbox Mode: Enable sandbox/test mode (no real charges). Los pagos nuevos van al sandbox de PagBank con el token de sandbox, y en la finalización de compra aparece una nota SANDBOX MODE. Las consultas de estado y los reembolsos de un pedido siempre usan el entorno y el token con los que se creó su pago. Por defecto: activado.
Sandbox token: el token de sandbox de PagBank. Se usa mientras el modo sandbox está activado.
Production token: el token de producción de PagBank. Se usa cuando el modo sandbox está desactivado. Manténlo en secreto.
El token único de la versión 1.0 se traslada automáticamente: si el modo sandbox estaba activado, pasa a ser el token de sandbox; si no, sigue siendo el token de producción.
Notificaciones de pago
Cada pago indica a PagBank dónde comunicar los cambios de estado, así que no hay nada que configurar en PagBank. La sección muestra la URL de notificación. Tiene este aspecto: https://your-site/wc-api/webhook_wc_pagseguro/. La dirección debe ser accesible desde Internet por HTTPS.
Las notificaciones que incluyen un encabezado x-authenticity-token se comprueban con el token del entorno del pedido; una firma no válida se rechaza. El contenido de la notificación nunca se da por bueno: el plugin siempre lee el checkout y el pedido de PagBank desde la API de PagBank (estado, importe y moneda) antes de cambiar el pedido.
Avanzado
Debug log: Log API requests and notifications escribe los detalles en WooCommerce > Status > Logs, origen wcp_pagseguro_gateway. Los errores siempre se registran. Los registros no contienen tokens ni datos de clientes. Por defecto: desactivado.
Delete Data on Uninstall: Remove the gateway settings and logs when the plugin is deleted. Por defecto: desactivado.
Finalización de compra
El cliente elige el método de pago (por defecto PagSeguro / PagBank) y realiza el pedido. El plugin crea un checkout de PagBank por el total exacto del pedido en BRL como un único artículo, Order # con el número del pedido y el nombre de tu tienda, y envía al cliente a la página de pago de PagBank. El nombre y el correo electrónico del cliente, el CPF o CNPJ de los campos del plugin Brazilian Market on WooCommerce y un número de teléfono brasileño se rellenan cuando la tienda los tiene; el cliente puede completarlos o corregirlos en la página de PagBank. El cliente paga con los métodos habilitados en tu cuenta de PagBank, por ejemplo tarjeta de crédito, PIX o boleto.
La página de pago caduca 5 minutos antes de que el temporizador Hold stock de WooCommerce cancele el pedido sin pagar (como mínimo 10 minutos), o a los 120 minutos si no se reservan existencias.
Después de pagar, el cliente vuelve a la tienda. El regreso se comprueba igual que una notificación: el plugin lee el pago desde la API de PagBank, y el regreso por sí solo nunca marca un pedido como pagado. Un pedido pagado, o un pago que está pendiente (boleto, PIX, análisis), pasa a la página de pedido recibido; el pedido se confirma con la notificación si PagBank aún no la ha enviado.
Si el pago no se completó, el cliente vuelve a la página Pay for order con The PagBank payment was not completed. You can pay the order again below., The PagBank payment page has expired. You can pay the order again below. o The payment was declined by PagBank. Please try again with another card or payment method. Si el pago se canceló y con él el pedido, el cliente va al carrito con The PagBank payment was cancelled, so the order was cancelled.
Cuando el cliente vuelve a pagar, el checkout abierto de PagBank se reutiliza si el importe y el entorno son los mismos y no caduca en menos de 10 minutos. En caso contrario, el checkout anterior se desactiva y ya no se puede pagar. Un pago hecho en la página anterior antes de eso sigue contando para el pedido.
Si PagBank no puede iniciar el pago, el cliente ve un mensaje breve, por ejemplo PagBank did not accept your billing details (CPF/CNPJ). Please check them and try again. o Could not connect to PagBank. Please try again in a moment. El motivo que indica PagBank se añade a las notas del pedido.
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 (HPOS) de WooCommerce.
El plugin no tiene formulario de tarjeta en la tienda, ni tarjetas guardadas, ni suscripciones o pagos recurrentes, ni pagos divididos ni marketplaces. Los métodos de pago y las cuotas son los que configures en tu cuenta de PagBank.
Pedidos y reembolsos
Estados del pedido
Pending payment: el cliente fue enviado a PagBank y aún no ha pagado. Una nota muestra el ID del checkout de PagBank y el entorno. Si la página de pago caduca sin pago, una nota lo indica y el estado no cambia.
Processing: el pago se confirmó. Es el estado estándar de WooCommerce después del pago; los pedidos que solo contienen productos virtuales descargables pasan a Completado. La nota del pedido muestra el importe, el método de pago y el ID de cargo de PagBank, que también es el ID de transacción del pedido.
On hold: se generó un boleto o un PIX y está pendiente de pago; el pago está en análisis; un pago con tarjeta fue autorizado pero no capturado (captúralo en PagBank); el importe o la moneda pagados no coinciden con el pedido; o un pago llegó después de que WooCommerce cancelara el pedido sin pagar (comprueba las existencias y después completa el pedido o reembolsa el pago en PagBank). La nota del pedido lo explica.
Failed: el pago fue rechazado. El cliente puede volver a pagar desde la página Pay for order.
Cancelled: el pago se canceló, por ejemplo un boleto o PIX vencido.
Refunded: el pago se reembolsó por completo desde el panel de PagBank.
Cada estado de PagBank se aplica una sola vez, así que las notificaciones o regresos repetidos no añaden notas, correos electrónicos ni reducciones de existencias. Si llega un segundo pago para un pedido que ya está pagado, una nota te pide reembolsarlo en PagBank.
Reembolsos
Abre el pedido, haz clic en Refund, introduce el importe y haz clic en Refund via PagSeguro / PagBank (el botón muestra el título de tu método de pago). Se admiten reembolsos totales y parciales. El reembolso se envía en el entorno y con el token con los que se hizo el pago. Un reembolso solo se registra cuando PagBank lo confirma; en caso contrario, WooCommerce muestra el error, por ejemplo PagBank refund failed: ... o PagBank did not confirm the refund, y no se registra nada. Los reembolsos de pagos con boleto y los reembolsos parciales de PIX siguen las normas de PagBank. Un reembolso correcto se añade a las notas del pedido con el ID de cargo.
Los reembolsos hechos en el panel de PagBank no se importan como líneas de reembolso de WooCommerce. Un reembolso total marca el pedido como Reembolsado; un reembolso parcial añade una nota con el importe reembolsado, y puedes añadir el reembolso al pedido manualmente.
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 > PagSeguro / PagBank. 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 quitarla de este sitio. El enlace Manage licenses and domains in your account abre tu cuenta de vibefox.net.
Una clave funciona en un 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, PagBank 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 gestores de la tienda que han iniciado sesión siguen viendo el método de pago, marcado como (unlicensed — visible to admins only), así que puedes configurar y probar el plugin antes de comprar una clave. Aparece un recordatorio en la página 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 requieren una renovación. El estado se vuelve a comprobar automáticamente en segundo plano.
Solución de problemas
PagBank no aparece en la finalización de compra: revisa que la licencia esté activa, que Enable / Disable esté activado, que el token del modo actual esté configurado (Sandbox token en modo sandbox, Production token en modo real) y que la moneda de la tienda sea BRL. La página de ajustes muestra un aviso en cada caso.
El pago se realizó, pero el pedido sigue en Pendiente de pago: PagBank aún no ha informado del pago y el cliente no volvió a la tienda. El pedido se actualiza en cuanto llega la notificación. Comprueba que tu sitio sea accesible desde Internet por HTTPS y revisa WooCommerce > Status > Logs, origen wcp_pagseguro_gateway.
La notificación responde Invalid signature: el x-authenticity-token no coincide con el token del entorno en el que se pagó el pedido. Comprueba que el token correcto esté en los ajustes.
La notificación responde Verification failed, retry later: no se pudo contactar con la API de PagBank, falta el token del entorno del pedido o otra solicitud estaba actualizando el pedido en ese mismo momento. PagBank reintenta la notificación.
La notificación responde Order not found: el pedido no existe en esta tienda o se pagó con otro método de pago. No se cambia nada.
El cliente ve This order is already being processed: una notificación o el regreso del cliente estaban actualizando el pedido a la vez. El cliente puede intentarlo de nuevo en un momento.
El cliente ve PagBank payments are temporarily unavailable: falta el token del modo actual o PagBank lo rechazó.
El cliente ve PagSeguro/PagBank only accepts payments in Brazilian Real (BRL): el pedido está en otra moneda.
El pedido está en On hold con la nota Amount/currency does not match: PagBank informó de un pago cuyo importe o moneda difiere del total del pedido, por ejemplo porque el pedido se editó después de crear la página de pago. Compara los importes en PagBank y completa o reembolsa el pedido manualmente.
El reembolso falla con un mensaje sobre el token: el pago se hizo en sandbox o en producción, y el token de ese entorno falta o fue rechazado. Introduce el token correcto e inténtalo de nuevo.
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 contactar con el servidor de licencias, el plugin sigue funcionando con el último estado conocido.
Desinstalación
Desactivar el plugin mantiene 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. Los ajustes de la pasarela, las demás opciones del plugin y sus 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 PagBank.
PagSeguro y PagBank son marcas comerciales de sus respectivos titulares. Este plugin no está afiliado ni respaldado por PagSeguro ni por PagBank.