VibeFox Pagar.me 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 se oculta cuando la moneda de la tienda (o, en la página Pay for order, la del pedido) no es BRL.
Cuenta de Pagar.me: necesitas las claves secretas de tu cuenta de Pagar.me: la clave de prueba (sk_test_...) y, para pasar a producción, la clave de producción (sk_...). Están en el panel de Pagar.me, en Development > Keys. Solo se usan las claves secretas; la clave pública (pk_...) no es necesaria. Solo se pueden ofrecer los métodos de pago habilitados en tu cuenta de Pagar.me.
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_pagarme_gateway a /wp-content/plugins/ por FTP.
2. Haz clic en Activate.
3. Abre los ajustes: WooCommerce > Settings > Payments > Pagar.me > 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 la clave secreta de prueba y, cuando pases a producción, la clave secreta de producción.
6. Crea el webhook en el panel de Pagar.me con la URL que muestran los ajustes (ver Configuración).
7. Activa Enable / Disable y guarda. Haz pagos de prueba con Test mode activado y luego desactívalo para aceptar pagos reales.
Configuración
Todos los ajustes están en una sola página: WooCommerce > Settings > Payments > Pagar.me. Bajo el título, la página muestra el modo actual: TEST MODE (los pagos se crean con la clave secreta de prueba, sin cargos reales) o LIVE. Avisa cuando falta la clave secreta del modo actual (en ese caso el método de pago se oculta en la finalización de compra), cuando la clave de prueba no empieza por sk_test_, cuando la clave de producción no empieza por sk_ o es una clave de prueba, y cuando la moneda de la tienda no es BRL. En la lista de métodos de pago, Pagar.me aparece como pendiente de configuración hasta que se introduce la clave del modo actual, y se muestra una insignia de modo de prueba mientras este esté activado.
General
Enable / Disable: Enable Pagar.me 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: Pagar.me.
Description: el texto que se muestra bajo el método de pago en la finalización de compra. Por defecto: Pay securely via Pagar.me (credit card, PIX or boleto). You will be redirected to complete your payment.
Claves de API
Copia las claves secretas desde el panel de Pagar.me: Development > Keys. Pagar.me usa una sola dirección de API para pagos de prueba y de producción; la clave determina si un pago es de prueba o real.
Test mode: Use the test secret key (no real charges). Mientras el modo de prueba esté activado, en la finalización de compra se muestra una nota TEST MODE. Las consultas de estado y los reembolsos de un pedido siempre usan la clave del modo en el que se creó su pago. Por defecto: activado.
Test secret key: la clave secreta de prueba de Pagar.me (sk_test_...). Se usa mientras el modo de prueba está activado.
Live secret key: la clave secreta de producción de Pagar.me (sk_...). Se usa cuando el modo de prueba está desactivado. Mantenla en secreto.
La clave secreta única de la versión 1.0 se traslada automáticamente: una clave de prueba pasa a Test secret key y el modo de prueba se activa; en caso contrario, se mantiene como clave de producción y el modo de prueba se desactiva.
Página de pago
Payment methods: los métodos que se ofrecen en la página de pago de Pagar.me. Elige solo los métodos habilitados en tu cuenta de Pagar.me. Por defecto: Credit card, PIX y Boleto.
Boleto due in (days): número de días hasta el vencimiento del boleto, de 1 a 30. El pedido permanece en espera hasta que Pagar.me confirme el pago. Por defecto: 3.
Notificaciones de pago (webhook)
En el panel de Pagar.me, abre Settings > Webhooks y crea un webhook con la URL que aparece en esta sección. Tiene este aspecto: https://your-site/wc-api/webhook_wc_pagarme/. Cópiala exactamente como la muestran los ajustes.
Selecciona estos eventos:
El webhook no necesita contraseña ni firma. Su contenido nunca se da por válido: la tienda solo toma de él el ID del pedido de Pagar.me y lee ese pedido desde la API de Pagar.me con la clave del modo en que se creó. Las notificaciones de pedidos de otras tiendas de la misma cuenta de Pagar.me se ignoran. Sin el webhook, los pagos de PIX y boleto realizados más tarde solo se confirman cuando el cliente vuelve a la tienda.
Avanzado
Debug log: Log API requests and notifications escribe los detalles en WooCommerce > Status > Logs, origen wcp_pagarme_gateway. Los errores se registran siempre. Los registros no contienen claves 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 Pagar.me) y realiza el pedido. Es obligatorio un correo electrónico de facturación válido. El plugin crea un pedido de Pagar.me por el total en BRL, con las líneas del pedido, el envío y las tasas (o una sola línea Order # con el número de pedido cuando las líneas no pueden sumar exactamente), y envía al cliente a la página de pago de Pagar.me. El nombre, el correo electrónico y, en Brasil, el teléfono y la dirección de facturación del cliente se pasan a Pagar.me. El CPF o CNPJ se toma de los campos de Brazilian Market on WooCommerce cuando existen; en caso contrario, el cliente lo introduce en la página de Pagar.me.
Después de pagar, el cliente vuelve a tu tienda. El pedido solo se marca como pagado cuando Pagar.me lo confirma: la tienda lee el pedido de Pagar.me desde la API, y el importe y la moneda pagados deben coincidir con el pedido. Un pago con tarjeta, PIX o boleto ya pagado marca el pedido como pagado. Un PIX o boleto emitido que aún no se ha pagado pone el pedido en espera hasta que Pagar.me confirme el pago mediante webhook.
Si el cliente vuelve sin pagar, o el pago fue rechazado o cancelado, el cliente va a la página Pay for order con The Pagar.me payment was not completed. You can pay the order below. o The Pagar.me payment was declined or canceled. You can try again below.
Cuando el cliente vuelve a pagar, se reutiliza la página de pago de Pagar.me abierta si el importe y el modo son los mismos; en caso contrario, se cierra en Pagar.me antes de crear una nueva. Si el intento anterior se pagó mientras tanto, o su PIX o boleto sigue pendiente, el pedido se actualiza sin un nuevo pago. Si la página anterior no se puede cerrar, sigue asociada al pedido, de modo que un pago realizado en ella se registra igualmente.
Si Pagar.me no puede iniciar el pago, el cliente ve un mensaje breve, por ejemplo Could not connect to Pagar.me. Please try again in a moment., o el mensaje de Pagar.me sobre datos de facturación no válidos. El motivo técnico 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 incluye formulario de tarjeta en tu finalización de compra, ni tarjetas guardadas, suscripciones o pagos recurrentes, ni reglas de cuotas, ni pagos divididos (marketplace), ni pagos con tarjeta solo de autorización, ni integración con Pagar.me Hub.
Pedidos y reembolsos
Estados del pedido
Pending payment: el cliente fue enviado a Pagar.me y todavía no ha pagado ni emitido un PIX o boleto. Una nota muestra el ID del pedido de Pagar.me y el modo.
Processing: el pago se confirmó. Es el estado estándar de WooCommerce tras el pago; los pedidos con solo productos virtuales descargables pasan a Completado. La nota del pedido muestra el ID del pedido de Pagar.me y el método de pago. El ID de transacción es el ID del pedido de Pagar.me (or_...).
On hold: se emitió un PIX o boleto (o un pago con tarjeta está en análisis) y espera el pago; o el boleto se pagó solo parcialmente; o el importe o la moneda pagados difieren del pedido; o un pago llegó después de cancelar el pedido; o el pedido se pagó en Pagar.me después de que el cliente cambiara a otro método de pago; o se abrió un contracargo sobre un pedido pagado. La nota del pedido lo explica. Revisa el pedido y cámbialo a Procesando, o reembolsa el pago en Pagar.me.
Failed: el pago falló, o el pedido de Pagar.me se canceló o caducó (por ejemplo, un boleto no pagado). Solo el último intento de un pedido no pagado puede hacerlo fallar. El cliente puede volver a pagar.
Refunded: el pago se reembolsó o canceló en Pagar.me.
Cada estado de Pagar.me se aplica una sola vez, de modo que los webhooks o regresos repetidos no añaden notas, correos electrónicos ni reducciones de stock. Un pedido pagado nunca vuelve a pendiente o fallido, y un pedido cancelado o reembolsado nunca se vuelve a abrir. Si se paga un segundo pedido de Pagar.me del mismo pedido de WooCommerce, una nota te pide que reembolses el duplicado en el panel de Pagar.me.
Reembolsos
Abre el pedido, haz clic en Refund, introduce el importe y haz clic en Refund via Pagar.me (el botón muestra el título de tu método de pago). Se admiten reembolsos totales y parciales de pagos con tarjeta y PIX, hasta el importe que todavía se pueda reembolsar en Pagar.me. El reembolso se envía con la clave del modo en que se realizó el pago. Un reembolso solo se registra cuando Pagar.me lo confirma; en caso contrario, WooCommerce muestra el error, por ejemplo Pagar.me refused the refund: ... o Pagar.me did not confirm the refund, y no se registra ningún reembolso. Un reembolso correcto se añade a las notas del pedido con el ID del cargo.
Los pagos con boleto solo pueden reembolsarse a la cuenta bancaria del cliente. Reembólsalos en el panel de Pagar.me y luego registra el reembolso manualmente en WooCommerce, sin usar Refund via Pagar.me.
Un reembolso total o una cancelación realizados en el panel de Pagar.me llegan mediante webhook y cambian el pedido a Reembolsado. Un contracargo añade una nota y pone en espera un pedido Procesando o Completado.
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 > Pagar.me. 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. Libera la plaza en tu cuenta de vibefox.net.
Sin una clave activa, Pagar.me no se muestra a los clientes en la finalización de compra. Si aun así se inicia un pago, el cliente ve This payment method is not available. Please choose another one. Los gestores de la tienda con sesión iniciada 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. 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 siguen funcionando.
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
Pagar.me no aparece en la finalización de compra: comprueba que la licencia está activa, que Enable / Disable está activado, que la clave secreta del modo actual está configurada (Test secret key en modo de prueba, Live secret key en modo real) y que la moneda de la tienda es BRL. La página de ajustes muestra un aviso en cada caso.
El pago se realizó, pero el pedido sigue en Pending payment o On hold: el webhook no funciona. En el panel de Pagar.me, comprueba que existe un webhook para la cuenta y el modo que usas, que su URL es exactamente la que muestran los ajustes y que están seleccionados los eventos indicados arriba. El pedido también se comprueba cuando el cliente vuelve a la tienda.
El webhook responde verification failed, retry later: la tienda no pudo leer el pedido de Pagar.me desde la API, por ejemplo porque falta la clave de ese modo o la API no respondió. Pagar.me vuelve a intentar el webhook.
El webhook responde busy, retry later: otra solicitud estaba actualizando el pedido en ese mismo momento. Pagar.me vuelve a intentar el webhook.
El webhook responde unknown order: el pedido de Pagar.me no lo creó esta tienda, por ejemplo un pedido de otra tienda de la misma cuenta. No se cambia nada.
El cliente ve This order is already being processed: un webhook o el regreso del cliente estaban actualizando el pedido en ese mismo momento. El cliente puede volver a intentarlo tras un momento.
El cliente ve Pagar.me payments are not available right now: la clave secreta es incorrecta o falta. Comprueba la clave del modo actual.
El cliente ve Pagar.me could not start the payment: Pagar.me rechazó los datos de facturación. El mensaje indica el problema; el motivo completo está en las notas del pedido.
El cliente ve Pagar.me only supports payments in Brazilian Real (BRL): el pedido está en otra moneda, por ejemplo por un plugin selector de moneda.
Order is On hold after payment: lee la nota del pedido. Un PIX o boleto espera el pago, el importe o la moneda pagados eran distintos, o el pago llegó después de cancelar el pedido.
El reembolso de un boleto falla: los pagos con boleto no se pueden reembolsar mediante la API. Reembólsalo en el panel de Pagar.me y registra el reembolso manualmente.
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 la dirección del sitio cambió, haz clic en Check now para activar la clave para 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 conserva todos los datos. Para eliminarlo, desactívalo y bórralo en la página Plugins. La clave de licencia y el estado de la licencia de este plugin se eliminan siempre. Los ajustes de la pasarela y los registros del plugin solo se eliminan si Delete data on uninstall estaba activado. De lo contrario, se conservan para una reinstalación posterior. Los pedidos existentes conservan sus notas de pago, los ID de transacción y los datos de Pagar.me.
Pagar.me es una marca comercial de su respectivo propietario. Este plugin no está afiliado a Pagar.me ni respaldado por Pagar.me.