VibeFox Kushki for WooCommerce — Ayuda
Requisitos
WordPress: 6.0 o posterior.
WooCommerce: 8.0 o posterior, instalado y activo. El plugin no se activa sin él.
PHP: 8.0 o posterior.
Moneda de la tienda: USD (Ecuador) o COP (Colombia). Para otras monedas el método de pago se oculta en la finalización de compra.
HTTPS: Kushki exige que la finalización de compra se sirva por HTTPS en modo real.
Cuenta de Kushki: necesitas los IDs de comerciante Públicos y Privados de tu cuenta de prueba (UAT) de Kushki y de tu cuenta de producción. Están en la consola de Kushki, en Developers > Credentials. Para el webhook opcional necesitas también la clave de firma del webhook de cada cuenta (ver Configuración).
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_kushki_payment a /wp-content/plugins/ por FTP.
2. Haz clic en Activate.
3. Abre los ajustes: WooCommerce > Settings > Payments > Kushki > 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 los IDs de comerciante Públicos y Privados de prueba y deja Test mode activado. Opcionalmente, configura el webhook en la consola de Kushki y pega su clave de firma (ver Configuración).
6. Activa Enable / Disable y realiza un pedido de prueba. Cuando estés listo, introduce los IDs de comerciante reales (y la firma del webhook real) y desmarca Test mode.
Configuración
Todos los ajustes están en una sola página: WooCommerce > Settings > Payments > Kushki. Encima de los campos, la página te avisa cuando el método de pago está activado pero faltan los IDs de comerciante del modo actual (en ese caso el método de pago se oculta en la finalización de compra), cuando la moneda de la tienda no es compatible, cuando se usa el modo real sin HTTPS y cuando el modo actual no tiene firma de webhook. Mientras el modo de prueba está activado, muestra Test mode is on: the Kushki test environment is used, no real money is charged. Si guardas con el método de pago activado pero sin los IDs de comerciante del modo actual, aparece un error que te recuerda introducirlos. Los espacios alrededor de los IDs se eliminan al guardar.
General
Enable / Disable: Enable Kushki card payments 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: Credit / debit card (Kushki).
Description: el texto que se muestra encima del formulario de tarjeta en la finalización de compra. Por defecto: Pay securely with your card. Card details are entered in a Kushki form and never stored on this site.
Credenciales de API
Copia los IDs de comerciante Públicos y Privados desde la consola de Kushki (Developers > Credentials). Las cuentas de prueba (UAT) y de producción tienen IDs distintos. El modo de prueba usa solo los IDs de prueba, y el modo real solo los IDs reales.
Test mode: Use the Kushki test (UAT) environment cambia a la vez los IDs de comerciante, el formulario de tarjeta y la API al entorno de prueba de Kushki. No se cobra dinero real y se muestra una insignia TEST MODE en la finalización de compra. Por defecto: activado. Desmárcalo para aceptar pagos reales.
Test Public Merchant ID: el ID de comerciante Público de tu cuenta de prueba de Kushki. Carga el formulario de tarjeta.
Test Private Merchant ID: el ID de comerciante Privado de tu cuenta de prueba de Kushki. Se usa en el servidor para los cargos y los reembolsos.
Live Public Merchant ID: el ID de comerciante Público de tu cuenta de producción de Kushki.
Live Private Merchant ID: el ID de comerciante Privado de tu cuenta de producción de Kushki. Mantenlo en secreto.
Webhook (recomendado)
Los pagos se confirman de inmediato con la respuesta de la API de Kushki, así que el webhook no es obligatorio. Además confirma los pagos cuya respuesta se perdió (por ejemplo, por un tiempo de espera) y registra las anulaciones y los reembolsos hechos en la consola de Kushki. En la consola de Kushki (Webhooks) añade la URL que se muestra en esta sección de los ajustes para los pagos con tarjeta. Tiene este aspecto: https://your-site/wc-api/webhook_kushki_p/. Hazlo para la cuenta de prueba y para la cuenta de producción.
El plugin gestiona estas notificaciones de tarjeta:
Test webhook signature: la clave de firma del webhook de la cuenta de prueba de Kushki (Console > Webhooks).
Live webhook signature: la clave de firma del webhook de la cuenta de producción de Kushki.
Los webhooks sin una firma válida se rechazan. Sin clave de firma, todas las notificaciones de webhook se rechazan, pero los pagos siguen funcionando, porque se confirman con la respuesta de la API.
Avanzado
Debug log: Log API calls and webhooks escribe las solicitudes y los webhooks de Kushki en WooCommerce > Status > Logs, origen wcp_kushki_payment. Los errores siempre se registran. Los registros nunca contienen IDs de comerciante, tokens de tarjeta ni correos de clientes. Por defecto: desactivado.
Delete data on uninstall: si está activado, al eliminar el plugin se borran los ajustes y los registros. Los pedidos y sus referencias de Kushki se conservan. Por defecto: desactivado.
Finalización de compra
El cliente elige el método de pago (por defecto Credit / debit card (Kushki)). El formulario de tarjeta de Kushki aparece debajo, con el total del pedido en la moneda del pedido. En la página Pay for order el formulario usa el total del pedido. El cliente introduce la tarjeta, elige las cuotas si el formulario de Kushki las ofrece y pulsa el botón de pago dentro del formulario de Kushki.
En la finalización de compra clásica el botón Place order de WooCommerce se oculta mientras Kushki está seleccionado: una vez aceptada la tarjeta, el pedido se envía automáticamente. En el bloque de Finalizar compra el cliente también pulsa el botón de pago dentro del formulario de Kushki. Si el cliente intenta realizar el pedido sin hacerlo, se muestra el mensaje Please enter your card details in the Kushki form and press its pay button.
Después tu tienda cobra la tarjeta en el servidor. El pedido se marca como pagado solo cuando Kushki lo confirma con un número de ticket, y el cliente pasa directamente a la página de pedido recibido. Si Kushki informa de un importe o una moneda aprobados, se comparan con el pedido.
Si la tarjeta es rechazada, el cliente ve Your payment was declined con el motivo de Kushki y puede probar otra tarjeta en el mismo formulario. Ante problemas de red, de claves o del servidor, el cliente ve The payment could not be processed right now. Please try again in a moment or choose another payment method. El motivo técnico se añade a las notas del pedido y al registro. Un segundo clic mientras se procesa un pago muestra A payment for this order is already being processed. Please wait a moment and check your order status.
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 3-D Secure, las reglas antifraude y las cuotas ofrecidas se configuran en la consola de Kushki.
El plugin solo admite pagos con tarjeta de un solo paso. No tiene reembolsos parciales, tarjetas guardadas, suscripciones ni Add payment method, ni pagos en efectivo, transferencias bancarias (PSE) ni pagos con tarjeta de débito por redirección, y no permite autorizar y capturar por separado.
Pedidos y reembolsos
Estados del pedido
Pending payment: el pedido se ha creado y la tarjeta aún no se ha cobrado.
Processing: Kushki confirmó el cargo (por la respuesta de la API o por el webhook). Los pedidos con solo productos descargables virtuales pasan a Completed, el valor por defecto de WooCommerce. La nota del pedido muestra el modo, el número de ticket de Kushki y la referencia. El ID de transacción es la referencia de transacción de Kushki (o el número de ticket).
On hold: Kushki devolvió un éxito sin número de ticket, o informó de un importe o una moneda distintos a los del pedido. La nota del pedido lo explica. Comprueba la transacción en la consola de Kushki y completa el pedido o reembolsa el pago.
Failed: la tarjeta fue rechazada o no se pudo realizar el cargo. La nota del pedido muestra el código y el mensaje de Kushki. El cliente puede volver a pagar.
Si un webhook informa de otro cargo aprobado para un pedido que ya está pagado, cancelado o reembolsado, el pedido no se modifica. Una nota te pide que compruebes si hay un cobro duplicado y que lo reembolses en la consola de Kushki. Un webhook del entorno de prueba para un pedido real (o al revés) se ignora con una nota.
Reembolsos
Abre el pedido, haz clic en Refund, introduce el total completo del pedido y haz clic en Refund via Credit / debit card (Kushki) (el botón muestra tu Title). Kushki reembolsa el pago completo, así que solo se aceptan reembolsos completos. Para un importe parcial, el plugin muestra Kushki refunds the full payment only. Enter the full order total as the refund amount, or make a partial refund manually in the Kushki Console. Un pago solo se puede reembolsar una vez.
El reembolso se envía en el modo en que se hizo el pago (prueba o real), así que debe estar configurado el ID de comerciante Privado de ese modo. Si Kushki no acepta el reembolso, WooCommerce muestra el error y no se registra ningún reembolso. Un reembolso correcto se añade a las notas del pedido con el número de ticket de reembolso de Kushki.
Las anulaciones y los reembolsos hechos en la consola de Kushki llegan por webhook y se añaden a las notas del pedido. No se registran automáticamente como reembolsos de WooCommerce.
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 > Kushki. 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. Libera la plaza en tu cuenta de vibefox.net.
Sin una clave activa, Kushki 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 administradores 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. Un recordatorio aparece en la página de Plugins y en las páginas de WooCommerce. Los pedidos existentes no se ven afectados: los webhooks siguen procesándose y los reembolsos funcionan.
Cuando una licencia caduca, el plugin sigue funcionando, pero las actualizaciones y el soporte requieren renovación. El estado se vuelve a comprobar automáticamente en segundo plano.
Solución de problemas
Kushki no aparece en la finalización de compra: comprueba que la licencia está activa, que Enable / Disable está activado y que el modo actual tiene ambos IDs de comerciante: los IDs de prueba en modo de prueba, los IDs reales en modo real. Comprueba que la moneda de la tienda (o la moneda del pedido en la página Pay for order) es USD o COP. La página de ajustes muestra un aviso para cada uno de estos problemas.
El pago se realizó, pero el pedido está Failed o sigue en Pending payment: la respuesta de la API de Kushki se perdió, por ejemplo por un tiempo de espera. El webhook confirma estos pagos. En la consola de Kushki comprueba que la URL del webhook es exactamente la que se muestra en los ajustes, para la cuenta del modo que usas, y que la clave de firma de esa cuenta está en el campo correspondiente (Test webhook signature o Live webhook signature). Un cargo aprobado sin el importe y la moneda pagados pone el pedido en espera en su lugar.
El webhook responde Webhook signature not configured: no hay ninguna firma de webhook configurada. Pega la clave de firma en los ajustes.
El webhook responde Invalid signature: la clave de firma pertenece a otra cuenta o modo, o la notificación se modificó por el camino.
El webhook responde Order mismatch: la notificación no pertenece a este pedido (clave de pedido o transacción incorrectas). El pedido no se modifica.
El webhook responde Busy, retry later: otra solicitud estaba procesando el pedido en el mismo momento. Kushki puede volver a enviar la notificación.
El formulario de tarjeta no se carga: el cliente ve The Kushki card form could not be loaded. Please reload the page or choose another payment method. Comprueba el ID de comerciante Público del modo actual.
El cliente ve This payment option is not available in this store. Please pay by card.: se eligió una opción de pago que no es tarjeta en el formulario de Kushki. El plugin solo cobra tarjetas.
El cliente ve un error al pagar: abre las notas del pedido o activa el Debug log y revisa WooCommerce > Status > Logs, origen wcp_kushki_payment. Un ID de comerciante Privado incorrecto o ausente da el mensaje general de que el pago no se pudo procesar.
El reembolso falla con un mensaje sobre el modo: el pago se realizó en modo de prueba o real, y el ID de comerciante Privado de ese modo no está configurado. Introdúcelo y vuelve a intentarlo.
El reembolso falla con No Kushki ticket number found for this order: el pedido no tiene un cargo de Kushki confirmado. Reembólsalo en la consola de Kushki.
Otras monedas: los desarrolladores pueden cambiar la lista de monedas con el filtro kushki_p_supported_currencies bajo su propia responsabilidad. La moneda debe estar activada en tu cuenta de Kushki.
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 para 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 siempre se eliminan. Los ajustes de la pasarela y los registros solo se eliminan si Delete data on uninstall estaba activado. Si no, se conservan para una reinstalación posterior. Los pedidos existentes conservan sus notas de pago, números de ticket de Kushki e IDs de transacción.
Kushki es una marca comercial de su respectivo titular. Este plugin no está afiliado a Kushki ni respaldado por Kushki.