VibeFox Khipu 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: peso chileno (CLP), peso argentino (ARS) o sol peruano (PEN). En los carritos con otras monedas, el método de pago se oculta en la finalización de compra.

Cuenta de Khipu: necesitas el Receiver ID ("Id de cobrador"), la API key y la Secret key de tu cuenta de cobros de Khipu. Los encuentras en tu cuenta de Khipu, en el perfil de comerciante (khipu.com/merchant/profile). Las tres son obligatorias: sin la Secret key no se puede confirmar ningún pago. No hay que configurar nada en la cuenta de Khipu.

Tienda accesible: Khipu confirma los pagos llamando a tu tienda, así que la URL de notificación debe ser accesible desde internet, sin protección con contraseña ni cortafuegos que bloquee a Khipu. El modo de mantenimiento de la tienda no lo bloquea.

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

3. Introduce tu clave de licencia de VibeFox en el campo License key del bloque de licencia de la parte superior de la página Configure y haz clic en Activate (véase Clave de licencia).

4. Introduce el Receiver ID, la API key y la Secret key de tu cuenta de cobros de Khipu (ver Configuración).

5. Activa Enable / Disable y haz clic en Save. Para probar primero, usa las claves de una cuenta de desarrollador de Khipu y luego sustitúyelas por las claves de tu cuenta de producción.

Al instalarse, el módulo crea el estado de pedido Khipu payment on hold. PrestaShop habilita automáticamente el 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 Khipu Gateway > Configure. Cada sección tiene su propio botón Save, que guarda la página completa. Encima de los campos, la página te avisa cuando falta el Receiver ID, la API key o la Secret key (en ese caso Khipu no se ofrece en la finalización de compra) y cuando la moneda predeterminada de la tienda no es compatible con Khipu.

Khipu

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. También es el nombre del método de pago guardado en el pedido. Predeterminado: Khipu. Obligatorio.

Description: el texto que aparece debajo del 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 API key y la Secret key de tu cuenta de cobros de Khipu (khipu.com/merchant/profile). Khipu no tiene un servidor de pruebas aparte y el módulo 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 pases a producción.

Receiver ID: tu ID de cobrador ("cobrador") 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.

Las claves 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 cambiarla.

Clear saved secrets: marca API key o Secret key y haz clic en Save para eliminarla. Un campo vacío mantiene el valor guardado.

Notificaciones de pago

Notification URL: Khipu confirma los pagos llamando a la URL que se muestra aquí. Con URL amigables tiene este aspecto: https://your-shop/module/wcp_khipu_gateway/webhook, posiblemente con un código de idioma. 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 firma válida se rechazan. El módulo nunca confía en el contenido de la notificación: pide a Khipu el estado del pago y actúa según lo que Khipu informe:

Status after payment: el estado del pedido una vez que Khipu confirma el pago. El estado se asigna de inmediato, con un único cambio de estado.

Avanzado

Debug log: registra las llamadas a la API y las notificaciones en logs/wc_khp_debug.log.php, en la carpeta del módulo. El archivo no se puede abrir desde la web. Los errores siempre se registran, incluso con el interruptor desactivado. Nunca se escriben claves ni datos del pagador. Predeterminado: 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 los ajustes de la pasarela y el registro. Los datos de los pedidos (los ID de pago de Khipu de los pedidos) siempre se conservan. Predeterminado: desactivado.

Finalización de compra

En el paso de pago, el cliente elige el método de pago (de forma predeterminada Khipu) con su descripción y confirma el pedido. El módulo crea un pago de Khipu por el total del carrito en la moneda del carrito y envía al cliente a la página de pago de Khipu. En Khipu el pago aparece como Order # con el número de carrito y el nombre de la tienda, junto con la lista de productos. El correo electrónico del cliente se pasa a Khipu cuando es válido. En la página de Khipu, el cliente paga por transferencia bancaria desde su propio banco. Todavía no existe ningún pedido en este punto.

Después de pagar, el cliente vuelve a tu tienda. El pedido se marca como pagado solo cuando Khipu lo confirma: mediante la notificación firmada o mediante una consulta de estado a Khipu cuando el cliente regresa. El retorno en sí nunca marca nada como pagado. Una vez creado el pedido, el cliente ve la página estándar de confirmación del pedido. Si el banco aún está verificando la transferencia o Khipu no responde, aparece una página Payment confirmation con el texto Khipu is confirming your bank transfer. Your order will be created automatically as soon as Khipu confirms the payment, and you will receive an e-mail. y los botones Check again y Back to checkout. Si el último pago de Khipu del carrito no puede asociarse a él (por ejemplo, pertenece a otro Receiver ID), el cliente vuelve a la finalización de compra con el mensaje We could not match this payment to an order. If you paid, please contact us.

Si el cliente sale de la página de Khipu sin pagar, o el pago no se completó, vuelve a la finalización de compra con el mensaje The Khipu payment was not completed. You can try again or choose another payment method. El carrito se conserva. Un nuevo intento elimina el pago de Khipu anterior sin pagar, de modo que el enlace antiguo ya no se puede pagar. Si Khipu ya recibió el pago anterior, se crea el pedido y no se realiza ningún pago nuevo. Si la transferencia anterior todavía 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.

Si Khipu no puede crear el pago, el cliente permanece en la finalización de compra con 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.

La notificación funciona mientras la tienda está en modo de mantenimiento, y no la bloquea la restricción por país de tu tienda.

El módulo admite solo pagos únicos por transferencia bancaria. Los reembolsos no se envían a Khipu desde PrestaShop, y no incluye suscripciones, métodos de pago guardados ni preautorizaciones. Los pagos sin completar no se vinculan a una reserva de stock.

Pedidos

Estados del pedido

No order yet: el cliente fue enviado a Khipu y no ha pagado, o Khipu todavía no ha confirmado la transferencia. Solo existe el carrito.

Payment accepted or Delivered: Khipu confirmó el pago. El estado sigue a Status after payment. El pago se registra con el ID de pago de Khipu como ID de transacción, y una nota muestra Khipu payment verified. Payment ID: con el ID de pago y el importe.

Khipu payment on hold: Khipu confirmó un pago cuyo importe o moneda no coincide con el pedido (por ejemplo, el carrito se cambió después de iniciar el pago), o el pago llegó después de que el pedido se cancelara. El importe realmente recibido se registra en el pedido (no cuando la moneda es distinta), y una nota lo explica. Comprueba el pago en tu cuenta de Khipu y luego completa el pedido o reembolsa al cliente. Si llega un pago posterior por el importe correcto para el mismo carrito, el pedido pasa al estado de pagado.

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. Si Khipu informa de que un pago pagado fue revertido, el pedido recibe una nota y su estado no cambia.

Bloque de pago de Khipu

La página del pedido muestra un bloque Khipu payment con los intentos de pago de Khipu del carrito del pedido (fecha, importe, ID de pago de Khipu, estado y resultado de Khipu), una advertencia Manual review mientras el pedido esté en Khipu payment on hold, y las Khipu notes del pedido. El bloque es de solo lectura.

Reembolsos

Los reembolsos no se envían a Khipu desde PrestaShop, porque Khipu no ofrece reembolsos a través de su API. Reembolsa al cliente desde tu cuenta de Khipu o por transferencia bancaria, y después registra el reembolso manualmente en PrestaShop.

Clave de licencia

El módulo funciona con una clave de licencia de VibeFox de vibefox.net. El bloque de licencia License — VibeFox Khipu Gateway es el primer bloque de Modules > Module Manager > VibeFox Khipu Gateway > 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 aparecen la línea Product: presta-payment-khipu 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 tras liberar una plaza de dominio en tu cuenta, haz clic en Check now. Si no se puede acceder al servidor de licencias, el módulo sigue funcionando con el último estado conocido.

Una clave funciona en un dominio: el dominio de la tienda principal, también en una configuración multitienda. Eliminar la clave de la tienda no libera su plaza de dominio. Libera la plaza en tu cuenta de vibefox.net.

Sin una clave activa, Khipu 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 confirmando.

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 hace falta ninguna tarea cron. Al desinstalar o restablecer el módulo, siempre se eliminan la clave de licencia y el estado de la licencia.

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 del carrito debe ser CLP, ARS o PEN. La página de ajustes muestra una advertencia cuando falta algo. 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: Khipu confirma una transferencia después de que el banco la haya verificado. El pedido se crea cuando llega la notificación de Khipu o cuando el cliente hace clic en Check again. Comprueba que tu tienda sea accesible desde internet en la URL que aparece en Notification URL (sin protección con contraseña ni cortafuegos que bloquee a Khipu), y revisa el campo Log de la página del módulo.

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

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

La notificación responde Order not found or Payment does not belong to this order: el pago se hizo a otro Receiver ID o para otro carrito. Revisa el Receiver ID.

La notificación responde Payment not final yet or Verification unavailable: la transferencia todavía se está verificando, o Khipu no pudo ser contactado. Khipu vuelve a enviar la notificación.

La notificación responde Busy, retry later or Order could not be created, retry later: otra solicitud estaba confirmando el pedido en ese mismo momento, o el pedido no se pudo crear (por ejemplo, el módulo está desactivado). Khipu vuelve a enviar la notificación. El motivo está en el registro.

El pedido está en Khipu payment on hold: lee las notas del bloque Khipu payment. 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": falta la API key o es incorrecta. Revisa las claves en tu cuenta de Khipu.

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

Desinstalación

Ve a Modules > Module Manager, abre el menú junto a VibeFox Khipu Gateway 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 de la pasarela y el registro. Si está desactivado, todos los ajustes se conservan para una reinstalación posterior. Los intentos de pago de Khipu y el estado de pedido Khipu payment on hold siempre se conservan. Los pedidos existentes conservan sus notas de pago y sus ID de transacción.

Khipu es una marca registrada de su respectivo titular. Este módulo no está afiliado ni respaldado por Khipu.