VibeFox KOMOJU for PrestaShop — Ayuda
Requisitos
PrestaShop: 8.0 a 9.x.
PHP: 8.0 o posterior. El módulo no se instala en versiones anteriores de PHP.
Cuenta de KOMOJU: necesitas la clave secreta (sk_live_... y, para el modo de prueba, sk_test_...) y el token secreto de un webhook creado en el panel de KOMOJU (consulta Configuración). La clave publicable no es necesaria. KOMOJU debe poder acceder a la URL del webhook de tu tienda.
Moneda del carrito: JPY, USD, EUR, TWD, KRW, PLN, GBP, HKD, SGD, NZD, AUD, IDR, MYR, PHP, THB, CNY, BRL, CHF, CAD o VND. Para carritos en otras monedas el método de pago se oculta.
Clave de licencia de VibeFox: se compra en vibefox.net. Una clave funciona en un solo 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 carga, haz clic en Configure, o busca más tarde VibeFox KOMOJU Payment en la lista de módulos y haz clic en Configure.
3. Introduce tu clave de licencia de VibeFox en License key, en el bloque de licencia de la parte superior de la página de configuración, y haz clic en Activate (ver Clave de licencia).
4. En el panel de KOMOJU añade un webhook con la URL y los eventos que se indican en la sección Webhook URL, y copia su token secreto (consulta Configuración).
5. Introduce la clave secreta de producción y el token secreto del webhook de producción, y los de prueba para el modo de prueba. Activa Enable/Disable y haz clic en Save.
Al instalarse, el módulo crea dos estados de pedido: Awaiting KOMOJU payment y KOMOJU payment on hold. PrestaShop asigna un nuevo módulo de pago solo a los países activos en ese momento: un país que actives más tarde debe marcarse para el módulo en Payment > Preferences. Allí también puedes limitar las monedas y los grupos de clientes.
Configuración
Todos los ajustes están en la página del módulo: Modules > Module Manager > VibeFox KOMOJU Payment > Configure. Cada sección tiene su propio botón Save, que guarda toda la página. Encima de los campos, la página muestra KOMOJU Sandbox Mode is enabled. mientras el modo de prueba está activado. Avisa cuando el modo actual no tiene clave secreta (en ese caso el método de pago se oculta en la finalización de compra) o no tiene token secreto de webhook (las notificaciones de KOMOJU se rechazan y, por tanto, los pagos con konbini y transferencia bancaria nunca se confirman), y cuando KOMOJU no admite la moneda predeterminada de la tienda (en ese caso el método de pago se oculta para los carritos en esa moneda).
Pago KOMOJU
Enable/Disable: Enable KOMOJU Payment Gateway 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 que se guarda en el pedido. Predeterminado: KOMOJU Payment.
Description: el texto que se muestra debajo del método de pago en la finalización de compra. Predeterminado: Pay securely on the KOMOJU payment page: credit card, convenience store (konbini), PayPay, bank transfer and other local payment methods.
Claves API de producción
Encuentra las claves en el panel de KOMOJU: la clave secreta en Settings > API keys, y el token secreto del webhook en Settings > Webhooks (añade antes allí la URL del webhook que se muestra en la sección Webhook URL).
Live Secret Key: tu clave secreta de KOMOJU de producción. Empieza por sk_live_.
Live Webhook Secret Token: el token secreto del webhook de producción. Se usa para verificar la firma de cada notificación.
Modo de prueba
KOMOJU usa la misma dirección de API para los pagos de prueba y de producción: lo que decide es la clave. Los pagos conservan el modo en el que se hicieron, así que los reembolsos y las comprobaciones de estado de un pedido siempre usan la clave de ese modo.
Sandbox Mode: Enable test mode (use the test keys below, no real payments). Predeterminado: desactivado. Mientras está activado, la finalización de compra muestra Test mode encima de la descripción.
Sandbox Secret Key: tu clave secreta de prueba de KOMOJU. Empieza por sk_test_.
Sandbox Webhook Secret Token: el token secreto del webhook del modo de prueba.
Las claves y los tokens guardados ya no se muestran. El campo queda vacío y muestra Saved — leave empty to keep it. Escribe un valor nuevo solo si quieres cambiarlo.
Borrar secretos guardados: marca una clave o un token y haz clic en Save para eliminarlo. Un campo vacío conserva el valor guardado.
URL del webhook
El webhook informa a tu tienda sobre los pagos, incluidos los pagos diferidos con konbini y transferencia bancaria. En el panel de KOMOJU, en Settings > Webhooks, añade la URL que se muestra en esta sección, tanto para producción como para el modo de prueba. Con URL amigables tiene este aspecto: https://your-shop/module/wcp_komoju_payment/webhook, posiblemente con un código de idioma como /en/. Copia la URL exactamente como la muestran los ajustes. Después copia el token secreto de cada webhook en Live Webhook Secret Token o en Sandbox Webhook Secret Token.
Selecciona estos eventos (también aparecen en esta sección):
Los eventos de caducidad, cancelación y fallo solo cambian el pedido para su pago actual, así que un pago de un intento anterior no puede cancelar un pedido que se está pagando de otra forma. Los webhooks sin una firma válida se rechazan. Los webhooks firmados con cualquiera de los dos tokens secretos se aceptan, pero solo para pagos del mismo modo. Sin el webhook, los pagos con tarjeta se siguen confirmando cuando el cliente vuelve a la tienda, pero los pagos con konbini y transferencia bancaria nunca se confirman.
Avanzado
Invoice Prefix: el prefijo de los números de pedido que se envían a KOMOJU, seguido del número del carrito. Si usas varias tiendas con la misma cuenta de KOMOJU, haz que sea único para cada tienda. Predeterminado: PS-.
Enable Logging: escribe los eventos de KOMOJU y las llamadas a la API en logs/komoju_p_debug.log.php, en la carpeta del módulo. El archivo no se puede abrir desde la web. Las claves y los datos de los clientes no se registran. Los errores y las advertencias siempre se escriben. 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 pedidos, las transacciones y reembolsos de KOMOJU y los estados de pedido siempre se conservan, así que los pedidos antiguos se pueden seguir confirmando y reembolsando tras una reinstalación. Predeterminado: desactivado.
Finalización de compra
En el paso de pago, el cliente elige el método de pago (de forma predeterminada KOMOJU Payment) y confirma. El módulo crea una sesión de pago de KOMOJU por el total del carrito en la moneda del carrito y envía al cliente a la página de pago de KOMOJU. El correo electrónico, el nombre, las direcciones de facturación y de envío y los artículos del pedido se transfieren a KOMOJU. La página se muestra en japonés, inglés o coreano, según el idioma del carrito (en inglés para los demás idiomas). Allí el cliente elige un método de pago. Los métodos que se ofrecen dependen de tu cuenta de KOMOJU y de la moneda del carrito. En este momento todavía no existe ningún pedido.
Tras pagar, el cliente vuelve a tu tienda. El módulo lee la sesión de pago desde la API de KOMOJU con la clave del modo del pago. El pedido se marca como pagado solo cuando KOMOJU lo confirma: mediante el webhook firmado o mediante la lectura de la sesión cuando el cliente vuelve. Después el pedido se crea y el cliente ve la página estándar de confirmación del pedido con Your payment with KOMOJU has been received. Si en ese momento no se puede contactar con KOMOJU, una página de Payment confirmation muestra We could not confirm the payment status with KOMOJU yet. If you completed the payment, your order will be updated automatically in a few minutes. y un botón Check again.
En los pagos con konbini y transferencia bancaria, el cliente recibe un documento de pago. El pedido se crea en Awaiting KOMOJU payment, y la página de confirmación indica al cliente que complete el pago según las instrucciones de KOMOJU (por ejemplo, en una tienda de conveniencia o mediante transferencia bancaria). El pedido pasa a Payment accepted cuando el cliente paga y KOMOJU envía el webhook. Si el documento caduca o el pago falla más tarde, la página de confirmación muestra Your KOMOJU payment was not completed. Please contact us about this order.
Si el pago no se completó, el cliente vuelve a la finalización de compra con The payment was not completed. You can try again or choose another payment method. El carrito se conserva. Un nuevo intento reutiliza la sesión de KOMOJU abierta si el total no ha cambiado. Una sesión con un total antiguo se cancela en KOMOJU, y una sesión que se pagó entretanto crea el pedido en lugar de un nuevo pago.
Si KOMOJU no puede iniciar el pago, el cliente se queda en la finalización de compra con un mensaje breve, por ejemplo KOMOJU could not accept this payment: con el motivo, KOMOJU payments are temporarily unavailable. Please choose another payment method or contact us. o Payment error: Could not connect to KOMOJU. Please try again in a moment. El motivo técnico se escribe en el registro.
Si un cupón del carrito deja de ser válido entre el pago y su confirmación, PrestaShop lo elimina del pedido. El pedido pasa entonces a KOMOJU payment on hold con una nota, porque el cliente pagó el precio con el descuento.
El webhook funciona mientras la tienda está en modo de mantenimiento y no se bloquea por la restricción de países de tu tienda.
El módulo no tiene formulario de tarjeta en tu sitio, tarjetas guardadas ni suscripciones. No restringe los métodos de pago: se eligen en la página de KOMOJU. No tiene acción de captura manual: los pagos autorizados para captura manual deben capturarse en el panel de KOMOJU, y el pedido permanece en Awaiting KOMOJU payment hasta entonces.
Pedidos y reembolsos
Estados del pedido
No order yet: el cliente fue enviado a KOMOJU y no ha pagado, o KOMOJU aún no ha confirmado el pago. Solo existe el carrito.
Payment accepted: KOMOJU confirmó el pago. El pago se registra con el ID de pago de KOMOJU como ID de transacción, y una nota muestra el ID del pago, el método de pago y cómo se confirmó (webhook o regreso del cliente).
Awaiting KOMOJU payment: se emitió un documento de pago de konbini o transferencia bancaria y espera el pago, o un pago espera la captura en el panel de KOMOJU.
KOMOJU payment on hold: KOMOJU informó de un importe o una moneda distintos del total del pedido (por ejemplo, el carrito se cambió después de iniciar el pago), se eliminó un cupón, o el pago se capturó después de que el pedido se hubiera cancelado. La nota lo explica. Revisa el pedido y procésalo o reembolsa el pago.
Canceled: el documento de pago caducó o el pago se canceló.
Payment error: falló un pago de un pedido existente.
Refunded: el pago se reembolsó por completo, desde la página del pedido o en el panel de KOMOJU.
Si se captura un segundo pago de un pedido que ya está pagado, el pedido no cambia. Una nota te pide que lo reembolses en el panel de KOMOJU si es un duplicado. Los pedidos reembolsados nunca se reabren.
Bloque de pago de KOMOJU
La página del pedido muestra un bloque KOMOJU payment con el ID de pago de KOMOJU (enlazado con el pago en el panel de KOMOJU) y el método de pago, la sesión, el número de pedido en KOMOJU, el estado, el importe pagado y el importe reembolsado, una etiqueta Test mode para los pagos de prueba, el historial de reembolsos y las KOMOJU notes del pedido.
Reembolsos
En el bloque KOMOJU payment introduce el importe (se rellena el importe que aún no se ha reembolsado), opcionalmente un motivo, y haz clic en Refund via KOMOJU. Confirma la pregunta Refund this amount through KOMOJU? This cannot be undone. Se admiten reembolsos totales y parciales. Necesitas el permiso para editar pedidos. Los reembolsos se limitan al importe que KOMOJU cobró realmente, así que tras una discrepancia de importe puedes reembolsar hasta lo que pagó el cliente, no el total del pedido. El reembolso se envía con la clave del modo en el que se hizo el pago, así que debe estar configurada la clave secreta de ese modo. El módulo primero comprueba el pago en KOMOJU y rechaza los reembolsos por encima del importe aún reembolsable. Si KOMOJU no puede reembolsar un pago automáticamente (algunos métodos, por ejemplo konbini, necesitan los datos bancarios del cliente), se muestra el mensaje de error de KOMOJU y no se registra nada: gestiona esos reembolsos en el panel de KOMOJU. Un reembolso se considera hecho solo cuando KOMOJU lo confirma. Un reembolso correcto se añade al historial de reembolsos y a las notas. Un reembolso total pone el pedido en Refunded. Un reembolso parcial no cambia el estado. Los reembolsos están disponibles cuando KOMOJU ha capturado el pago.
En los pagos que KOMOJU convirtió a otra moneda (por ejemplo, konbini en JPY para un carrito en EUR), desde PrestaShop solo es posible un reembolso total. Haz los reembolsos parciales en el panel de KOMOJU.
El módulo no crea notas de crédito. Los botones de reembolso estándar de PrestaShop en la página del pedido no devuelven dinero a través de KOMOJU.
Los reembolsos hechos en el panel de KOMOJU llegan por webhook y se añaden al historial de reembolsos con una nota. Cuando se reembolsa todo el pago, el pedido pasa a Refunded. Los reembolsos parciales hechos en el panel para pagos convertidos a otra moneda solo se anotan en el pedido: registra manualmente en PrestaShop el importe correspondiente (nota de crédito).
Clave de licencia
El módulo funciona con una clave de licencia de VibeFox de vibefox.net. El bloque de licencia License — VibeFox KOMOJU Payment es el primer bloque de Modules > Module Manager > VibeFox KOMOJU Payment > Configure, 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-komoju 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 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. Después de 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 no se puede contactar con el servidor de licencias, el módulo sigue funcionando con el último estado conocido.
Una clave funciona en un solo dominio: el dominio de la tienda principal, también en una configuración multitienda. Quitar la clave de la tienda no libera su plaza de dominio. Libera la plaza en tu cuenta de vibefox.net.
Sin una clave activa, KOMOJU no se muestra a los clientes en la finalización de compra. Si se inicia un pago de todos modos, 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 y los reembolsos funcionan.
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 se necesita ninguna tarea cron. Desinstalar o restablecer el módulo siempre elimina la clave de licencia y el estado de la licencia.
Solución de problemas
KOMOJU no aparece en la finalización de compra: comprueba que la licencia esté activa, que Enable/Disable esté activado y que el modo actual tenga una clave secreta: Sandbox Secret Key en el modo de prueba, Live Secret Key en el modo de producción. La moneda del carrito debe ser compatible con KOMOJU. 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: el webhook no funciona. En el panel de KOMOJU comprueba que el webhook exista para el modo que usas, que su URL sea exactamente la que se muestra en la sección Webhook URL y que los eventos estén seleccionados. Comprueba que su token secreto esté en el campo correspondiente (Live Webhook Secret Token o Sandbox Webhook Secret Token) y revisa el campo Log de la página del módulo. Los pagos con tarjeta también se confirman cuando el cliente vuelve a tu tienda, pero los pagos con konbini y transferencia bancaria solo los confirma el webhook.
El webhook responde Failed to verify KOMOJU webhook signature.: falta el token secreto o pertenece a otro webhook. KOMOJU reintenta la notificación.
El webhook responde Mode mismatch, ignored.: el webhook se firmó con el token secreto del otro modo distinto al del pago. Usa webhooks y tokens separados para producción y para el modo de prueba, y comprueba que no estén intercambiados.
El webhook responde Order is busy, retry later. o Temporary error, retry later.: el pedido se estaba actualizando con otra solicitud, el pedido no se pudo crear en ese momento (por ejemplo, el módulo está desactivado) o no se pudo comprobar el pago. KOMOJU reintenta la notificación. El motivo está en el registro.
La URL del webhook muestra un error en el navegador: es normal. La URL solo acepta solicitudes firmadas de KOMOJU.
El pedido está en KOMOJU payment on hold o Awaiting KOMOJU payment: lee las KOMOJU notes en el bloque del pedido. Un documento de pago espera el pago, un pago espera la captura en el panel de KOMOJU, el importe o la moneda no coincidían, se eliminó un cupón o el pago llegó después de que el pedido se cancelara.
El reembolso falla: lee el mensaje. Puede que falte la clave secreta del modo en el que se hizo el pago, que el pago no se pueda reembolsar automáticamente (reembólsalo en el panel de KOMOJU), que KOMOJU no reconozca el pago con la clave configurada o que para un pago convertido solo sea posible un reembolso total.
Los desarrolladores pueden cambiar la lista de monedas con el hook actionKomojuPSupportedCurrencies y la sesión de pago, por ejemplo los métodos de pago, con el hook actionKomojuPSessionParams.
Desinstalación
Ve a Modules > Module Manager, abre el menú junto a VibeFox KOMOJU Payment 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. Las transacciones y los reembolsos de KOMOJU y los estados de pedido Awaiting KOMOJU payment y KOMOJU payment on hold siempre se conservan, así que los pedidos antiguos se pueden seguir confirmando y reembolsando tras una reinstalación. Los pedidos existentes conservan sus notas de pago y sus ID de transacción.
KOMOJU es una marca comercial de su respectivo propietario. Este módulo no está afiliado a KOMOJU ni cuenta con su respaldo.