VibeFox Pagar.me for PrestaShop — Ayuda
Requisitos
PrestaShop: 8.0 a 9.x.
PHP: 8.0 o posterior. El módulo se niega a instalarse en versiones anteriores de PHP.
Moneda: real brasileño (BRL). El método de pago se oculta en los carritos con cualquier otra moneda.
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 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 más tarde VibeFox Pagar.me Gateway 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 Configure, y haz clic en Activate (véase Clave de licencia).
4. Introduce la clave secreta de prueba y, cuando pases a producción, la clave secreta de producción.
5. Crea el webhook en el panel de Pagar.me con la URL que aparece en la configuración (véase Configuración).
6. Activa Enable / Disable y haz clic en Save. Haz pagos de prueba con Test mode activado y después desactívalo para aceptar pagos reales.
Al instalarse, el módulo crea dos estados de pedido: Awaiting Pagar.me payment y Pagar.me 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.
Configuración
Todos los ajustes están en la página del módulo: Modules > Module Manager > VibeFox Pagar.me 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: 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 el proceso 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 predeterminada de la tienda no es BRL.
Pagar.me
Enable / Disable: Enable Pagar.me payments activa o desactiva el método de pago. Predeterminado: desactivado.
Title: el nombre del método de pago que ve el cliente en el proceso de compra. También es el nombre del método de pago guardado en el pedido. Predeterminado: Pagar.me. Obligatorio.
Description: el texto que se muestra debajo del método de pago en el proceso de compra. Predeterminado: Pay securely via Pagar.me (credit card, PIX or boleto). You will be redirected to complete your payment.
Claves API
Copia las claves secretas desde el panel de Pagar.me: Development > Keys. Pagar.me usa una única dirección de API para pagos de prueba y de producción; la clave decide si un pago es de prueba o real.
Test mode: usa la clave secreta de prueba, sin cargos reales. Mientras esté activado, los clientes ven TEST MODE — Use test credentials. No real charges. debajo del método de pago. Las consultas de estado y los reembolsos de un pedido siempre usan la clave del modo en que se creó su pago. Predeterminado: 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. Manténla en secreto.
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 cambiarla.
Clear saved secret keys: marca una clave y haz clic en Save para eliminarla. Un campo vacío conserva el valor guardado.
Página de pago
Payment methods: los métodos que se ofrecen en la página de pago de Pagar.me. Elige solo métodos habilitados en tu cuenta de Pagar.me. Si no se marca ninguno, se usan los métodos predeterminados. Predeterminado: Credit card, PIX and Boleto.
Boleto due in (days): el número de días hasta el vencimiento del boleto, de 1 a 30. El pedido permanece en Awaiting Pagar.me payment hasta que Pagar.me confirme el pago. Predeterminado: 3. Otro valor se rechaza al guardar con Boleto due in (days): enter a number from 1 to 30.
Notificaciones de pago (webhook)
En el panel de Pagar.me abre Settings > Webhooks y crea un webhook con la URL que aparece en Webhook URL en esta sección. Con URLs amigables tiene este aspecto: https://your-shop/module/wcp_pagarme_gateway/webhook, posiblemente con un código de idioma como /en/. Cópiala exactamente como la muestra la configuración.
Selecciona estos eventos (también aparecen listados en esta sección):
El webhook no necesita contraseña ni firma. Su contenido nunca se considera de confianza: 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 regresa a la tienda.
Avanzado
Debug log: registra las peticiones a la API y las notificaciones en logs/wc_pgm_debug.log.php dentro de la carpeta del módulo. El archivo no se puede abrir desde la web. Los errores y advertencias siempre se registran. Las claves y los datos de los clientes no 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: si está activado, al desinstalar el módulo se eliminan los ajustes de la pasarela y el registro. Los pedidos, sus datos de pago de Pagar.me (necesarios para los reembolsos) y los estados de pedido se conservan. Predeterminado: desactivado.
Finalización de compra
En el paso de pago, el cliente elige el método de pago (por defecto Pagar.me) y confirma. Se requiere un correo electrónico válido. El módulo crea un pedido de Pagar.me por el total del carrito en BRL, con las líneas del carrito, el envío y el envoltorio de regalo (o una sola línea Order # con el número del carrito cuando el carrito tiene descuentos), y envía al cliente a la página de pago de Pagar.me. En este punto todavía no existe ningún pedido en tu tienda.
El nombre y el correo electrónico del cliente se envían a Pagar.me. El CPF o CNPJ se toma del campo Identification number de la dirección, o de VAT number; también se envía un número de móvil brasileño. La dirección de facturación solo se envía para una dirección brasileña con CEP de 8 dígitos y estado. PrestaShop no incluye estados brasileños de forma predeterminada, así que normalmente el cliente introduce la dirección en la página de Pagar.me. Si no tiene CPF o CNPJ, también lo introduce allí.
Después de pagar, el cliente vuelve a tu tienda. El pedido se marca como pagado solo cuando Pagar.me lo confirma: la tienda lee el pedido de Pagar.me desde la API, y el importe pagado y la moneda deben coincidir con el carrito. Un pago con tarjeta, PIX o boleto realizado crea el pedido en Payment accepted, y el cliente ve la página estándar de confirmación del pedido con Your payment with Pagar.me has been received. Un PIX o boleto emitido que aún no está pagado crea el pedido en Awaiting Pagar.me payment, y la página muestra Your Pagar.me payment is awaiting confirmation (PIX / boleto). The order will be confirmed as soon as Pagar.me reports the payment. Cada regreso posterior vuelve a leer el pedido de Pagar.me, así que un PIX o boleto pagado mientras tanto se aplica aunque no haya llegado el webhook. Si el pago de ese pedido falló o caducó, la página muestra Your Pagar.me payment was not completed. Please contact us about this order.
Si el cliente regresa sin pagar, vuelve al proceso de compra con The Pagar.me payment was not completed. You can pay the order below. Si el pago fue rechazado o cancelado, el mensaje es The Pagar.me payment was declined or canceled. You can try again below. El carrito se conserva. Si el pedido ya existe y su pago falló o caducó, el mensaje es The Pagar.me payment of your order was declined, canceled or has expired. Please place a new order or contact us. Si no se pudo contactar con Pagar.me, aparece una página Payment confirmation que pide al cliente que no pague de nuevo y ofrece Check again y Back to checkout.
Cuando el cliente vuelve a pagar, se reutiliza la página de pago abierta de Pagar.me 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 crea sin un nuevo pago. Si la página anterior no se puede cerrar, queda asociada al carrito, así que un pago hecho en ella se registra igualmente.
Si Pagar.me no puede iniciar el pago, el cliente permanece en el proceso de compra con un mensaje breve, por ejemplo Could not connect to Pagar.me. Please try again in a moment., o con el mensaje de Pagar.me sobre datos de facturación no válidos. El motivo técnico se escribe en el registro.
El webhook funciona mientras la tienda está en modo de mantenimiento y no se ve afectado por la restricción de países de tu tienda.
El módulo no incluye formulario de tarjeta en tu proceso 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 de pedido
No order yet: el cliente fue enviado a Pagar.me y aún no ha pagado ni emitido un PIX o boleto. Solo existe el carrito.
Payment accepted: el pago fue confirmado. El pago se registra con el ID del pedido de Pagar.me (or_...) como ID de transacción, y una nota muestra el pedido de Pagar.me y el método de pago.
Awaiting Pagar.me payment: se emitió un PIX o boleto (o un pago con tarjeta está en análisis) y espera el pago. El pedido pasa a Payment accepted cuando Pagar.me confirma el pago.
Pagar.me payment on hold: el boleto se pagó solo parcialmente; o el importe pagado o la moneda no coinciden con el pedido (por ejemplo, el carrito se cambió después de iniciar el pago); o el pago llegó después de que se cancelara el pedido; o se abrió un contracargo sobre un pedido pagado. La nota lo explica. Revisa el pedido y tramítalo o reembolsa el pago.
Payment error: el pago de un pedido en espera o retenido falló, o su pedido de Pagar.me fue cancelado o caducó (por ejemplo, un boleto no pagado). Si Pagar.me informa de un pago más tarde, el pedido igualmente pasa a Payment accepted.
Refunded: el pago fue reembolsado por completo a través del módulo, o reembolsado o cancelado en Pagar.me.
Cada estado de Pagar.me se aplica una sola vez, así que los webhooks o regresos repetidos no añaden notas ni pagos. Si se paga un segundo pedido de Pagar.me del mismo carrito, una nota te pide reembolsar el duplicado en el panel de Pagar.me.
Bloque de pago de Pagar.me
La página del pedido muestra un bloque Pagar.me payment con el ID del pedido de Pagar.me y los IDs de los cargos, el método de pago, el estado, el importe pagado y reembolsado, una insignia Test mode para los pagos de prueba, el historial de reembolsos y las Pagar.me notes del pedido.
Reembolsos
En el bloque Pagar.me payment introduce el importe (se rellena el importe que aún no se ha reembolsado), opcionalmente un motivo, y haz clic en Refund via Pagar.me. Confirma la pregunta Refund this amount through Pagar.me? This cannot be undone. Se admiten reembolsos totales y parciales de pagos con tarjeta y PIX. Necesitas el permiso para editar pedidos. Puedes reembolsar hasta el importe que Pagar.me realmente cobró, así que tras una diferencia de importe el límite es lo que pagó el cliente, no el total del pedido. El reembolso se envía con la clave del modo en que se hizo el pago, por lo que esa clave secreta debe estar configurada. Un reembolso solo se registra cuando Pagar.me lo confirma; en caso contrario, el bloque 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 al historial de reembolsos y a las notas con el ID del cargo. Un reembolso total pone el pedido en Refunded. Un reembolso parcial no cambia el estado. Los reembolsos están disponibles cuando Pagar.me ha informado del pago.
Los pagos con boleto solo pueden reembolsarse a la cuenta bancaria del cliente. Reembólsalos en el panel de Pagar.me y después registra el reembolso manualmente en PrestaShop.
El módulo no crea abonos (credit slips). Los botones de reembolso estándar de PrestaShop en la página del pedido no devuelven dinero a través de Pagar.me.
Un reembolso total o una cancelación realizados en el panel de Pagar.me llegan por webhook, ponen el pedido en Refunded y añaden una nota. Un contracargo añade una nota y pone un pedido pagado en Pagar.me payment on hold.
Clave de licencia
El módulo funciona con una clave de licencia de VibeFox de vibefox.net. El bloque de licencia License — VibeFox Pagar.me Gateway es el primer bloque de Modules > Module Manager > VibeFox Pagar.me 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-pagarme 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, Pagar.me no se muestra a los clientes en el proceso de compra. 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 proceso de compra. 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
Pagar.me no aparece en el proceso 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 de producción) y que la moneda del carrito es BRL. La página de configuración muestra un aviso cuando falta la clave. En Payment > Preferences comprueba que el módulo está permitido para la moneda del carrito, el país del cliente y el grupo del cliente.
El pago se realizó, pero no se creó el pedido o este sigue en Awaiting Pagar.me payment: el webhook no funciona. En el panel de Pagar.me comprueba que el webhook existe para la cuenta y el modo que usas, que su URL es exactamente la que aparece en Webhook URL y que los eventos indicados arriba están seleccionados. El pedido también se comprueba cada vez que el cliente regresa 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 reintenta el webhook.
El webhook responde busy: el carrito estaba siendo actualizado por otra petición en ese mismo momento, o el pedido no pudo crearse (por ejemplo, el módulo está desactivado). Pagar.me reintenta el webhook. Activa Debug log para ver el motivo.
El webhook responde unknown order: el pedido de Pagar.me no fue creado por esta tienda, por ejemplo un pedido de otra tienda de la misma cuenta. No se cambia nada.
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, por ejemplo el CPF del campo Identification number de la dirección. El mensaje indica el problema; el motivo completo está en el registro.
El cliente ve Pagar.me only supports payments in Brazilian Real (BRL): el carrito está en otra moneda.
El cliente ve This order already has a Pagar.me payment that the store has to review: un pago anterior del carrito necesita tu revisión. Comprueba el panel de Pagar.me y el registro.
El pedido está en Pagar.me payment on hold tras el pago: lee las notas del bloque Pagar.me payment (véase Estados de pedido) y después tramita el pedido o reembolsa el pago.
El reembolso falla con un boleto: los pagos con boleto no se pueden reembolsar a través de la API. Reembólsalo en el panel de Pagar.me y registra el reembolso manualmente.
El reembolso falla con un mensaje sobre el modo: el pago se hizo en modo de prueba o de producción, y la clave secreta de ese modo no está configurada. Introdúcela e inténtalo de nuevo.
Los desarrolladores pueden modificar los datos del pedido de Pagar.me antes de enviarlo con el hook actionWcpPagarmeOrderData.
Desinstalación
Ve a Modules > Module Manager, abre el menú junto a VibeFox Pagar.me 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 los ajustes de la pasarela y el registro. Si está desactivado, todos los ajustes se conservan para una reinstalación posterior. Los datos de pago de Pagar.me de los pedidos y los estados de pedido Awaiting Pagar.me payment y Pagar.me payment on hold siempre se conservan, así que los pedidos pagados antes se pueden reembolsar tras reinstalar. Los pedidos existentes conservan sus notas de pago y sus IDs de transacción.
Pagar.me es una marca comercial de su respectivo titular. Este módulo no está afiliado a Pagar.me ni cuenta con su respaldo.