VibeFox KOMOJU for WooCommerce — Ayuda
Requisitos
WordPress: 6.0 o posterior.
WooCommerce: 7.0 o posterior, instalado y activo. El plugin no se activa sin él.
PHP: 8.0 o posterior.
HTTPS: tu sitio necesita HTTPS y KOMOJU debe poder acceder a la URL del webhook.
KOMOJU account: necesitas la clave secreta (sk_live_... y, para pruebas, sk_test_...) y el token secreto de un webhook creado en el panel de KOMOJU (consulta Configuración). No se necesita la clave publicable.
Store currency: JPY, USD, EUR, TWD, KRW, PLN, GBP, HKD, SGD, NZD, AUD, IDR, MYR, PHP, THB, CNY, BRL, CHF, CAD o VND. Para otras monedas se oculta el método de pago.
VibeFox license key: comprada en vibefox.net. Una clave funciona en un dominio.
Instalación
1. En WordPress ve a Plugins > Add New > Upload Plugin, elige el ZIP del plugin y haz clic en Install Now. También puedes subir la carpeta wcp_komoju_payment a /wp-content/plugins/ por FTP.
2. Haz clic en Activate.
3. Abre los ajustes: WooCommerce > Settings > Payments > KOMOJU Payment > Manage, o haz clic en Settings bajo el 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 y haz clic en Activate.
5. En el panel de KOMOJU añade un webhook con la URL y los eventos de la página de ajustes y copia su token secreto (consulta Configuración).
6. Introduce la clave secreta y el token secreto del webhook de producción, y los de prueba para el modo sandbox. Activa Enable/Disable y guarda.
Configuración
Todos los ajustes están en una página: WooCommerce > Settings > Payments > KOMOJU Payment. Encima de los campos aparece KOMOJU Sandbox Mode is enabled. mientras el modo de prueba está activo. Te avisa si al modo actual le falta la clave secreta (el método se oculta en la finalización de compra) o el token secreto de webhook (se rechazan las notificaciones de KOMOJU, por lo que nunca se confirman los pagos konbini y por transferencia bancaria), y si la moneda de la tienda no es compatible. En la lista de métodos de pago, KOMOJU aparece pendiente de configuración hasta que el modo actual tenga clave secreta y muestra una insignia de prueba mientras sandbox está activo.
General
Enable/Disable: Enable KOMOJU Payment Gateway activa o desactiva el método de pago. Predeterminado: off.
Title: nombre del método que ven los clientes al finalizar la compra. Predeterminado: KOMOJU Payment.
Description: texto bajo el método al finalizar la 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
Busca las claves en el panel de KOMOJU: la clave secreta en Settings > API keys, el token secreto del webhook en Settings > Webhooks (añade antes allí la URL del webhook indicada abajo).
Live Secret Key: tu clave secreta de producción de KOMOJU. Empieza por sk_live_.
Live Webhook Secret Token: token secreto del webhook de producción. Verifica la firma de cada notificación.
Modo de prueba
KOMOJU usa la misma dirección API para pagos de prueba y producción: la clave determina el modo. Los pedidos conservan el modo en que se pagaron, por lo que sus reembolsos y comprobaciones de estado siempre usan la clave de ese modo.
Sandbox Mode: Enable test mode (use the test keys below, no real payments). Predeterminado: off. Mientras está activo, 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: token secreto del webhook de prueba.
URL del webhook
El webhook informa a tu tienda de los pagos, incluidos los pagos diferidos konbini y por transferencia bancaria. En el panel de KOMOJU, en Settings > Webhooks, añade la URL de esta sección de los ajustes para producción y pruebas. Tiene el formato https://your-site/wc-api/komoju_p_webhook/. Si tu sitio usa un prefijo de idioma en las URL, copia la URL exactamente como aparece en los ajustes. Después copia el token secreto de cada webhook en Live Webhook Secret Token o Sandbox Webhook Secret Token.
Selecciona estos eventos:
Los eventos de caducidad, cancelación y fallo solo modifican el pedido para su pago actual, por lo que un pago de un intento anterior no puede cancelar un pedido que se está pagando de otra forma. Se rechazan los webhooks sin firma válida. Se aceptan los firmados con cualquiera de los dos tokens secretos, pero solo para pedidos del mismo modo. Sin webhook, los pagos con tarjeta se confirman al volver el cliente a la tienda, pero los pagos konbini y por transferencia bancaria nunca se confirman.
Avanzado
Invoice Prefix: prefijo de los números de pedido enviados a KOMOJU. Si usas varias tiendas con la misma cuenta de KOMOJU, hazlo único para cada tienda. Predeterminado: WC-.
Enable Logging: Log KOMOJU events and API calls en WooCommerce > Status > Logs, fuente wcp_komoju_payment, sin claves ni datos de clientes. Los errores siempre se registran. Predeterminado: off.
Delete data on uninstall: Delete the gateway settings and logs when the plugin is deleted. Desactivar el plugin nunca elimina nada. Los datos de pedidos (ID de pago de KOMOJU en pedidos) siempre se conservan. Predeterminado: off.
Finalización de compra
El cliente elige el método de pago (por defecto KOMOJU Payment) y realiza el pedido. El plugin crea una sesión de pago de KOMOJU por el total del pedido en su moneda y envía al cliente a la página de pago de KOMOJU. Se transmiten a KOMOJU el correo de facturación, el nombre, las direcciones de facturación y envío y los artículos del pedido. La página se muestra en japonés, inglés o coreano según el idioma del sitio (inglés para los demás idiomas). Allí el cliente elige un método de pago. Los métodos disponibles dependen de tu cuenta de KOMOJU y de la moneda del pedido.
Tras pagar, el cliente vuelve a tu tienda. El plugin consulta la sesión de pago en la API de KOMOJU con la clave del modo del pedido. El pedido solo se marca como pagado cuando KOMOJU lo confirma: mediante el webhook firmado o la consulta de la sesión al regresar el cliente. Si no se puede contactar con KOMOJU en ese momento, el cliente llega a la página de pedido recibido con 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.
Para pagos konbini y por transferencia bancaria, el cliente recibe un documento. El pedido queda en espera y se completa cuando el cliente paga y KOMOJU envía el webhook. Si caduca el documento, se cancela el pedido.
Si el pago no se completó, el cliente vuelve a Pay for order con The payment was not completed. You can try again or choose another payment method. Un nuevo intento reutiliza la sesión abierta de KOMOJU si el total no ha cambiado. Una sesión con un total antiguo se cancela en KOMOJU y una sesión pagada entretanto confirma el pedido. Cuando se cancela un pedido impagado (por ti, por el cliente o por el temporizador de reserva de existencias de WooCommerce), también se cancela su sesión abierta de KOMOJU para que ya no pueda pagarse.
Si KOMOJU no puede iniciar el pago, el cliente ve 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. Los detalles se añaden a las notas del pedido y al registro.
El método funciona en la finalización de compra clásica, en el bloque de Finalizar compra y en Pay for order. Es compatible con WooCommerce High-Performance Order Storage (HPOS).
El plugin 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 queda en espera hasta entonces.
Pedidos y reembolsos
Estados del pedido
Pending payment: el cliente fue enviado a KOMOJU y aún no ha pagado, o KOMOJU aún no ha confirmado el pago.
Processing or Completed: KOMOJU confirmó el pago. WooCommerce establece el estado habitual de un pedido pagado. La nota muestra el ID de pago de KOMOJU, el método de pago y cómo se confirmó (webhook o regreso). El ID de transacción es el ID de pago de KOMOJU y, en la pantalla del pedido, enlaza al pago en el panel de KOMOJU.
On hold: se emitió un documento konbini o de transferencia bancaria y espera el pago, o un pago espera su captura en el panel de KOMOJU. El pedido también queda en espera si el importe o la moneda no coinciden con el pedido, o si se capturó un pago tras cancelarse el pedido. La nota lo explica. Tramita el pedido o reembolsa el pago.
Failed: el pago falló. El cliente puede volver a intentarlo.
Cancelled: el documento caducó o el pago se canceló.
Refunded: el pago se reembolsó íntegramente desde WooCommerce o en el panel de KOMOJU.
Si se captura un segundo pago para un pedido ya pagado, el pedido no vuelve a modificarse. Una nota te pide reembolsarlo en el panel de KOMOJU si está duplicado. Los pedidos reembolsados nunca se reabren.
Reembolsos
Abre el pedido, haz clic en Refund, introduce el importe y haz clic en Refund via KOMOJU Payment. Se admiten reembolsos totales y parciales. El reembolso se envía con la clave del modo en que se pagó el pedido, por lo que debe estar configurada su clave secreta. El plugin comprueba antes el pago en KOMOJU y rechaza reembolsos superiores al importe aún reembolsable. Si KOMOJU no puede reembolsar automáticamente un pago (algunos métodos, como konbini, necesitan los datos bancarios del cliente), se muestra su mensaje de error y no se registra nada: gestiona esos reembolsos en el panel de KOMOJU. Un reembolso solo se considera realizado cuando KOMOJU lo confirma. Un reembolso correcto se añade a las notas del pedido.
Para pagos que KOMOJU convirtió a otra moneda (por ejemplo konbini en JPY para un pedido en EUR), solo se puede hacer un reembolso total desde WooCommerce. Realiza los parciales en el panel de KOMOJU.
Los reembolsos del panel de KOMOJU llegan por webhook y se registran automáticamente como reembolsos de WooCommerce. Un reembolso total pone el pedido en Reembolsado. Los reembolsos parciales del panel para pagos convertidos a otra moneda solo se anotan en el pedido: registra el importe correspondiente en WooCommerce con "Refund manually".
Clave de licencia
El plugin funciona con una clave de licencia de VibeFox de vibefox.net. El bloque de licencia está arriba de WooCommerce > Settings > Payments > KOMOJU Payment. Pega la clave en License key y haz clic en Activate. El bloque muestra el estado, por ejemplo la fecha hasta la que está activa la licencia y tu dominio. Usa Check now para volver a comprobarlo, 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. Quitarla de un sitio 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 al finalizar la compra. Si aun así se inicia un pago, el cliente ve This payment method is not available. Please choose another one. Los gestores de tienda con sesión iniciada siguen viendo el método, 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 de plugins y en las páginas de WooCommerce. Los pedidos existentes no se ven afectados: los pagos ya iniciados siguen confirmándose y los reembolsos funcionan.
Cuando caduca una licencia, 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
KOMOJU no aparece al finalizar la compra: comprueba que la licencia esté activa, que Enable/Disable esté activado y que el modo actual tenga clave secreta: Sandbox Secret Key en sandbox, Live Secret Key en producción. KOMOJU debe admitir la moneda de la tienda. Los ajustes muestran un aviso si falta algo.
El pago se realizó, pero el pedido sigue Pending payment: el webhook no funciona. En el panel de KOMOJU comprueba que exista para el modo utilizado, que su URL sea exactamente la de los ajustes y que estén seleccionados los eventos. Comprueba su token secreto en el campo correspondiente (Live Webhook Secret Token o Sandbox Webhook Secret Token) y consulta WooCommerce > Status > Logs, fuente wcp_komoju_payment. Los pagos con tarjeta también se confirman al regresar el cliente a la tienda, pero los pagos konbini y por transferencia bancaria solo mediante 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: se firmó con el token secreto de un modo distinto al del pago del pedido. Usa webhooks y tokens separados para producción y pruebas.
El webhook responde Order is busy, retry later o Temporary error, retry later: otra solicitud estaba actualizando el pedido o no se pudo comprobar el pago en ese momento. KOMOJU reintenta la notificación.
El pedido está On hold: lee la nota del pedido. Un documento espera el pago, un pago espera captura en el panel de KOMOJU, el importe o la moneda no coincidieron, o el pago llegó tras cancelarse el pedido.
El reembolso falla: lee el mensaje. Puede faltar la clave secreta del modo del pago, el pago puede no admitir reembolso automático (reembólsalo en el panel de KOMOJU) o un pago convertido puede admitir solo reembolso total.
El bloque de licencia muestra un error: sigue su mensaje. 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 en el nuevo dominio. Si no se puede contactar con el servidor de licencias, el plugin sigue funcionando con el último estado conocido.
Los desarrolladores pueden modificar la lista de monedas con el filtro komoju_p_supported_currencies y la sesión de pago, por ejemplo los métodos de pago, con el filtro komoju_p_session_params.
Desinstalación
Desactivar el plugin conserva todos los datos. Para eliminarlo, desactívalo y bórralo en Plugins. La clave 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. De lo contrario se conservan para una reinstalación. Los pedidos existentes conservan sus notas de pago e ID de transacción.
KOMOJU es una marca comercial de su respectivo propietario. Este plugin no está afiliado a KOMOJU ni cuenta con su respaldo.