VibeFox Khipu for WooCommerce — Ayuda

Requisitos

WordPress: 6.0 o posterior.

WooCommerce: 8.0 o posterior, instalado y activo. Sin WooCommerce, el plugin no se activa.

PHP: 8.0 o posterior.

Moneda de la tienda: peso chileno (CLP), peso argentino (ARS) o sol peruano (PEN). El método de pago se oculta en la finalización de compra cuando la tienda, o el pedido en la página Pay for order, usa otra moneda.

Cuenta de Khipu: necesitas el Receiver ID ("Id de cobrador"), la clave de API y la clave secreta ("llave") de tu cuenta de cobros de Khipu. Los encuentras en tu cuenta de Khipu, en el perfil de comercio (khipu.com/merchant/profile). Los tres son obligatorios: sin la clave secreta no se puede confirmar ningún pago.

Sitio accesible: Khipu confirma los pagos llamando a tu tienda, así que el sitio debe ser accesible desde internet (sin modo mantenimiento, autenticación básica ni cortafuegos que bloquee a Khipu).

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

2. Haz clic en Activate.

3. Abre los ajustes: WooCommerce > Settings > Payments > Khipu > Manage, o haz clic en Settings bajo el nombre del plugin en la página 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 el Receiver ID, la API key y la Secret key de tu cuenta de cobros de Khipu (consulta Configuración).

6. Activa Enable / Disable y guarda. Para probar primero, usa las claves de una cuenta de desarrollador de Khipu y después sustitúyelas por las claves de tu cuenta de producción.

Configuración

Todos los ajustes están en una sola página: WooCommerce > Settings > Payments > Khipu. Encima de los campos, la página te avisa cuando falta el Receiver ID, la clave de API o la clave secreta (en ese caso Khipu no se ofrece en la finalización de compra) y cuando la moneda de la tienda no es compatible. En la lista de métodos de pago, Khipu aparece marcado como pendiente de configurar hasta que se introducen las tres claves.

General

Enable / Disable: Enable Khipu payments activa o desactiva el método de pago. Predeterminado: desactivado.

Title: el nombre del método de pago que ven los clientes en la finalización de compra. Predeterminado: Khipu.

Description: el texto que se muestra bajo el método de pago en la finalización de compra. Predeterminado: Pay by bank transfer with Khipu.

Cuenta de Khipu

Copia el Receiver ID, la clave de API y la clave secreta de tu cuenta de cobros de Khipu (khipu.com/merchant/profile). Khipu no tiene un servidor sandbox aparte y el plugin no tiene interruptor de modo de prueba. Para probar, usa las claves de una cuenta de cobros de desarrollador ("desarrollo"): paga con el banco de pruebas DemoBank y no se mueve dinero real. Cambia a las claves de tu cuenta de cobros de producción cuando te pongas en producción.

Receiver ID: el ID de cobrador ("cobrador") de tu cuenta de Khipu. Los pagos de otras cuentas de Khipu se rechazan.

API key: se usa para crear pagos y para verificar cada pago con Khipu.

Secret key: se usa para verificar la firma (HMAC-SHA256) de las notificaciones de pago de Khipu. Sin ella no se puede confirmar ningún pago.

Notificaciones de pago

Khipu confirma los pagos llamando a la URL de notificación que se muestra en esta sección de los ajustes. Tiene el formato https://your-site/wc-api/webhook_wc_khipu/. La URL se envía automáticamente con cada pago, así que no hay nada que configurar en tu cuenta de Khipu, pero la URL debe ser accesible desde internet.

Cada notificación debe llevar una firma válida hecha con tu Secret key. Las notificaciones sin una firma válida se rechazan. Después, el plugin pregunta a Khipu por el estado del pago y actúa según lo que Khipu responde:

Status after payment: el estado del pedido una vez que Khipu confirma el pago. El estado se establece de inmediato, con un solo cambio de estado y un solo conjunto de correos electrónicos.

Avanzado

Debug log: Log API calls and notifications en WooCommerce > Status > Logs, origen wcp_khipu_gateway. Los errores se registran siempre. Las claves y los datos del pagador nunca se escriben. Predeterminado: desactivado.

Delete data on uninstall: Remove the gateway settings and logs when the plugin is deleted. Los datos de los pedidos (los IDs de pago de Khipu en los pedidos) se conservan siempre. Predeterminado: desactivado.

Finalización de compra

El cliente elige el método de pago (por defecto, Khipu) y realiza el pedido. El plugin crea un pago de Khipu por el total del pedido en la moneda del pedido, con el número de pedido, el nombre de la tienda y los artículos pedidos, y envía al cliente a la página de pago de Khipu. El correo electrónico de facturación se pasa a Khipu cuando es válido. En la página de Khipu, el cliente paga mediante transferencia bancaria desde su propio banco y elige allí entre los tipos de transferencia que ofrece Khipu.

Después de pagar, el cliente vuelve a la página de pedido recibido de tu tienda. El pedido se marca como pagado solo cuando Khipu confirma la transferencia: mediante la notificación firmada, o mediante una consulta de estado a Khipu cuando el cliente abre la página de pedido recibido. La vuelta en sí nunca marca un pedido como pagado. Mientras la transferencia no esté confirmada, la página muestra Khipu is confirming your bank transfer. Your order will be updated automatically as soon as Khipu confirms the payment, and you will receive an e-mail.

Si el cliente abandona la página de Khipu sin pagar, llega a la página Pay for order con The Khipu payment was not completed. You can try again or choose another payment method. Un nuevo intento elimina el pago de Khipu anterior no pagado, por lo que el enlace antiguo ya no se puede pagar. Si Khipu ya recibió el pago anterior, el pedido se completa y no se crea ningún pago nuevo. Si la transferencia anterior aún se está verificando, el cliente ve Your previous Khipu payment for this order is still being verified by the bank. Please wait a few minutes before paying again.

Con la gestión de stock activada, el pago de Khipu caduca junto con el tiempo de Hold stock (minutes) de WooCommerce, de modo que el cliente no puede pagar un pedido que ya se canceló.

Si Khipu no puede crear el pago, el cliente ve un mensaje breve, por ejemplo Khipu could not create the payment for this order. Please check your billing details and try again, or contact the store. o Khipu is temporarily unavailable. Please try again in a few minutes. Los detalles se escriben en el registro.

El método de pago funciona en la finalización de compra clásica, en el bloque Checkout y en la página Pay for order. Es compatible con el almacenamiento de pedidos de alto rendimiento (HPOS) de WooCommerce.

El plugin solo acepta pagos únicos por transferencia bancaria. Los reembolsos desde WooCommerce no son compatibles y no tiene suscripciones, métodos de pago guardados ni preautorizaciones.

Pedidos

Estados de pedido

Pending payment: el cliente fue enviado a Khipu y todavía no ha pagado, o Khipu aún no ha confirmado la transferencia. La nota del pedido muestra el ID de pago de Khipu.

Processing or Completed: Khipu confirmó el pago. El estado sigue lo indicado en Status after payment. La nota del pedido muestra el ID de pago de Khipu y el ID de transacción es el ID de pago de Khipu.

On hold: Khipu informó de un pago cuyo importe o moneda no coincide con el pedido, o el pago llegó después de que el pedido se hubiera cancelado (por ejemplo, tras el tiempo de retención de stock). La nota del pedido lo explica. Comprueba el pago en tu cuenta de Khipu y completa el pedido o haz un reembolso al cliente.

Si llega un pago para un pedido que ya está pagado o que se cerró después del pago, el pedido no se modifica. Una nota te pide que lo reembolses al cliente si se trata de un segundo pago.

Reembolsos

Los reembolsos no se envían a Khipu desde WooCommerce. Reembolsa al cliente desde tu cuenta de Khipu o por transferencia bancaria y, después, registra el reembolso manualmente en 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 > Khipu. 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 solo dominio. Quitar la clave de un sitio no libera su hueco de dominio. Libera el hueco en tu cuenta de vibefox.net.

Sin una clave activa, Khipu no se muestra a los clientes en la finalización de compra. Si aun así se inicia un pago, 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 (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 Plugins y en las páginas de WooCommerce. Los pedidos existentes no se ven afectados: los pagos ya iniciados se siguen confirmando.

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

Khipu no aparece en la finalización de compra: comprueba que la licencia esté activa, que Enable / Disable esté activado y que el Receiver ID, la API key y la Secret key estén todos introducidos. La moneda de la tienda debe ser CLP, ARS o PEN. La página de ajustes muestra un aviso cuando falta algo.

El pago se realizó, pero el pedido sigue en Pendiente de pago: Khipu confirma una transferencia después de que el banco la haya verificado. El pedido se actualiza cuando llega la notificación de Khipu o cuando el cliente abre la página de pedido recibido. Comprueba que tu sitio sea accesible desde internet en la URL de notificación que se muestra en los ajustes (sin modo mantenimiento, autenticación básica ni cortafuegos que bloquee a Khipu) y revisa WooCommerce > Status > Logs, origen wcp_khipu_gateway.

La notificación responde Secret key not configured: la Secret key está vacía. Introdúcela. Khipu enviará la notificación de nuevo.

La notificación responde Invalid signature, Missing signature o Malformed signature: la Secret key no pertenece a la cuenta de cobros cuyas claves usas, o la solicitud no vino de Khipu.

La notificación responde Payment does not belong to this order: el pago se hizo a otro Receiver ID o para otro pedido. Comprueba el Receiver ID.

La notificación responde Payment not final yet o Verification unavailable: la transferencia aún se está verificando, o no se pudo contactar con Khipu. Khipu enviará la notificación de nuevo.

El pedido está En espera: lee la nota del pedido. El importe o la moneda no coincidían con el pedido, o el pago llegó después de que el pedido se hubiera cancelado.

El cliente ve "Khipu payments are not available right now": la clave de API falta o es incorrecta. Comprueba las claves en tu cuenta de Khipu.

El bloque de licencia muestra un error: sigue el mensaje del bloque. Por ejemplo, si la clave ya se usa en otro dominio, libera un hueco en tu cuenta de vibefox.net y haz clic en Check now. Si la dirección del sitio ha cambiado, 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.

Si tu cuenta de Khipu acepta otra moneda, por ejemplo EUR para Khipu España, los desarrolladores pueden añadirla con el filtro wc_khp_supported_currencies.

Desinstalación

Al desactivar el plugin se conservan todos los datos. Para eliminarlo, desactívalo y bórralo en la página Plugins. La clave de licencia y el estado de la licencia de este plugin se eliminan siempre. 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 futura reinstalación. Los pedidos existentes mantienen sus notas de pago y sus IDs de transacción.

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