VibeFox Przelewy24 for WooCommerce — Ayuda
Requisitos
WordPress: 5.8 o posterior.
WooCommerce: 7.0 o posterior, instalado y activo. El plugin no se activa sin él.
PHP: 8.0 o posterior.
Moneda: el pedido debe estar en PLN, EUR, GBP o CZK. En otras monedas el método de pago se oculta en la finalización de compra. El pedido se cobra en su propia moneda; el plugin no convierte monedas.
Cuenta de Przelewy24: necesitas una cuenta de comerciante de Przelewy24 y sus datos de API: el Merchant ID, la clave API (llamada report key en el panel de Przelewy24), la clave CRC y, si tu tienda tiene su propio ID, el POS ID (Shop ID). Los encontrarás en el panel de comerciante de Przelewy24, en panel.przelewy24.pl, en My data > API data and configuration. Las claves de sandbox se obtienen de una cuenta sandbox independiente, en sandbox.przelewy24.pl/panel. No hay que configurar nada más en el panel de Przelewy24: el plugin envía su URL de notificación con cada pago. Tu sitio debe ser accesible desde internet, porque Przelewy24 envía a él las notificaciones de pago.
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 y haz clic en Install Now. También puedes subir la carpeta wcp_przelewy24_payment a /wp-content/plugins/ por FTP.
2. Haz clic en Activate.
3. Abre los ajustes: WooCommerce > Settings > Payments > Przelewy24 > Manage, o haz clic en Settings debajo del nombre del plugin en la página de 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 las claves de sandbox (Merchant ID, API key, CRC key; el POS ID solo si es distinto del Merchant ID), activa Enable/Disable, guarda y haz un pago de prueba en modo sandbox.
6. Introduce las claves de producción, desmarca Test Mode y guarda para aceptar pagos reales.
Configuración
Todos los ajustes están en una sola página: WooCommerce > Settings > Payments > Przelewy24. Sobre los campos, la página muestra avisos cuando falta algo. Mientras el sandbox está activado: Sandbox (test) mode is on: payments go to the Przelewy24 sandbox and no real money is charged. Do not ship orders paid in test mode. Cuando las claves del modo actual están incompletas: Enter the Sandbox Merchant ID, API key and CRC key — until then Przelewy24 is not shown at checkout. (o lo mismo para las claves de producción). Si Przelewy24 no acepta la moneda de la tienda, el aviso indica esa moneda y las admitidas. Después de guardar, los avisos siguen de inmediato el nuevo modo y las nuevas claves. Los espacios y saltos de línea copiados junto con las claves desde el panel de Przelewy24 se eliminan al guardar.
Finalización de compra
Enable/Disable: Enable Przelewy24 Payment 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: Przelewy24.
Description: el texto que se muestra debajo del método de pago en la finalización de compra. Por defecto: Pay with BLIK, online bank transfer or card via Przelewy24.
Credenciales de API
La sección explica dónde encontrar las claves (My data > API data and configuration en el panel de comerciante de Przelewy24) y enlaza con panel.przelewy24.pl y sandbox.przelewy24.pl/panel.
Test Mode: Enable sandbox (test) mode. Cuando está activado, los nuevos pagos van al sandbox de Przelewy24 (sandbox.przelewy24.pl) con las claves de sandbox, y no se cobra dinero real. Desmárcalo para aceptar pagos reales en secure.przelewy24.pl con las claves de producción. Por defecto: activado.
Claves de producción
Live Merchant ID: tu ID de comerciante de Przelewy24, solo números.
Live POS ID (optional): el Shop ID (posId). Déjalo vacío si es el mismo que el Merchant ID.
Live API key (report key): la clave API del panel de Przelewy24. Se usa para la autenticación de la API, junto con el POS ID.
Live CRC key: se usa para firmar las solicitudes a Przelewy24 y para verificar la firma de las notificaciones de Przelewy24.
Claves de sandbox
Sandbox Merchant ID: el Merchant ID de tu cuenta sandbox de Przelewy24.
Sandbox POS ID (optional): el Shop ID (posId) de la cuenta sandbox. Déjalo vacío si es el mismo que el Merchant ID.
Sandbox API key (report key): la clave API de la cuenta sandbox.
Sandbox CRC key: la clave CRC de la cuenta sandbox, que se usa para firmar las solicitudes y verificar las notificaciones del sandbox.
Las claves de producción y de sandbox son distintas. El Merchant ID y el POS ID deben contener solo dígitos; hasta que se introduzcan el Merchant ID, la clave API y la clave CRC del modo actual, el método de pago no se muestra en la finalización de compra. Un pago iniciado en un modo siempre se verifica y reembolsa con las claves de ese modo, incluso después de cambiar de modo, así que conserva las claves del modo anterior mientras sus pagos sigan abiertos o puedan reembolsarse.
Notificaciones de pago
Esta sección muestra la URL de notificación de tu tienda. Tiene este aspecto: https://your-site/wc-api/wc_p24_payment/. El plugin envía esta URL a Przelewy24 con cada pago, así que no hay que configurar nada en el panel de Przelewy24. La misma URL recibe los resultados de los reembolsos. La URL debe ser accesible desde internet: sin cortafuegos, modo de mantenimiento ni autenticación HTTP delante. Sin notificaciones, el pago se confirma igualmente cuando el cliente vuelve a la página de pedido recibido (ver Finalización de compra); si el cliente no vuelve, el pedido se queda en «Pago pendiente».
Avanzado
Debug Log: Enable logging escribe eventos técnicos (números de pedido, ID de transacción de P24, errores) en WooCommerce > Status > Logs, origen wcp_przelewy24_payment. Los errores y las advertencias siempre se registran. Las claves, los cuerpos de las solicitudes y los datos personales nunca se registran. Por defecto: desactivado.
Delete data on uninstall: Delete the plugin settings and logs when the plugin is deleted. Los pedidos y sus datos de pago nunca se eliminan. Desactivar el plugin lo conserva todo. Por defecto: desactivado.
Finalización de compra
El cliente elige el método de pago (por defecto Przelewy24, con el logotipo de P24 en el bloque de Finalizar compra) y realiza el pedido. En modo sandbox, el bloque de Finalizar compra muestra Sandbox mode — no real money is charged. El plugin registra una transacción de Przelewy24 por el total del pedido en la moneda del pedido, con el correo electrónico, el nombre y el país de facturación del cliente, y añade una nota al pedido con el ID de sesión y el modo (sandbox o producción). Cada intento de pago recibe su propio ID de sesión. El cliente es enviado a la página de pago de Przelewy24 y paga con BLIK, transferencia bancaria en línea, tarjeta u otro método habilitado para tu cuenta de Przelewy24. La página de pago se muestra en el idioma del sitio si Przelewy24 lo admite; si no, en inglés.
El pedido solo se marca como pagado cuando Przelewy24 lo confirma. Przelewy24 envía una notificación firmada a tu tienda. El plugin comprueba la firma con la clave CRC, el Merchant ID y el POS ID; que la sesión se registró para este pedido y en el mismo modo; y que el importe y la moneda coinciden con el intento de pago y con el total actual del pedido. Solo entonces verifica la transacción con Przelewy24 (Przelewy24 solo abona los pagos verificados) y marca el pedido como pagado. Los webhooks sin una firma válida se rechazan.
Después de pagar, el cliente vuelve a la página de pedido recibido. Si la notificación todavía no ha llegado, el plugin pide a Przelewy24 el estado de la transacción mediante una solicitud autenticada de servidor a servidor (como máximo una vez cada 10 segundos por pedido) y aplica las mismas comprobaciones. La página de regreso, por sí sola, nunca marca un pedido como pagado. Mientras el pago no esté confirmado, la página muestra We have not received the payment confirmation from Przelewy24 yet. If you have paid, it will be confirmed in a few minutes. If the payment was interrupted, you can try again: con un botón Pay again que abre la página Pay for order. Si el pedido está en espera, la página muestra Your payment is being verified. We will send you an e-mail as soon as it is confirmed. Un pago realizado más tarde desde una página antigua de Przelewy24 del mismo pedido se sigue aceptando.
Si el pago no puede iniciarse, el cliente ve un mensaje breve: Payment error: Przelewy24 could not start the payment. Please try again or choose another payment method. (el motivo va al registro), Payment gateway is not configured properly. Please contact the administrator. (faltan las claves del modo actual), un mensaje que indica que Przelewy24 no puede aceptar pagos en la moneda del pedido, o The order total must be greater than zero. Un pedido que ya está pagado o en espera no se vuelve a enviar a Przelewy24 (This order does not need a payment any more.).
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 WooCommerce High-Performance Order Storage (HPOS).
El plugin no admite tarjetas guardadas ni pagos con un clic, suscripciones ni pagos recurrentes, la elección del método de pago de P24 (por ejemplo, un campo para el código BLIK) en la página de finalización de compra, widgets de pagos a plazos, y no envía el contenido del carrito a Przelewy24.
Pedidos y reembolsos
Estados del pedido
Pending payment: el cliente fue enviado a Przelewy24 y todavía no ha pagado, o el pago aún no está confirmado.
Processing or Completed: el pago fue verificado. WooCommerce establece «Procesando», o «Completado» en los pedidos que solo contienen productos virtuales descargables. La nota del pedido muestra el ID de pedido de P24, el importe y el modo. El ID de transacción del pedido es el ID de pedido de P24. Cada pago se aplica una sola vez.
On hold: el importe o la moneda informados por Przelewy24 no coinciden con el pedido (por ejemplo, el total se cambió después de iniciar el pago); el pago no se confirmó y la nota lo indica. O bien el pago llegó y se verificó para un pedido que había sido cancelado; el pedido no se reabre en silencio, y la nota te pide que lo envíes o reembolses el pago. Revisa el pago en el panel de Przelewy24.
Si llega un segundo pago para un pedido que ya está pagado o reembolsado (un enlace de pago antiguo, dos pestañas del navegador), no se confirma, por lo que Przelewy24 no lo abona. Una nota en el pedido te pide que lo revises en el panel de Przelewy24 y, si es necesario, que lo devuelvas al comprador.
Reembolsos
Abre el pedido, haz clic en Refund, introduce el importe y haz clic en Refund via Przelewy24. Se admiten reembolsos totales y parciales. El reembolso se envía en el modo en que se realizó el pago (sandbox o producción), así que deben estar configuradas las claves de ese modo. Przelewy24 procesa los reembolsos de forma asíncrona: primero, la nota del pedido indica que el reembolso fue solicitado; el resultado llega después a la URL de notificación y se añade como nota: Przelewy24: refund of … completed. o una nota que indica que el reembolso fue rechazado y el dinero no se devolvió. Si un reembolso se rechaza, revísalo en el panel de Przelewy24; el reembolso de WooCommerce ya registrado en el pedido no se elimina automáticamente.
Si Przelewy24 no acepta la solicitud de reembolso, WooCommerce muestra Przelewy24 refund failed: con el motivo, y no se registra ningún reembolso. Los reembolsos hechos directamente en el panel de Przelewy24 no se añaden al pedido.
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 > Przelewy24. 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. Eliminar la clave de un sitio no libera su plaza de dominio. Libera la plaza en tu cuenta de vibefox.net.
Sin una clave activa, Przelewy24 no se muestra a los clientes en la finalización de compra. Si de todos modos 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 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 requieren renovarla. El estado se vuelve a comprobar automáticamente en segundo plano.
Solución de problemas
Przelewy24 no aparece en la finalización de compra: comprueba que la licencia esté activa, que Enable/Disable esté activado, que el Merchant ID, la clave API y la clave CRC del modo actual estén introducidos (las claves de sandbox mientras Test Mode esté activado, las de producción en caso contrario; el Merchant ID y el POS ID solo con dígitos) y que la moneda del pedido sea PLN, EUR, GBP o CZK. Los avisos en la parte superior de los ajustes indican el problema. Los desarrolladores pueden cambiar la lista de monedas con el filtro wc_p24_supported_currencies (solo monedas con dos decimales habilitadas en tu cuenta de Przelewy24).
El pago se realizó, pero el pedido sigue en Pending payment: la notificación de Przelewy24 no llegó a tu tienda y el cliente no volvió a la página de pedido recibido. Comprueba que la URL que aparece en Payment notifications sea accesible desde internet (sin modo de mantenimiento, cortafuegos ni autenticación HTTP delante de /wc-api/wc_p24_payment/) y que el Merchant ID, el POS ID y la clave CRC del modo del pago sean correctos. Las notificaciones rechazadas se registran en WooCommerce > Status > Logs, origen wcp_przelewy24_payment, incluso con Debug Log desactivado.
Cómo responde la tienda a las notificaciones: una notificación procesada, repetida o desconocida recibe una respuesta HTTP 200. En caso contrario, Przelewy24 la vuelve a enviar más tarde: 400 (datos ausentes o mal formados), 401 Invalid signature (clave CRC incorrecta, otro Merchant ID o POS ID, o una notificación firmada con las claves del modo distinto al del pago), 405 (no es una solicitud POST), 500 Verification failed (la verificación con Przelewy24 falló; se añade una nota al pedido una sola vez) y 503 Busy, retry later (otra solicitud estaba actualizando el pedido en ese mismo momento).
El cliente ve Payment error: Przelewy24 could not start the payment: Przelewy24 rechazó la transacción, normalmente por claves incorrectas del modo actual (las claves de sandbox solo funcionan en modo sandbox, y las de producción solo en modo producción). El error de Przelewy24 aparece en el registro.
El pedido está On hold después del pago: lee la nota del pedido. El importe o la moneda no coincidían con el pedido, o el pago llegó para un pedido que había sido cancelado. Revisa el pago en el panel de Przelewy24 y, después, procesa el pedido o reembolsa el pago.
Un reembolso falla: This order has no verified Przelewy24 payment. Cannot process refund. significa que el pedido no se pagó mediante un pago de Przelewy24 verificado. The payment was made in the Przelewy24 sandbox, but the Sandbox keys are missing. (o lo mismo para producción) significa que se eliminaron las claves del modo del pago; vuelve a introducirlas.
El bloque de licencia muestra un error: sigue el mensaje que aparece en el 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, así como los marcadores temporales de la página de regreso, siempre se eliminan. Los ajustes del plugin y sus registros (archivos de registro, incluidos los rotados, y las entradas de la base de datos del origen wcp_przelewy24_payment) se eliminan solo si Delete data on uninstall estaba activado. En caso contrario, se conservan para una futura reinstalación. Los pedidos existentes conservan sus notas de pago, ID de transacción y datos de pago de Przelewy24.
Przelewy24 es una marca registrada de su respectivo titular. Este plugin no está afiliado a Przelewy24 ni cuenta con su respaldo.