VibeFox Paystack 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 una moneda que Paystack acepte: NGN, USD, GHS, ZAR, KES, XOF, EGP o RWF, según estén habilitadas en tu cuenta de Paystack. En otras monedas el método de pago se oculta. En XOF y RWF Paystack acepta solo importes enteros.

Cuenta de Paystack: necesitas las claves secretas de tu cuenta de Paystack: la clave secreta de prueba (sk_test_...) y/o la clave secreta real (sk_live_...). Las claves públicas (pk_...) no son necesarias, porque el pago se realiza en la página alojada de Paystack. En el panel de Paystack también configuras la URL del webhook de tu tienda (ver Configuración). Tu tienda debe ser accesible desde internet para recibir webhooks.

Clave de licencia de VibeFox: se compra en vibefox.net. Una clave 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 más tarde VibeFox Paystack Payment en la lista de módulos y haz clic en Configure.

3. Pega tu clave de licencia de VibeFox en License key del bloque de licencia de la parte superior de la página Configure y haz clic en Activate (ver Clave de licencia).

4. Pega tus claves secretas del panel de Paystack y configura la URL del webhook en el panel de Paystack (ver Configuración).

5. Activa Enable/Disable y haz clic en Save. Mantén Test Mode activado hasta que hayas hecho un pago de prueba y luego desactívalo para aceptar pagos reales.

Al instalarse, el módulo crea dos estados de pedido, Awaiting Paystack payment y Paystack 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 Paystack Payment > Configure. Cada sección con campos tiene su propio botón Save, que guarda toda la página. Encima de los campos, un cuadro de estado muestra el modo: Modo de prueba: no se cobra dinero real. o Modo real: se aceptan pagos reales. También avisa cuando la clave secreta del modo actual está vacía, cuando se ha introducido una clave pública (pk_...) en un campo de clave secreta, cuando el modo real tiene una clave de prueba (sk_test_...) o el modo de prueba tiene una clave real (sk_live_...), y cuando Paystack no acepta la moneda predeterminada de tu tienda. Mientras exista un problema con las claves, el método de pago se oculta en la finalización de compra.

Paystack

La primera sección se titula Paystack y lleva una insignia TEST o LIVE del modo actual.

Enable/Disable: Enable Paystack 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: Paystack. Obligatorio.

Description: el texto que se muestra debajo del método de pago en la finalización de compra. Por defecto: Pay securely using your debit card, credit card, or bank account via Paystack.

Claves API

Copia las claves secretas del panel de Paystack, página Settings > API Keys & Webhooks. La sección incluye un enlace a ella.

Test Mode: usa la clave secreta de prueba para los nuevos pagos, y no se cobra dinero real. Desactívalo para aceptar pagos reales con la clave secreta real. Los pagos hechos en el otro modo siguen usando la clave de su propio modo para la verificación y los reembolsos. Por defecto: activado. Mientras esté activado, los clientes ven MODO DE PRUEBA ACTIVADO. No se realizarán cargos reales. debajo del método de pago.

Test Secret Key: tu clave secreta de prueba de Paystack. Empieza por sk_test_.

Live Secret Key: tu clave secreta real de Paystack. Empieza por sk_live_.

Las claves guardadas nunca se vuelven a mostrar. El campo queda vacío y muestra Guardada: déjala vacía para conservarla. Escribe un valor nuevo solo si quieres cambiarla.

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

Webhook

El webhook avisa a tu tienda de que se ha realizado un pago, incluso cuando el cliente no vuelve a la tienda. En el panel de Paystack, página Settings > API Keys & Webhooks, configura la URL que aparece en Webhook URL de esta sección como Test Webhook URL y como Live Webhook URL. Con URLs amigables tiene este aspecto https://your-shop/module/wcp_paystack_payment/webhook, posiblemente con un código de idioma como /en/. Copia la URL exactamente como la muestran los ajustes.

Paystack firma cada webhook con tu clave secreta, así que no hay que configurar nada más. Los webhooks sin una firma válida se rechazan. El módulo usa el evento charge.success:

Los demás eventos reciben como respuesta OK y se ignoran. Sin el webhook, un pedido solo se confirma cuando el cliente vuelve a la tienda después de pagar. Los pagos por transferencia bancaria y USSD que se completan más tarde solo se confirman mediante el webhook.

Pedidos

Autocomplete Order: si está activado, los pedidos pagados reciben el estado Delivered en lugar de Payment accepted, con un solo cambio de estado. Por defecto: desactivado.

Avanzado

Debug log: registra los eventos y las llamadas a la API de Paystack en logs/paystack_p_debug.log.php, dentro de la carpeta del módulo. El archivo no se puede abrir desde la web. Los errores y las advertencias siempre se registran. Las claves y los datos de los clientes 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 datos de pago guardados en los pedidos siempre se conservan. Por defecto: desactivado.

Finalización de compra

En el paso de pago el cliente elige el método de pago (por defecto Paystack) y confirma el pedido. El módulo inicia una transacción de Paystack por el total del carrito en la moneda del carrito, con el correo electrónico del cliente, y envía al cliente a la página de pago alojada de Paystack. Allí el cliente paga con uno de los canales habilitados en tu cuenta de Paystack. El pago muestra el número del carrito y el nombre del cliente. En este punto todavía no existe ningún pedido.

Después de pagar, el cliente vuelve a tu tienda. El pedido solo se marca como pagado cuando Paystack lo confirma: cuando el cliente vuelve y cuando llega el webhook, el módulo lee la transacción desde la API de Paystack y comprueba la referencia, el estado, el importe y la moneda. Entonces se crea el pedido y el cliente ve la página estándar de confirmación del pedido.

Si el pago todavía se está procesando, por ejemplo una transferencia bancaria, el pedido se crea en Awaiting Paystack payment cuando el cliente vuelve, y la página de confirmación muestra Tu pago está siendo confirmado por Paystack. Recibirás un correo electrónico en cuanto se confirme. El webhook completa el pedido más tarde. Si no se puede contactar con Paystack cuando el cliente vuelve, una página Payment confirmation le pide que no pague de nuevo y le ofrece Check again y Back to checkout; el webhook crea el pedido en cuanto llega. Para un pedido en espera, la página de confirmación muestra Hemos recibido tu pago y tu pedido se está revisando. Nos pondremos en contacto contigo si hace falta algo.

Si el cliente cancela en la página de Paystack o la abandona sin pagar, no se crea ningún pedido y el carrito se conserva. El cliente vuelve a la finalización de compra con un mensaje, por ejemplo El pago se ha cancelado. Puedes intentarlo de nuevo o elegir otro método de pago., El pago no se ha completado. Puedes intentarlo de nuevo o elegir otro método de pago. o Tu pago ha sido rechazado. Puedes intentarlo de nuevo o elegir otro método de pago. Cada nuevo intento inicia una nueva transacción de Paystack. Una página de pago anterior del carrito sigue siendo válida: si se paga más tarde, el pago se sigue aceptando.

La página de confirmación del pedido solo se abre en el propio navegador del cliente. Si el enlace de retorno se abre en otro lugar, el pago se sigue comprobando, pero el pedido no se muestra: el visitante ve un mensaje neutro en la finalización de compra.

Si Paystack no puede iniciar el pago, el cliente se queda en la finalización de compra con un mensaje breve, por ejemplo Paystack no pudo iniciar el pago: seguido del motivo indicado por Paystack, o Paystack no está disponible temporalmente. Inténtalo de nuevo en un momento o elige otro método de pago. El total del carrito debe ser mayor que cero y el cliente necesita una dirección de correo electrónico válida.

El webhook funciona mientras la tienda está en modo de mantenimiento y no se ve bloqueado por la restricción de países de tu tienda.

El módulo no tiene formulario de pago integrado ni emergente, ni tarjetas guardadas, ni suscripciones, ni pagos divididos o subcuentas, ni elección de canales de pago en PrestaShop.

Pedidos y reembolsos

Estados del pedido

Aún sin pedido: el cliente fue enviado a Paystack y no ha pagado, ha salido de la página de Paystack o Paystack todavía no ha confirmado el pago. Solo existe el carrito.

Awaiting Paystack payment: el cliente volvió mientras Paystack seguía procesando el pago, por ejemplo una transferencia bancaria o USSD. El pedido pasa al estado de pagado cuando Paystack confirma el pago. Si ese pago nunca se completa, el pedido permanece en este estado hasta que lo cambies.

Payment accepted or Delivered: el pago fue confirmado. El estado es Entregado cuando Autocomplete Order está activado. El pago se registra con la referencia de Paystack (pscart_...) como ID de transacción. Una nota muestra el importe, la referencia, el número de transacción, el modo (prueba o real), el canal de pago, el tipo de tarjeta y los últimos dígitos en los pagos con tarjeta, y las comisiones de Paystack que haya pagado el cliente.

Paystack payment on hold: el importe o la moneda pagados no coinciden con el pedido (nota Discrepancia de importe o moneda de Paystack), por ejemplo porque el carrito se modificó después de iniciar el pago, o porque el pago llegó después de que el pedido se cancelara. La nota explica qué revisar. Procesa el pedido o reembolsa el pago.

Error de pago: Paystack informa de que el último intento de pago de un pedido en Awaiting Paystack payment ha fallado o se ha revertido. El fallo de un intento anterior no cambia el pedido.

Si llega un segundo pago de un carrito cuyo pedido ya está pagado, el pedido no cambia. Una nota te pide que reembolses el pago duplicado en el panel de Paystack. Un pago que llega para un pedido en otro estado, por ejemplo Enviado, solo se anota en el pedido.

Bloque Paystack payment

La página del pedido muestra un bloque Paystack payment con la referencia, el ID de transacción, el modo con una insignia Test mode para los pagos de prueba, el estado del pago, el canal y la tarjeta, la fecha de pago, los importes cobrados y reembolsados, el historial de reembolsos y las Payment notes del pedido.

Reembolsos

En el bloque Paystack payment introduce el importe (se rellena el importe que aún no se ha reembolsado), opcionalmente un motivo, y haz clic en Refund via Paystack. Confirma la pregunta ¿Reembolsar este importe a través de Paystack? Esta acción no se puede deshacer. Se admiten reembolsos totales y parciales. Necesitas el permiso para editar pedidos; el acceso a las páginas de módulos no es necesario. El reembolso se envía a la transacción que pagó el pedido, con la clave secreta del modo (prueba o real) en que se hizo, así que esa clave debe estar configurada. Los reembolsos se hacen por el importe y en la moneda que cobró Paystack, por lo que en un pedido en espera tras una discrepancia de importe o moneda puedes reembolsar hasta lo que el cliente pagó realmente, y no el total del pedido. En XOF y RWF los reembolsos deben ser importes enteros. Paystack pone los reembolsos en cola: la nota y el historial de reembolsos muestran el estado que devuelve Paystack, por ejemplo pending, y el ID del reembolso. Si Paystack no acepta el reembolso, el bloque muestra Error del reembolso de Paystack: con el motivo, y no se registra ningún reembolso. Un reembolso total pone el pedido en Refunded. Un reembolso parcial no cambia el estado. Los reembolsos están disponibles una vez que Paystack ha confirmado el pago.

El módulo no crea abonos. Los botones de reembolso estándar de PrestaShop en la página del pedido no devuelven dinero a través de Paystack.

Los reembolsos hechos en el panel de Paystack, y el estado final de los reembolsos que Paystack pone en cola, no se sincronizan con PrestaShop. Si es necesario, regístralos manualmente.

Clave de licencia

El módulo funciona con una clave de licencia de VibeFox de vibefox.net. El bloque de licencia License — VibeFox Paystack Payment es el primer bloque de Modules > Module Manager > VibeFox Paystack Payment > 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-paystack y el enlace Manage licenses and domains in your account, que abre tu cuenta de vibefox.net. Solo los empleados con el permiso Configure para el módulo pueden cambiar la clave. Los textos del bloque siguen el idioma del back office (se incluyen el inglés y el 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 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. Libérala en tu cuenta de vibefox.net.

Sin una clave activa, Paystack no se muestra a los clientes en la finalización de compra. Si se inicia un pago de todos modos, 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. En Modules > Module Manager, en la pestaña Alerts, aparece un recordatorio. 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 después de introducir la clave, y después una vez a la semana. No hace falta configurar ninguna tarea cron. Desinstalar o restablecer el módulo elimina siempre la clave de licencia y el estado de la licencia.

Solución de problemas

Paystack no aparece en la finalización de compra: comprueba que la licencia está activa, que Enable/Disable está activado, que el modo actual tiene una clave secreta correcta (Test Secret Key con sk_test_... en modo de prueba, Live Secret Key con sk_live_... en modo real) y que la moneda del carrito es una que Paystack acepta. El cuadro de estado de la parte superior de los ajustes indica 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.

El pago se realizó, pero no se creó ningún pedido: el webhook no llegó a tu tienda y el cliente no volvió. En el panel de Paystack comprueba que la Test Webhook URL y la Live Webhook URL son exactamente la URL que aparece en Webhook URL, y que ningún cortafuegos ni protección con contraseña la bloquea. Activa Debug log y revisa el campo Log por si hay webhooks rechazados.

El webhook responde Invalid signature: el webhook no se firmó con la clave secreta de prueba o real introducida en los ajustes, por ejemplo porque las claves pertenecen a otra cuenta de Paystack. Introduce las claves de la cuenta que envía el webhook.

El webhook responde Secret key not configured: no hay ninguna clave secreta configurada. Introduce las claves secretas en los ajustes.

El webhook responde Verification failed, Busy, retry later o Order could not be created, retry later: en ese momento no se pudo leer la transacción desde la API de Paystack, el carrito estaba siendo procesado a la vez por el regreso del cliente, o no se pudo crear el pedido (por ejemplo, porque el módulo está desactivado). Paystack vuelve a enviar el webhook. El registro muestra el motivo.

El webhook responde OK - unknown reference: el pago no se realizó para un carrito de esta tienda, por ejemplo una página de pago de Paystack o de otra integración en la misma cuenta. Se ignora.

La URL del webhook muestra Empty body en el navegador: es normal. La URL solo acepta solicitudes de Paystack.

El cliente ve el mensaje «La pasarela de pago no está configurada correctamente»: la clave secreta del modo actual falta o es incorrecta. Corrígela siguiendo el cuadro de estado de la parte superior de los ajustes.

El pedido está en Paystack payment on hold tras el pago: lee las notas de pago en el bloque Paystack payment (ver Estados del pedido) y luego procesa el pedido o reembolsa el pago.

El pedido permanece en Awaiting Paystack payment: Paystack todavía no ha confirmado el pago. Revisa la transacción en el panel de Paystack y la configuración del webhook. Si el cliente nunca completó el pago, cambia el estado manualmente.

El reembolso falla con un mensaje sobre el modo: el pago se realizó en modo de prueba o real, y la clave secreta de ese modo no está configurada. Introdúcela e inténtalo de nuevo.

Los desarrolladores pueden cambiar la solicitud de transacción y la lista de monedas con los hooks del módulo actionWcpPaystackPaymentRequest, actionWcpPaystackSupportedCurrencies y actionWcpPaystackCurrencyDecimals.

Desinstalación

Ve a Modules > Module Manager, abre el menú junto a VibeFox Paystack Payment y elige Uninstall. La clave de licencia y el estado de la 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 Paystack de los pedidos, los reembolsos y los estados de pedido Awaiting Paystack payment y Paystack payment on hold siempre se conservan, para que los pedidos pagados antes se puedan reembolsar tras una reinstalación. Los pedidos existentes conservan sus notas de pago y sus ID de transacción.

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