VibeFox Khipu for OpenCart — Ayuda

Requisitos

OpenCart: 3.0.x (probado en 3.0.5.0) o 4.0.2 y posteriores (probado en 4.1.0.3).

PHP: 8.0 o posterior.

Moneda: peso chileno (CLP), peso argentino (ARS) o sol peruano (PEN). La moneda debe existir en System > Localisation > Currencies. Khipu solo se ofrece mientras el cliente paga en una de estas monedas; para otras monedas, el método de pago se oculta en la compra.

Cuenta de Khipu: necesitas el Receiver ID («Id de cobrador»), la API key y la secret key de tu cuenta de cobro de Khipu. Los encuentras en tu cuenta de Khipu, en el perfil de comerciante (khipu.com/merchant/profile). Los tres son obligatorios: sin ellos Khipu no se ofrece en la compra, y sin la secret key no se puede confirmar ningún pago. No hace falta 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 solo dominio.

Instalación

La descarga es un único archivo zip con los paquetes para ambas versiones de OpenCart. Descomprímelo en tu ordenador. Contiene README.txt, el paquete de OpenCart 3 wcp_khipu_gateway-oc3-(version).ocmod.zip y el paquete de OpenCart 4 wcp_khipu_gateway.ocmod.zip. Instala solo el paquete de tu versión de OpenCart. La clave de licencia es la misma para ambas versiones.

OpenCart 3

1. En el panel de administración ve a Extensions > Installer, haz clic en Upload y elige el archivo wcp_khipu_gateway-oc3-(version).ocmod.zip. La extensión no tiene modificaciones OCMOD, así que Extensions > Modifications no necesita actualizarse. En lugar del instalador, también puedes copiar el contenido de la carpeta upload de este paquete en la carpeta raíz de tu tienda.

2. Ve a Extensions > Extensions y elige el tipo Payments. Busca VibeFox Khipu Gateway y haz clic en Install (el botón verde +). Tu usuario de administración necesita el permiso para modificar la lista de extensiones de pago.

3. Haz clic en Edit (el botón del lápiz) para abrir la página de configuración. Pega tu clave de licencia de VibeFox en License key, en el bloque de licencia de la parte superior de la página, y haz clic en Activate (ver License key).

4. Introduce el Receiver ID, la API key y la Secret key de tu cuenta de cobro de Khipu (ver Configuration).

5. Activa Enable / Disable y haz clic en Save. 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.

OpenCart 4

1. En el panel de administración ve a Extensions > Installer, haz clic en Upload y elige el archivo wcp_khipu_gateway.ocmod.zip. No cambies el nombre del archivo: OpenCart 4 toma el código de la extensión del nombre del archivo, y un paquete renombrado no funciona.

2. El paquete aparece en la lista de extensiones instaladas en la misma página. Haz clic en Install (el botón verde +) junto a él.

3. Ve a Extensions > Extensions y elige el tipo Payments. Busca VibeFox Khipu Gateway, haz clic en Install (el botón verde +) y luego en Edit (el botón del lápiz).

4. Introduce la clave de licencia y las claves de Khipu como en los pasos 3 a 5 de OpenCart 3. La página de configuración y sus campos son los mismos en ambas versiones. Solo la URL de notificación es distinta (consulta Notificaciones de pago).

Una instalación nueva empieza con el método de pago desactivado.

Configuración

Todos los ajustes están en la página de la extensión: Extensions > Extensions > Payments > VibeFox Khipu Gateway > Edit. Las secciones aparecen a la izquierda; el botón Save situado debajo de la lista guarda toda la página. Encima de los ajustes, 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 compra) y cuando la moneda predeterminada de la tienda no es compatible con Khipu (Khipu entonces solo se ofrece mientras el cliente paga en CLP, ARS o PEN). Sin permiso para modificar la extensión, la página muestra los ajustes pero no permite guardarlos.

Al guardar, Title no puede estar vacío ni tener más de 128 caracteres, Sort Order debe ser un número entero, Total debe ser un número igual o mayor que 0, y la zona geográfica y los estados de pedido deben existir. Si no, no se guarda nada y la página indica el campo. Las claves que falten no impiden guardar.

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 ve el cliente en la compra. También es el nombre del método de pago que se guarda en el pedido. Predeterminado: Khipu. Obligatorio, de 1 a 128 caracteres.

Description: el texto que se muestra al cliente en el paso Confirm Order, encima del botón de confirmar. Predeterminado: Paga por transferencia bancaria con Khipu.

Sort Order: la posición de Khipu entre los métodos de pago de la compra. Déjalo vacío o introduce un número entero.

Geo Zone: ofrece Khipu solo para direcciones de pago de la zona geográfica seleccionada. Predeterminado: All zones. Las zonas geográficas se configuran en System > Localisation > Geo Zones.

Total: el total de la compra, en la moneda predeterminada de la tienda, que debe alcanzar un pedido para que se ofrezca Khipu. Déjalo vacío para ofrecer Khipu con cualquier total.

Cuenta de Khipu

Copia el Receiver ID, la API key y la secret key de tu cuenta de cobro de Khipu (la sección enlaza a khipu.com/merchant/profile). Khipu no tiene un servidor sandbox independiente y la extensión no tiene un interruptor de modo de prueba. Para probar, usa las claves de una cuenta de cobro de desarrollador («desarrollo»): paga con el banco de pruebas DemoBank y no se mueve dinero real. Cambia a las claves de tu cuenta de cobro de producción cuando vayas a funcionar en real.

Receiver ID: tu ID de receptor («cobrador») de Khipu. Se rechazan los pagos de otras cuentas de Khipu.

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 cambiarlo. Para eliminar una clave guardada, marca Clear the saved value debajo del campo y haz clic en Save.

Notificaciones de pago

Notification URL: Khipu confirma los pagos llamando a la URL que se muestra aquí. En OpenCart 3 tiene el formato https://your-store/index.php?route=extension/payment/wcp_khipu_gateway/webhook y en OpenCart 4, https://your-store/index.php?route=extension/wcp_khipu_gateway/payment/wcp_khipu_gateway.webhook; se genera a partir de la dirección de la tienda de tu instalación de OpenCart. La URL se envía automáticamente con cada pago, así que no hay que configurar nada 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. La extensión nunca se fía del 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 que recibe el pedido cuando Khipu confirma el pago. El estado se asigna de inmediato, con un único cambio de estado.

OpenCart crea el pedido en el paso Confirm Order sin estado (un pedido incompleto). Recibe un estado solo después de que Khipu haya confirmado el pago. Cada campo siguiente muestra tus estados de pedido de OpenCart.

Paid Order Status: el estado tras un pago confirmado cuando Status after payment es Processing. Predeterminado: Procesando.

Complete Order Status: el estado tras un pago confirmado cuando Status after payment es Completed. Predeterminado: Completado.

On Hold (Review) Status: los pagos cuyo importe o moneda no coinciden con el pedido, o que llegan después de que el pedido se cancelara, reciben este estado y una nota que explica el motivo. Predeterminado: Pendiente de pago, porque OpenCart no tiene un estado «En espera». Puedes crear tu propio estado en System > Localisation > Order Statuses y seleccionarlo aquí.

Avanzado

Debug log: registra las llamadas a la API y las notificaciones en wc_khp_debug.log.php, en la carpeta de registros de OpenCart (storage/logs). El archivo no se puede abrir desde la web, y al llegar a 5 MB se traslada a wc_khp_debug.old.log.php. Los errores siempre se registran, incluso con el interruptor desactivado. Las claves y los datos del pagador nunca se escriben. Predeterminado: desactivado.

Log: muestra el tamaño y las entradas más recientes del registro. Haz clic en Clear log para vaciarlo.

Delete data on uninstall: si está activado, al desinstalar la extensión 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.

Importar / Exportar

Export: Download JSON guarda los ajustes en un archivo JSON. La API key y la secret key no se exportan.

Import: pega un JSON exportado previamente y haz clic en Import para restaurar los ajustes. La API key y la secret key guardadas se conservan.

Compra

En el paso Payment Method el cliente elige el método de pago (por defecto Khipu). En el paso Confirm Order el cliente ve tu descripción encima del botón de confirmar. OpenCart crea el pedido en este paso, todavía sin estado. Cuando el cliente hace clic en Confirm Order, la extensión crea un pago de Khipu por el total del pedido en la moneda del pedido y envía al cliente a la página de pago de Khipu. En Khipu, el pago aparece como Order # con el número del pedido y el nombre de la tienda, junto con la lista de productos. El correo electrónico del cliente se envía a Khipu cuando es válido. En la página de Khipu, el cliente paga mediante transferencia bancaria desde su propio banco.

En OpenCart 4, el cliente elige el método de pago con el botón Choose del bloque del método de pago, en la ventana Payment method options, y hace clic en Confirm Order al final de la página de finalización de compra.

Tras 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. Después, el pedido recibe su estado de la forma estándar de OpenCart, con los correos habituales del pedido y la actualización del stock, y el cliente ve la página de éxito de pedido de OpenCart. Si el banco todavía está verificando la transferencia o no se puede contactar con Khipu, aparece una página de Payment confirmation con el texto Khipu is confirming your bank transfer. Your order will be confirmed 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 pedido no se puede asociar a él (por ejemplo, porque pertenece a otro Receiver ID), el cliente vuelve a la compra con el mensaje We could not match this payment to an order. If you paid, please contact us.

Si el cliente cancela en la página de Khipu, o el pago no se completó, el cliente vuelve a la compra con el mensaje The Khipu payment was not completed. You can try again or choose another payment method. El carrito se conserva. En OpenCart 4 estos mensajes se muestran encima de la página de finalización de compra. Cada nuevo intento (OpenCart 3 crea un pedido nuevo cada vez que se muestra el paso Confirm Order; OpenCart 4 actualiza el pedido de la compra y lo paga con un nuevo pago de Khipu) elimina el pago de Khipu sin pagar anterior del pedido o del carrito, así que el enlace antiguo ya no se puede pagar. Si Khipu ya recibió el pago anterior, se aplica y el cliente va a la página de éxito, sin ningún pago nuevo. Si la transferencia anterior todavía la está verificando el banco, 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 el pago anterior está en revisión, se pide al cliente que contacte con la tienda antes de volver a pagar. Un cambio en el carrito, incluida una nueva cantidad, cuenta como un carrito nuevo que necesita su propio pago.

OpenCart 4 mantiene el pedido en la finalización de compra hasta que se muestra la página de éxito. Si ese pedido se ha cerrado sin pago mientras tanto (por ejemplo, lo has cancelado), el cliente vuelve a la finalización de compra con Your previous order was cancelled without a payment. Please confirm the order again to pay with a new order. Si el pedido ya está realizado y el carrito ha cambiado desde entonces, el mensaje es Your previous order has already been placed. Your cart has changed since — please confirm the order again to pay for the current cart with a new order. En ambos casos, el siguiente Confirm Order paga un nuevo pedido del carrito.

Si Khipu no puede crear el pago, el cliente se queda en el paso Confirm Order con un mensaje breve encima del botón, 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 también funciona mientras la tienda está en modo de mantenimiento: OpenCart 3 deja pasar las peticiones de las extensiones de pago, y en OpenCart 4 la extensión añade una acción de inicio que deja pasar la notificación y el regreso del cliente.

La extensión solo admite pagos únicos mediante transferencia bancaria. Los reembolsos no se envían a Khipu desde OpenCart, y no hay suscripciones, métodos de pago guardados ni preautorizaciones. Los pagos sin completar no están ligados a una reserva de stock.

Pedidos

Estados de pedido

Sin estado (pedido incompleto): el cliente fue enviado a Khipu y no ha pagado, o Khipu todavía no ha confirmado la transferencia. En Sales > Orders estos pedidos solo se muestran con el filtro Order Status en Missing Orders.

Paid Order Status o Complete Order Status (predeterminado Procesando o Completado): Khipu confirmó el pago. El estado sigue a Status after payment. Una nota muestra Khipu payment verified. Payment ID: con el ID del pago y el importe.

On Hold (Review) Status (predeterminado Pendiente de pago): Khipu confirmó un pago cuyo importe o moneda no coincide con el pedido, o el pago llegó después de que el pedido se cancelara o rechazara. Una nota lo explica. Revisa el pago en tu cuenta de Khipu y después completa el pedido o reembolsa al cliente. Si más tarde llega un pago del importe correcto para el mismo pedido, el pedido pasa al estado de pagado y el cliente recibe un correo electrónico. Si el pago llega después de que el pedido se haya pasado a otro estado de procesamiento, el estado no cambia y solo se añade una nota.

Si llega un pago para un pedido que ya está pagado, o para otro pedido de un carrito que ya está pagado, el pedido no cambia. Una nota te pide que lo reembolses al cliente si se trata de un segundo pago. Si Khipu informa de que un pago pagado ha sido revertido, el pedido recibe una nota y su estado no cambia.

Las notas son entradas del History del pedido que el cliente no ve. Empiezan con la palabra Khipu.

Pestaña VibeFox Khipu Gateway

En Sales > Orders abre un pedido pagado con Khipu. En la parte inferior de la página del pedido, junto a History y Additional, la pestaña VibeFox Khipu Gateway muestra los intentos de pago de Khipu del pedido (fecha, importe, ID del pago de Khipu, estado y resultado en Khipu), un aviso Manual review mientras el pedido está en el estado de revisión, y las Khipu notes del pedido. La pestaña es solo de lectura y se muestra a los usuarios que tienen acceso a la extensión.

Reembolsos

Los reembolsos no se envían a Khipu desde OpenCart, porque Khipu no ofrece ningún reembolso a través de su API. La pestaña lo indica. Reembolsa al cliente desde tu cuenta de Khipu o mediante transferencia bancaria, y después cambia manualmente el estado del pedido en OpenCart.

Clave de licencia

La extensión funciona con una clave de licencia de VibeFox de vibefox.net. El bloque de licencia License — VibeFox Khipu Gateway es el primer bloque de Extensions > Extensions > Payments > VibeFox Khipu Gateway > Edit, encima de los ajustes. Pega 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 comprobar el estado de nuevo, Change key para introducir otra clave y Remove key para eliminar la clave de esta tienda. Debajo aparecen la línea Product: opencart-payment-khipu y el enlace Manage licenses and domains in your account, que abre tu cuenta de vibefox.net. Solo los usuarios administradores con el permiso Modify para la extensión pueden cambiar la clave. Los textos del bloque siguen el idioma del panel de administración (se incluyen inglés y 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. Tras cambiar la dirección de la tienda, o después de liberar una plaza de dominio en tu cuenta, haz clic en Check now. Si el servidor de licencias no responde, la extensión sigue funcionando con el último estado conocido.

Una clave funciona en un solo dominio: la dirección de la tienda de la configuración de OpenCart. Eliminar la clave de la tienda no libera su plaza de dominio. Libérala en tu cuenta de vibefox.net.

Sin una clave activa, Khipu no se muestra a los clientes en la compra. Si aun así se inicia un pago, el cliente ve This payment method is not available. Please choose another one. Un usuario administrador que tenga la sesión iniciada en el panel en el mismo navegador sigue viendo el método de pago en la tienda, marcado como (unlicensed — visible to admins only), para que puedas configurar y probar la extensión antes de comprar una clave. En OpenCart 4 esta vista previa no está disponible: la tienda no ve el inicio de sesión del administrador, así que, sin una clave activa, el método de pago se oculta para todos. Después de abrir la página Edit una vez, aparece un recordatorio en el Dashboard del panel. Ciérralo con × para ocultarlo durante 7 días. Los pedidos existentes no se ven afectados: los pagos ya iniciados se siguen confirmando.

Cuando una licencia caduca, la extensión sigue funcionando, pero las actualizaciones y el soporte requieren una renovación. El estado se vuelve a comprobar automáticamente al abrir el Dashboard o la página Edit del panel: una vez al día durante los primeros 14 días tras introducir la clave, y después una vez por semana. No hace falta ningún cron job. Desinstalar la extensión siempre elimina la clave de licencia y el estado de la licencia.

Solución de problemas

Khipu no aparece en la 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. El cliente debe pagar en CLP, ARS o PEN. La página de ajustes muestra un aviso cuando falta algo. Comprueba también que la dirección de pago esté en la Geo Zone seleccionada y que el pedido alcance el Total configurado.

El pago se realizó, pero el pedido se queda sin estado: Khipu confirma una transferencia cuando el banco la ha verificado. El pedido recibe su estado 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 de la extensión.

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 o Malformed signature: la Secret key no pertenece a la cuenta de cobro cuyas claves usas, o la petición no procedía de Khipu.

La notificación responde Order not found, Payment not found for this account o Payment does not belong to this order: el pago se hizo a otro Receiver ID, con otras claves o para otro pedido. Revisa el Receiver ID y las claves.

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

La notificación responde Busy, retry later o Order could not be updated, retry later: el pedido estaba siendo confirmado por otra petición en el mismo momento, o no se pudo asignar el estado del pedido. Khipu vuelve a enviar la notificación. El motivo está en el registro.

El pedido está en el estado de revisión tras el pago: lee las notas de la pestaña VibeFox Khipu Gateway. 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 API key falta o es incorrecta. Revisa las claves en tu cuenta de Khipu.

Para desarrolladores: la extensión dispara los eventos de OpenCart wc_khp_supported_currencies (para añadir una moneda que acepte tu cuenta de Khipu, por ejemplo EUR para Khipu España), wc_khp_currency_decimals y wc_khp_payment_data.

Desinstalación

Ve a Extensions > Extensions, elige el tipo Payments y haz clic en Uninstall (el botón rojo −) junto a VibeFox Khipu Gateway. La clave de licencia y el estado de la licencia de esta extensión siempre se eliminan. OpenCart siempre elimina sus propios ajustes de la extensión: Enable / Disable, Sort Order, Geo Zone, Total y los tres estados de pedido, que vuelven a sus valores predeterminados al reinstalar. En OpenCart 4 se eliminan además su evento y su acción de inicio, que deja pasar la notificación y el regreso del cliente en modo de mantenimiento. Si Delete data on uninstall está activado, se eliminan los demás ajustes de la pasarela (título, descripción, Receiver ID, claves, estado tras el pago, registro de depuración) y el registro. Si está desactivado, se conservan para una reinstalación posterior. Los intentos de pago de Khipu siempre se conservan, así que las notificaciones tardías de pedidos pagados antes siguen gestionándose tras reinstalar. Los pedidos existentes conservan sus notas de pago.

En OpenCart 4, para eliminar también los archivos de la extensión, ve a Extensions > Installer después de la desinstalación y haz clic en Uninstall (el botón naranja −) junto a VibeFox Khipu Gateway en la lista de extensiones instaladas; después, haz clic en Delete (el botón rojo de papelera) para eliminar el paquete subido.

Khipu es una marca comercial de su respectivo titular. Esta extensión no está afiliada a Khipu ni cuenta con su aprobación.