VibeFox Paystack 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 una moneda que acepte Paystack: NGN, USD, GHS, ZAR, KES, XOF, EGP o RWF, según lo habilitado en tu cuenta de Paystack. En otras monedas el método de pago se oculta. En XOF y RWF, Paystack solo acepta 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 (consulta Configuración). Tu sitio debe ser accesible desde internet para recibir los webhooks.

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_paystack_payment a /wp-content/plugins/ por FTP.

2. Haz clic en Activate.

3. Abre la configuración: WooCommerce > Settings > Payments > Paystack > 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. Pega tus claves secretas del panel de Paystack y configura la URL del webhook en el panel de Paystack (consulta Configuración).

6. Activa Enable/Disable y guarda. Mantén Test Mode activado hasta que hayas hecho un pago de prueba; después desmárcalo para aceptar pagos reales.

Configuración

Todos los ajustes están en una sola página: WooCommerce > Settings > Payments > Paystack. 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 falta la clave secreta del modo actual, 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 de tu tienda. Mientras exista un problema con las claves, el método de pago se oculta en la finalización de compra. En la lista de métodos de pago, Paystack aparece como pendiente de configuración hasta que el modo actual tenga una clave secreta.

Finalización de compra

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. Por defecto: Paystack.

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 de API

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

Test Mode: Enable Test Mode usa la clave secreta de prueba para los pagos nuevos, y no se cobra dinero real. Desmárcalo para aceptar pagos reales con la clave secreta real. Los pagos realizados en el otro modo siguen usando la clave de su propio modo para la verificación y los reembolsos. Por defecto: activado.

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_.

Webhook

El webhook informa a tu tienda de que se ha realizado un pago, incluso cuando el cliente no vuelve a la tienda. En el panel de Paystack, en la página Settings > API Keys & Webhooks, introduce la URL que aparece en esta sección tanto en Test Webhook URL como en Live Webhook URL. Tiene este aspecto: https://your-site/wc-api/paystack_p_webhook/. Copia la URL exactamente como aparece en los ajustes.

Paystack firma cada webhook con tu clave secreta, así que no hay que configurar nada más. Los webhooks de prueba se verifican con la clave secreta de prueba, y los reales con la clave secreta real. Los webhooks sin firma válida se rechazan. El plugin usa el evento charge.success:

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

Pedidos

Autocomplete Order: Automatically mark orders as completed after successful payment. Si está marcado, los pedidos pagados pasan a Completado en lugar de Procesando, con un solo cambio de estado y un único correo al cliente. Por defecto: desactivado.

Avanzado

Debug log: Log Paystack events and API calls for debugging escribe los detalles en WooCommerce > Status > Logs, origen wcp_paystack_payment. Los errores siempre se registran. Nunca se registran claves ni datos de clientes. Por defecto: desactivado.

Delete data on uninstall: Remove the gateway settings and logs when the plugin is deleted. Desactivar el plugin nunca borra nada. Los datos de pago guardados en los pedidos siempre se conservan. Por defecto: desactivado.

Finalización de compra

El cliente elige el método de pago (por defecto Paystack) y realiza el pedido. En modo de prueba, la finalización de compra muestra MODO DE PRUEBA ACTIVADO. No se realizará ningún cargo real. El plugin inicia una transacción de Paystack por el total del pedido en la moneda del pedido, con el correo de facturación del pedido, 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.

Tras pagar, el cliente regresa a tu tienda. El pedido se marca como pagado solo cuando Paystack lo confirma: cuando el cliente vuelve y cuando llega el webhook, el plugin lee la transacción desde la API de Paystack con la clave secreta del modo en que se inició el pago, y comprueba la referencia, el estado, el importe y la moneda. Si el pago todavía se está procesando, por ejemplo una transferencia bancaria, la página de pedido recibido muestra Paystack está confirmando tu pago. Recibirás un correo electrónico en cuanto se confirme. El webhook completa el pedido más tarde.

Si el cliente cancela en la página de Paystack o la abandona sin pagar, el pedido sigue esperando el pago. El cliente vuelve a la finalización de compra o a la página Pay for order 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. El cliente puede volver a pagar el mismo pedido. Una página de pago anterior del pedido sigue siendo válida: si se paga más tarde, el pago se sigue aceptando.

La página de pedido recibido solo se abre para el cliente del pedido: mediante el enlace de retorno firmado, la sesión de finalización de compra que creó el pedido o la cuenta del cliente. Cualquier otra persona es enviada a la finalización de compra con un mensaje neutro, y no se muestra la página del pedido.

Si Paystack no puede iniciar el pago, el cliente ve 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 unos minutos o elige otro método de pago. El total del pedido debe ser mayor que cero, y el pedido necesita una dirección de correo electrónico válida.

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 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 WooCommerce.

Pedidos y reembolsos

Estados del pedido

Pending payment: el cliente fue enviado a Paystack y todavía no ha pagado, abandonó la página de Paystack sin pagar, o Paystack sigue procesando el pago. Cuando el cliente vuelve sin haber pagado, una nota indica que el pedido sigue esperando el pago.

Processing or Completed: el pago fue confirmado. El estado es Completado cuando Autocomplete Order está activado. La nota del pedido muestra el importe, la referencia de Paystack, el número de transacción, el modo (de 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 pagó el cliente. El ID de transacción del pedido es la referencia de Paystack (order_...).

On hold: el importe o la moneda pagados no coinciden con el pedido (nota Paystack amount or currency mismatch), o el pago llegó después de que el pedido se hubiera cancelado. La nota del pedido explica qué revisar. Procesa el pedido o reembolsa el pago.

Failed: Paystack informa de que el último intento de pago de un pedido pendiente ha fallado o se ha revertido. Un fallo de un intento anterior no cambia el pedido. El cliente puede volver a pagar.

Si un segundo intento de pago de un pedido que ya está pagado también se paga, el pedido no cambia. Una nota te pide reembolsar el pago duplicado en el panel de Paystack. Un pago que llega para un pedido en otro estado, por ejemplo Refunded, solo se anota en el pedido.

Reembolsos

Abre el pedido, haz clic en Refund, introduce el importe y haz clic en Refund via Paystack. Se admiten reembolsos totales y parciales. El botón de reembolso solo aparece en pedidos pagados mediante una transacción verificada de Paystack. El reembolso se envía a la transacción que pagó el pedido, con la clave secreta del modo (de prueba o real) en que se realizó, por lo que esa clave debe estar configurada. En XOF y RWF, los reembolsos deben ser importes enteros. Paystack pone los reembolsos en cola: la nota del pedido muestra el estado que devuelve Paystack, por ejemplo pendiente, y el ID del reembolso. Si Paystack no acepta el reembolso, WooCommerce muestra Paystack refund failed: con el motivo, y no se registra ningún reembolso.

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

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 > Paystack. 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. 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 un pago se inicia de todos modos, el cliente ve This payment method is not available. Please choose another one. Los gestores de la tienda que han iniciado sesión 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

Paystack no aparece en la finalización de compra: comprueba que la licencia esté activa, que Enable/Disable esté activado, que el modo actual tenga 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 pedido sea una que acepte Paystack. El cuadro de estado en la parte superior de los ajustes indica el problema.

El pago se realizó, pero el pedido sigue en Pending payment: 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 sean exactamente la URL que aparece en los ajustes, y que ningún modo de mantenimiento, cortafuegos o protección con contraseña la bloquee. Revisa WooCommerce > Status > Logs, origen wcp_paystack_payment, por si hay webhooks rechazados.

El webhook responde «Invalid signature»: el webhook no está firmado 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» o «Busy, retry later»: en ese momento no se pudo leer la transacción desde la API de Paystack, o el regreso del cliente estaba actualizando el pedido al mismo tiempo. El pedido no se modifica y Paystack vuelve a enviar el webhook.

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

El cliente ve «Payment gateway is not properly configured»: falta o es incorrecta la clave secreta del modo actual. Corrígela siguiendo el cuadro de estado de la parte superior de los ajustes.

El pedido está en On hold después del pago: lee la nota del pedido. El importe o la moneda pagados eran distintos del pedido, o el pago llegó después de que el pedido se hubiera cancelado. Procesa el pedido o reembolsa el pago.

El reembolso falla con un mensaje sobre el modo: el pago se hizo en modo de prueba o real, y la clave secreta de ese modo no está configurada. Introdúcela y vuelve a intentarlo. El mensaje No verified Paystack payment was found for this order significa que el pedido no se pagó mediante una transacción verificada de Paystack. Reembólsalo en el panel de Paystack.

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 cambió la dirección del sitio, haz clic en Check now para activar la clave en 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 licencia de este plugin siempre se eliminan. Los ajustes de la pasarela y los registros solo se eliminan si Delete data on uninstall estaba activado. En caso contrario, se conservan para una reinstalación posterior. Los pedidos existentes conservan sus notas de pago, sus ID de transacción y sus referencias de Paystack.

Paystack es una marca comercial de su respectivo titular. Este plugin no está afiliado a Paystack ni cuenta con su respaldo.