VibeFox Przelewy24 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: el carrito 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 carrito se cobra en su propia moneda; el módulo 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 proceden de una cuenta sandbox independiente, en sandbox.przelewy24.pl/panel. No hay que configurar nada más en el panel de Przelewy24: el módulo envía su URL de notificación con cada pago. Tu tienda debe ser accesible desde internet, porque Przelewy24 le envía las notificaciones de pago.

Licencia de VibeFox: se compra en vibefox.net. Una licencia funciona en un solo 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 Przelewy24 Payment 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 en el bloque de licencia de la parte superior de la página Configure y haz clic en Activate (ver Clave de licencia).

4. Introduce las claves de sandbox (Merchant ID, clave API, clave CRC; el POS ID solo si es distinto del Merchant ID), activa Enable/Disable, haz clic en Save y realiza un pago de prueba en modo sandbox.

5. Introduce las claves de producción, desactiva Test Mode y haz clic en Save para aceptar pagos reales.

Al instalarse, el módulo crea el estado de pedido Przelewy24 payment on hold. PrestaShop ofrece un nuevo módulo de pago para todas las monedas, países y grupos de clientes. Puedes limitarlos en Payment > Preferences.

Configuración

Todos los ajustes están en la página del módulo: Modules > Module Manager > VibeFox Przelewy24 Payment > Configure. Cada sección tiene su propio botón Save, que guarda toda la página. Encima de los campos, la página muestra advertencias 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 Live). Si Przelewy24 no acepta la moneda predeterminada de tu tienda, la advertencia indica la moneda y las que sí admite. Después de guardar, las advertencias siguen de inmediato el nuevo modo y las nuevas claves. Los espacios y los saltos de línea copiados junto con las claves desde el panel de Przelewy24 se eliminan al guardar.

Przelewy24

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. También es el nombre del método de pago guardado en el pedido. Por defecto: Przelewy24. Obligatorio: si guardas con el título vacío, aparece Enter a title for the payment method.

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 a panel.przelewy24.pl y sandbox.przelewy24.pl/panel.

Test Mode: usa el sandbox de Przelewy24 (sandbox.przelewy24.pl) y las claves Sandbox. No se cobra dinero real. Desactívalo para aceptar pagos reales en secure.przelewy24.pl con las claves Live. Por defecto: activado. Mientras está activado, los clientes ven Sandbox mode - no real money is charged debajo del método de pago.

Claves Live

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 igual al Merchant ID.

Live API key (report key): la clave API del panel de Przelewy24. Se usa para la autenticación de la API.

Live CRC key: se usa para firmar las solicitudes a Przelewy24 y para comprobar la firma de las notificaciones de Przelewy24.

Claves 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 igual al 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 comprobar las notificaciones de sandbox.

Las claves API y CRC 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 cambiarlo.

Clear saved secrets: marca una clave y haz clic en Save para eliminarla. Un campo vacío conserva el valor guardado.

Las claves Live y las 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 aparece en la finalización de compra. Un pago iniciado en un modo siempre se verifica y se reembolsa con las claves de ese modo, incluso después de cambiar, así que conserva las claves del modo anterior mientras sus pagos estén abiertos o puedan reembolsarse.

Notificaciones de pago

Notification URL: la dirección que recibe las notificaciones de pago de Przelewy24. Con URL amigables tiene este aspecto: https://your-shop/module/wcp_przelewy24_payment/notify, posiblemente con un código de idioma como /en/. El módulo envía esta URL a Przelewy24 con cada pago y cada reembolso, así que no hay que configurar nada en el panel de Przelewy24. La URL debe ser accesible desde internet: no debe haber cortafuegos ni autenticación HTTP delante. Sigue funcionando mientras la tienda está en modo de mantenimiento y no la bloquea la restricción por país de tu tienda. Sin notificaciones, el pago se confirma igualmente cuando el cliente vuelve a la tienda (ver Finalización de compra); si el cliente no vuelve, no se crea ningún pedido.

Avanzado

Debug Log: escribe eventos técnicos (números de carrito, ID de transacción de P24, errores) en logs/wc_p24_debug.log.php, dentro de la carpeta del módulo. El archivo no se puede abrir desde la web. Los errores y las advertencias, como las notificaciones rechazadas o una verificación o un reembolso fallidos, siempre se registran; activa el interruptor para registrar también cada paso. Las claves, los cuerpos de las solicitudes y los datos personales nunca 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 sus ajustes y el registro. Los pedidos y sus datos de pago de Przelewy24 nunca se eliminan. Por defecto: desactivado.

Finalización de compra

En el paso de pago, el cliente elige el método de pago (por defecto Przelewy24, con el logotipo de P24) y confirma el pedido. El módulo registra una transacción de Przelewy24 por el total del carrito en la moneda del carrito, con el correo electrónico, el nombre y el país de facturación del cliente, y la descripción Cart # con el número de carrito y el nombre de tu tienda. 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 carrito del cliente si Przelewy24 lo admite; si no, en inglés. En este punto todavía no existe ningún pedido.

El pedido se marca como pagado solo cuando Przelewy24 lo confirma. Przelewy24 envía a tu tienda una notificación firmada. El módulo comprueba la firma con la clave CRC, el Merchant ID y el POS ID; que la sesión se registró para este carrito y en el mismo modo; y que el importe y la moneda coinciden con el intento de pago y con el total actual del carrito. Solo entonces verifica la transacción con Przelewy24 (Przelewy24 solo abona los pagos verificados) y crea el pedido en Payment accepted. Los webhooks sin firma válida se rechazan.

Después de pagar, el cliente vuelve a tu tienda. Si la notificación todavía no ha llegado, el módulo pide a Przelewy24 el estado de la transacción con una solicitud autenticada de servidor a servidor (como máximo una vez cada 10 segundos por carrito) y aplica las mismas comprobaciones. La página de retorno por sí sola nunca marca un pedido como pagado. Cuando el pago se confirma, el cliente ve la página estándar de confirmación del pedido. Mientras no esté confirmado, una página Payment confirmation 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 Check again y un botón Pay again que abre la finalización de compra. El carrito se conserva, y un pago hecho más tarde en una página antigua de Przelewy24 del mismo carrito sigue siendo aceptado. Si el pedido está en espera, la página de confirmación muestra Your payment is being verified. We will send you an e-mail as soon as it is confirmed.

Si el pago no puede iniciarse, el cliente permanece en la finalización de compra con 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 carrito, o The order total must be greater than zero. Un carrito que ya tiene un pedido no se vuelve a enviar a Przelewy24; el cliente pasa a la confirmación del pedido.

El módulo no tiene tarjetas guardadas ni pagos con un clic, suscripciones ni pagos recurrentes, no permite elegir el método de pago de P24 (por ejemplo, un campo para el código BLIK) en la finalización de compra, no tiene widgets de pagos a plazos y no envía el contenido del carrito a Przelewy24.

Pedidos y reembolsos

Estados del pedido

No order yet: el cliente fue enviado a Przelewy24 y no ha pagado, o el pago todavía no está confirmado. Solo existe el carrito.

Payment accepted: el pago fue verificado. Se registra con el ID de pedido de P24 como ID de transacción, y una nota muestra el ID de pedido de P24, el importe y el modo. Cada pago se aplica una sola vez.

Przelewy24 payment on hold: el importe o la moneda que informa Przelewy24 difiere del carrito (por ejemplo, el carrito se cambió después de iniciar el pago); el pago no se confirmó y la nota lo indica. O bien el pago llegó y fue verificado para un pedido que había sido cancelado; el pedido no se reabre en silencio, la nota pide que lo envíes o que reembolses el pago. Comprueba el pago en el panel de Przelewy24. Si después llega un pago correcto de otro intento para un pedido en espera tras una discrepancia, el pedido pasa a Payment accepted.

Refunded: el pago fue reembolsado por completo a través del módulo.

Si llega un segundo pago para un carrito cuyo pedido ya está pagado o reembolsado (un enlace de pago antiguo, dos pestañas del navegador), no se confirma, así que Przelewy24 no lo abona. Una nota en el pedido pide que lo compruebes en el panel de Przelewy24 y, si es necesario, que lo devuelvas al comprador.

Bloque de pago de Przelewy24

La página del pedido muestra un bloque Przelewy24 payment con el ID de pedido de P24, la sesión, el entorno (una insignia Sandbox para los pagos de sandbox), el estado del pago y cómo se verificó (notificación o retorno), los importes pagados y reembolsados, el formulario de reembolso, el historial de reembolsos y las Payment notes del pedido.

Reembolsos

En el bloque Przelewy24 payment, introduce el importe (se rellena el importe que aún no se ha reembolsado), opcionalmente un motivo, y haz clic en Refund via Przelewy24. Confirma la pregunta Refund this amount through Przelewy24? This cannot be undone. Se admiten reembolsos totales y parciales, hasta el importe que aún no se ha reembolsado. Necesitas el permiso para editar pedidos; no hace falta acceso a las páginas de Módulos. 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. Los reembolsos están disponibles cuando Przelewy24 ha verificado el pago.

Przelewy24 procesa los reembolsos de forma asíncrona. El bloque muestra Refund of … requested at Przelewy24. The result will be added as an order note., el historial de reembolsos muestra el estado requested y se añade una nota. El resultado llega más tarde a la URL de notificación: el estado pasa a completed con la nota Przelewy24: refund of … completed., o a rejected con una nota que indica que el dinero no se devolvió al comprador. Un reembolso total pone el pedido en Refunded en el momento de solicitarlo; un reembolso parcial no cambia el estado. Si un reembolso es rechazado, compruébalo en el panel de Przelewy24; el estado del pedido no vuelve a cambiarse automáticamente.

Si Przelewy24 no acepta la solicitud de reembolso, el bloque muestra Przelewy24 refund failed: con el motivo, y no se registra ningún reembolso. El módulo no crea notas de crédito. Los botones de reembolso estándar de PrestaShop de la página del pedido no devuelven dinero a través de Przelewy24, y los reembolsos hechos directamente en el panel de Przelewy24 no se añaden al pedido.

Clave de licencia

El módulo funciona con una clave de licencia de VibeFox de vibefox.net. El bloque de licencia License — VibeFox Przelewy24 Payment es el primer bloque de Modules > Module Manager > VibeFox Przelewy24 Payment > Configure, por 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 están la línea Product: presta-payment-przelewy24 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 solo 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, 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. La tienda de PrestaShop 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 la finalización 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 verificando y confirmando, y los reembolsos funcionan.

Cuando una licencia caduca, el módulo sigue funcionando, pero las actualizaciones y el soporte requieren 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 después de introducir la clave, y después una vez a la 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

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 Sandbox mientras Test Mode esté activado, las claves Live en caso contrario; el Merchant ID y el POS ID solo con dígitos) y que la moneda del carrito sea PLN, EUR, GBP o CZK. Las advertencias en la parte superior de los ajustes indican el problema. 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. Los desarrolladores pueden cambiar la lista de monedas con el hook actionWcpPrzelewy24SupportedCurrencies (solo monedas con dos decimales habilitadas en tu cuenta de Przelewy24).

El pago se realizó, pero no se creó ningún pedido: la notificación de Przelewy24 no llegó a tu tienda y el cliente no volvió a la tienda. Comprueba que la Notification URL sea accesible desde internet (sin cortafuegos ni autenticación HTTP delante) y que el Merchant ID, el POS ID y la clave CRC del modo del pago sean correctos. Las notificaciones rechazadas se escriben en el registro incluso con Debug Log desactivado; mira el campo Log en la página del módulo.

Cómo responde la tienda a las notificaciones: una notificación procesada, repetida o desconocida recibe una respuesta HTTP 200. En otro caso, Przelewy24 la reenvía más tarde: 400 (datos ausentes o mal formados), 401 Invalid signature (clave CRC incorrecta, otro Merchant ID o POS ID), 401 Invalid signature for this payment (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, si existe), 500 Order could not be created (por ejemplo, el módulo está desactivado; la siguiente notificación crea el pedido sin una nueva verificación) y 503 Busy, retry later (otra solicitud estaba confirmando el carrito en ese mismo momento).

El cliente ve el mensaje 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, las claves Live solo en modo live). El error de Przelewy24 está en el registro.

El pedido está en Przelewy24 payment on hold tras el pago: lee las notas del bloque Przelewy24 payment. El importe o la moneda eran distintos del carrito, o el pago llegó para un pedido que había sido cancelado. Comprueba 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 Live) significa que se eliminaron las claves del modo del pago; vuelve a introducirlas. Invalid refund amount significa que el importe está vacío, no es un número o supera el importe que aún no se ha reembolsado.

Desinstalación

Ve a Modules > Module Manager, abre el menú junto a VibeFox Przelewy24 Payment y elige Uninstall. La clave de licencia y el estado de licencia de este módulo siempre se eliminan. Si Delete data on uninstall está activado, se eliminan los ajustes del módulo y el registro. Si está desactivado, todos los ajustes se conservan para una reinstalación posterior. Los datos de pago de Przelewy24 de los pedidos (sesiones, ID de pedidos de P24, reembolsos) y el estado de pedido Przelewy24 payment on hold siempre se conservan, así que los pedidos pagados antes pueden reembolsarse después de una reinstalación. Los pedidos existentes conservan sus notas de pago y sus ID de transacción.

Przelewy24 es una marca comercial de su respectivo titular. Este módulo no está afiliado a Przelewy24 ni cuenta con su respaldo.