VibeFox PagSeguro 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: real brasileño (BRL). El método de pago solo se muestra para carritos en BRL.
HTTPS: tu tienda 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 para 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 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 PagSeguro 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, dentro del bloque de licencia de la parte superior de la página de configuración, y haz clic en Activate (véase Clave de licencia).
4. Introduce el token de sandbox y, para aceptar pagos reales, el token de producción.
5. Activa Enable / Disable y haz clic en Save. Haz pagos de prueba con Sandbox Mode activado y después desactívalo para aceptar pagos reales.
Al instalarse, el módulo crea dos estados de pedido, Awaiting PagBank payment y PagBank 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; la moneda BRL debe seguir permitida para el módulo.
Configuración
Todos los ajustes están en la página del módulo: Modules > Module Manager > VibeFox PagSeguro Gateway > Configure. Cada sección tiene su propio botón Save, que guarda toda la página. Encima de los campos, 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 (en ese caso el método de pago se oculta en el checkout) y cuando la moneda predeterminada de la tienda no es BRL (entonces el método de pago no se ofrece para carritos en otras monedas).
PagSeguro / PagBank
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 el checkout. También es el nombre del método de pago guardado en el pedido. Por defecto: PagSeguro / PagBank. Obligatorio.
Description: el texto que se muestra debajo del método de pago en el checkout. 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 a tu cuenta de PagBank y a 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 los clientes ven SANDBOX MODE — Using test environment. No real charges. debajo del método de pago. Las comprobaciones 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 (Bearer). Se usa cuando el modo sandbox está desactivado. Guárdalo en secreto.
Los tokens guardados 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 tokens: marca un token y haz clic en Save para eliminarlo. Un campo vacío mantiene el valor guardado.
Notificaciones de pago
Notification URL: cada pago indica a PagBank dónde informar los cambios de estado, así que no hay nada que configurar en PagBank. La sección muestra la URL. Con URLs amigables tiene este aspecto: https://your-shop/module/wcp_pagseguro_gateway/webhook. 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 en el que se creó el pago; una firma no válida se rechaza. El cuerpo de la notificación nunca se considera fiable: el módulo siempre lee el checkout y el pedido de PagBank desde la API (estado, importe y moneda) antes de crear o modificar un pedido. Sin notificaciones, el pedido se crea cuando el cliente vuelve a la tienda después de pagar.
Avanzado
Debug log: Log API requests and notifications escribe los detalles en logs/wc_psg_debug.log.php, en la carpeta del módulo. El archivo no se puede abrir desde la web. Los registros no contienen tokens ni datos de clientes. Los errores siempre se registran. Por defecto: desactivado.
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 la configuración de la pasarela y el registro. Los pedidos, sus referencias de PagBank (necesarias para los reembolsos) y los estados de pedido siempre se conservan. Por defecto: desactivado.
Proceso de pago
En el paso de pago, el cliente elige el método de pago (por defecto PagSeguro / PagBank) y confirma. El módulo crea un checkout de PagBank por el total del carrito en BRL como un único artículo, Order # con el número del carrito 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 del campo Identification number o VAT number de la dirección y un 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 a los 120 minutos. En este punto todavía no existe ningún pedido.
Después de pagar, el cliente vuelve a tu tienda. El pedido se marca como pagado solo cuando PagBank lo confirma: el módulo lee el pago desde la API de PagBank cuando llega la notificación o cuando el cliente regresa, y un regreso por sí solo nunca marca un pedido como pagado. Entonces se crea el pedido y el cliente ve la página de confirmación del pedido con Your payment with PagBank has been received. Para un boleto o PIX generado, o un pago en análisis, la página muestra Your PagBank payment is awaiting confirmation (boleto / PIX / analysis). The order will be confirmed as soon as PagBank reports the payment. Si ese pago se rechaza o se cancela más tarde, la página muestra Your PagBank payment was not completed. Please contact us about this order. Si PagBank todavía no ha confirmado el pago cuando el cliente regresa, aparece una página Payment confirmation con We are confirming your payment with PagBank. The order will be updated automatically — please do not pay again. y un botón Check again.
Si el pago no se completó, el cliente vuelve al checkout 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. El carrito se conserva. Si un pedido que esperaba un boleto o PIX se canceló, el cliente ve The PagBank payment was cancelled, so the order was cancelled.
Cuando el cliente paga de nuevo, el checkout de PagBank abierto se reutiliza si el importe y el entorno son los mismos y no caduca en los próximos 10 minutos. En caso contrario, el checkout anterior se desactiva y ya no se puede pagar. Un pago hecho antes en la página anterior sigue contando para el carrito, y se crea el pedido en lugar de un nuevo pago.
Si PagBank no puede iniciar el pago, el cliente se queda en el checkout con 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 técnico se escribe en el registro.
Las notificaciones funcionan con la tienda en modo de mantenimiento y no las bloquea la restricción por país de tu tienda.
El módulo 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
Sin pedido todavía: el cliente fue enviado a PagBank y no ha pagado, la tarjeta fue rechazada o la página de pago caducó. Solo existe el carrito, y el cliente puede volver a pagar.
Payment accepted: el pago se confirmó con el importe y la moneda esperados. El pago se registra con el ID de cargo de PagBank como ID de transacción, y una nota muestra el importe, el método de pago y el ID de cargo.
Awaiting PagBank payment: se generó un boleto o PIX que espera pago, o el pago está en análisis. El pedido pasa a Payment accepted cuando PagBank informa de que está pagado.
PagBank payment on hold: PagBank informó de un importe o una moneda distintos de los del carrito (por ejemplo, el carrito se modificó después de crear la página de pago), un pago llegó después de que el pedido se cancelara (revisa el stock y después completa el pedido o reembolsa el pago en PagBank), o un pago con tarjeta fue autorizado pero no capturado (captúralo en PagBank). La nota lo explica. El dinero realmente recibido se registra en el pedido.
Payment error: un pago que estaba pendiente o en análisis fue rechazado.
Canceled: un pago que estaba pendiente, por ejemplo un boleto o PIX vencido, fue cancelado.
Refunded: el pago se reembolsó por completo, a través del módulo o en el panel de PagBank.
Cada estado de PagBank se aplica una sola vez, así que las notificaciones o los regresos repetidos no añaden notas ni cambios de estado. Si llega un segundo pago para un pedido que ya está pagado, el pedido no cambia y una nota te pide que reembolses el duplicado en PagBank.
Bloque «PagBank payment»
La página del pedido muestra un bloque PagBank payment con el checkout de PagBank, los ID del pedido y del cargo de PagBank, el método de pago, el estado, el importe pagado y reembolsado, una insignia Sandbox para los pagos de sandbox, el historial de reembolsos y las PagBank notes del pedido.
Reembolsos
En el bloque PagBank payment, introduce el importe (se rellena el importe aún no reembolsado), opcionalmente un motivo, y haz clic en Refund via PagBank. Confirma la pregunta Refund this amount through PagBank? 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. El límite es el importe que cobró PagBank, así que, tras una discrepancia de importe, puedes reembolsar hasta lo que el cliente pagó realmente, no el total del pedido. 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; si no, el bloque 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 al historial de reembolsos y a las notas con el ID de cargo. Un reembolso total pone el pedido en Refunded; un reembolso parcial no cambia el estado. Los reembolsos están disponibles cuando PagBank ha informado de que el pago está pagado.
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 PagBank.
Los reembolsos hechos en el panel de PagBank se ven con la siguiente notificación: un reembolso total pone el pedido en Refunded, un reembolso parcial añade una nota con el importe reembolsado, y puedes registrar el reembolso en el pedido manualmente.
Clave de licencia
El módulo funciona con una clave de licencia de VibeFox de vibefox.net. El bloque de licencia License — VibeFox PagSeguro Gateway es el primer bloque de Modules > Module Manager > VibeFox PagSeguro Gateway > Configure, 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-pagseguro 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. 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, PagBank no se muestra a los clientes en el checkout. Si aun así se inicia un pago, el cliente ve This payment method is not available. Please choose another one. La tienda 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 el checkout. 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 por 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
PagBank no aparece en el checkout: comprueba 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 live) y que la moneda del carrito sea BRL. La página de configuración muestra un aviso cuando falta el token o cuando la moneda de la tienda 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: PagBank todavía no ha informado del pago y el cliente no volvió a la tienda. El pedido se crea en cuanto llega la notificación. Comprueba que tu tienda sea accesible desde Internet por HTTPS en la Notification URL y activa el Debug log para ver las notificaciones.
La notificación responde Invalid signature: el x-authenticity-token no coincide con el token del entorno en el que se realizó el pago, o ese token no está guardado. Comprueba que el token correcto esté en la configuración.
La notificación responde Verification failed, retry later: no se pudo contactar con la API de PagBank, falta el token del entorno del pago, o otra petición estaba procesando el carrito en ese mismo momento. PagBank vuelve a intentar la notificación.
La notificación responde Order not found: la notificación corresponde a un carrito que no se pagó con este módulo en esta tienda. No se modifica nada.
El cliente ve PagBank payments are temporarily unavailable. Please choose another payment method.: falta el token del modo actual o PagBank lo ha rechazado.
El cliente ve PagSeguro/PagBank only accepts payments in Brazilian Real (BRL).: el carrito está en otra moneda.
El pedido está en PagBank payment on hold: lee las notas del bloque PagBank payment (ver Estados del pedido), compara los importes en PagBank y después completa el pedido o reembolsa el pago.
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 ha sido rechazado. Introduce el token correcto y vuelve a intentarlo.
Desinstalación
Ve a Modules > Module Manager, abre el menú junto a VibeFox PagSeguro Gateway y elige Uninstall. La clave de licencia y el estado de la licencia de este módulo se eliminan siempre. Si Delete Data on Uninstall está activado, se eliminan la configuración de la pasarela y el registro. Si está desactivado, todos los ajustes se conservan para una reinstalación posterior. Los pagos y reembolsos de PagBank de los pedidos y los estados de pedido Awaiting PagBank payment y PagBank 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 e ID de transacción.
PagSeguro y PagBank son marcas registradas de sus respectivos titulares. Este módulo no está afiliado ni respaldado por PagSeguro ni por PagBank.