VibeFox KOMOJU for WooCommerce — Aide
Prérequis
WordPress: 6.0 ou ultérieur.
WooCommerce: 7.0 ou ultérieur, installé et actif. L’extension refuse de s’activer sans lui.
PHP: 8.0 ou ultérieur.
HTTPS: votre site doit utiliser HTTPS et KOMOJU doit pouvoir joindre l’URL du webhook.
KOMOJU account: il vous faut la clé secrète (sk_live_... et, pour les tests, sk_test_...) et le jeton secret d’un webhook créé dans le tableau de bord KOMOJU (voir Configuration). La clé publiable n’est pas nécessaire.
Store currency: JPY, USD, EUR, TWD, KRW, PLN, GBP, HKD, SGD, NZD, AUD, IDR, MYR, PHP, THB, CNY, BRL, CHF, CAD ou VND. Pour les autres devises, le moyen de paiement est masqué.
VibeFox license key: achetée sur vibefox.net. Une clé fonctionne sur un domaine.
Installation
1. Dans WordPress, ouvrez Plugins > Add New > Upload Plugin, choisissez le ZIP de l’extension et cliquez sur Install Now. Vous pouvez aussi envoyer le dossier wcp_komoju_payment dans /wp-content/plugins/ par FTP.
2. Cliquez sur Activate.
3. Ouvrez les réglages : WooCommerce > Settings > Payments > KOMOJU Payment > Manage, ou cliquez sur Settings sous le nom de l’extension sur la page des extensions.
4. Saisissez votre clé de licence VibeFox dans le bloc de licence en haut de page et cliquez sur Activate.
5. Dans le tableau de bord KOMOJU, ajoutez un webhook avec l’URL et les événements indiqués sur la page des réglages, puis copiez son jeton secret (voir Configuration).
6. Saisissez la clé secrète et le jeton secret de webhook de production, ainsi que ceux de test pour le mode sandbox. Activez Enable/Disable et enregistrez.
Configuration
Tous les réglages sont sur une page : WooCommerce > Settings > Payments > KOMOJU Payment. Au-dessus des champs, KOMOJU Sandbox Mode is enabled. s’affiche en mode test. La page vous avertit si le mode actuel n’a pas de clé secrète (le moyen est alors masqué au paiement) ou de jeton secret de webhook (les notifications KOMOJU sont rejetées et les paiements konbini et par virement ne sont jamais confirmés), ou si la devise de la boutique n’est pas prise en charge. Dans la liste des moyens de paiement, KOMOJU est indiqué comme nécessitant une configuration tant que le mode actuel n’a pas de clé secrète, et affiche un badge de test en mode sandbox.
Général
Enable/Disable: Enable KOMOJU Payment Gateway active ou désactive le moyen de paiement. Par défaut : off.
Title: nom du moyen de paiement visible par le client au paiement. Par défaut : KOMOJU Payment.
Description: texte sous le moyen de paiement. Par défaut : Pay securely on the KOMOJU payment page: credit card, convenience store (konbini), PayPay, bank transfer and other local payment methods.
Clés API de production
Retrouvez les clés dans le tableau de bord KOMOJU : la clé secrète sous Settings > API keys, le jeton secret du webhook sous Settings > Webhooks (ajoutez-y d’abord l’URL du webhook affichée ci-dessous).
Live Secret Key: votre clé secrète KOMOJU de production. Elle commence par sk_live_.
Live Webhook Secret Token: jeton secret du webhook de production. Il vérifie la signature de chaque notification.
Mode test
KOMOJU utilise la même adresse API pour les paiements de test et de production : la clé détermine le mode. Les commandes conservent leur mode de paiement : leurs remboursements et contrôles de statut utilisent toujours la clé de ce mode.
Sandbox Mode: Enable test mode (use the test keys below, no real payments). Par défaut : off. Lorsque ce mode est actif, le paiement affiche Test mode au-dessus de la description.
Sandbox Secret Key: votre clé secrète KOMOJU de test. Elle commence par sk_test_.
Sandbox Webhook Secret Token: jeton secret du webhook de test.
URL du webhook
Le webhook informe votre boutique des paiements, y compris les paiements différés konbini et par virement. Dans le tableau de bord KOMOJU, sous Settings > Webhooks, ajoutez l’URL de cette section des réglages, pour la production et les tests. Elle ressemble à https://your-site/wc-api/komoju_p_webhook/. Si votre site utilise un préfixe de langue dans les URL, copiez exactement celle des réglages. Copiez ensuite le jeton secret de chaque webhook dans Live Webhook Secret Token ou Sandbox Webhook Secret Token.
Sélectionnez ces événements :
Les événements d’expiration, d’annulation et d’échec ne modifient la commande que pour son paiement actuel : un paiement d’une tentative précédente ne peut donc pas annuler une commande en cours de paiement autrement. Les webhooks sans signature valide sont rejetés. Ceux signés avec l’un ou l’autre jeton secret sont acceptés, mais uniquement pour les commandes du même mode. Sans webhook, les paiements par carte sont confirmés au retour du client, mais les paiements konbini et par virement ne le sont jamais.
Avancé
Invoice Prefix: préfixe des numéros de commande envoyés à KOMOJU. Si plusieurs boutiques partagent le même compte KOMOJU, rendez-le unique pour chacune. Par défaut : WC-.
Enable Logging: Log KOMOJU events and API calls dans WooCommerce > Status > Logs, source wcp_komoju_payment, sans clés ni données clients. Les erreurs sont toujours journalisées. Par défaut : off.
Delete data on uninstall: Delete the gateway settings and logs when the plugin is deleted. Désactiver l’extension ne supprime jamais rien. Les données de commande (identifiants de paiement KOMOJU) sont toujours conservées. Par défaut : off.
Paiement
Le client choisit le moyen de paiement (par défaut KOMOJU Payment) et passe commande. L’extension crée une session KOMOJU pour le total dans la devise de la commande et redirige le client vers la page de paiement KOMOJU. L’e-mail de facturation, le nom, les adresses de facturation et de livraison et les articles commandés sont transmis à KOMOJU. La page s’affiche en japonais, anglais ou coréen selon la langue du site (anglais pour les autres langues). Le client y choisit un moyen de paiement. Les moyens proposés dépendent de votre compte KOMOJU et de la devise de la commande.
Après paiement, le client revient dans votre boutique. L’extension lit la session via l’API KOMOJU avec la clé du mode de la commande. La commande n’est marquée payée qu’après confirmation de KOMOJU : webhook signé ou lecture de session au retour du client. Si KOMOJU est alors injoignable, le client arrive sur la page de commande reçue avec 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.
Pour les paiements konbini et par virement, le client reçoit un bordereau. La commande est mise en attente et terminée quand le client paie et que KOMOJU envoie le webhook. Si le bordereau expire, elle est annulée.
Si le paiement n’est pas terminé, le client revient sur Pay for order avec The payment was not completed. You can try again or choose another payment method. Une nouvelle tentative réutilise la session KOMOJU ouverte si le total est inchangé. Une session avec un ancien total est annulée dans KOMOJU ; une session payée entre-temps confirme la commande. Si une commande impayée est annulée (par vous, le client ou le délai de réservation du stock WooCommerce), sa session KOMOJU ouverte est également annulée et ne peut plus être payée.
Si KOMOJU ne peut pas démarrer le paiement, le client voit un bref message, par exemple KOMOJU could not accept this payment: avec la raison, KOMOJU payments are temporarily unavailable. Please choose another payment method or contact us. ou Payment error: Could not connect to KOMOJU. Please try again in a moment. Les détails sont ajoutés aux notes de commande et au journal.
Le moyen de paiement fonctionne sur le paiement classique, le bloc Paiement et la page Pay for order. Il est compatible avec WooCommerce High-Performance Order Storage (HPOS).
L’extension ne propose ni formulaire de carte sur votre site, ni cartes enregistrées, ni abonnements. Elle ne restreint pas les moyens de paiement, choisis sur la page KOMOJU. Elle ne propose pas de capture manuelle : les paiements autorisés pour celle-ci doivent être capturés dans le tableau de bord KOMOJU, et la commande reste en attente jusque-là.
Commandes et remboursements
Statuts des commandes
Pending payment: le client a été redirigé vers KOMOJU et n’a pas encore payé, ou KOMOJU n’a pas encore confirmé le paiement.
Processing or Completed: KOMOJU a confirmé le paiement. WooCommerce attribue le statut habituel d’une commande payée. La note indique l’identifiant de paiement KOMOJU, le moyen et la confirmation (webhook ou retour). L’identifiant de transaction est celui du paiement KOMOJU ; sur l’écran de commande, il renvoie au paiement dans le tableau de bord KOMOJU.
On hold: un bordereau konbini ou de virement a été émis et attend le paiement, ou un paiement attend sa capture dans le tableau de bord KOMOJU. La commande est aussi mise en attente si le montant ou la devise ne correspondent pas, ou si un paiement a été capturé après son annulation. La note l’explique. Honorez la commande ou remboursez le paiement.
Failed: le paiement a échoué. Le client peut réessayer.
Cancelled: le bordereau a expiré ou le paiement a été annulé.
Refunded: le paiement a été intégralement remboursé, depuis WooCommerce ou le tableau de bord KOMOJU.
Si un second paiement est capturé pour une commande déjà payée, celle-ci n’est plus modifiée. Une note vous demande de le rembourser dans le tableau de bord KOMOJU s’il s’agit d’un doublon. Les commandes remboursées ne sont jamais rouvertes.
Remboursements
Ouvrez la commande, cliquez sur Refund, saisissez le montant et cliquez sur Refund via KOMOJU Payment. Les remboursements totaux et partiels sont pris en charge. Le remboursement utilise la clé du mode du paiement initial : sa clé secrète doit être configurée. L’extension vérifie d’abord le paiement dans KOMOJU et refuse les remboursements dépassant le solde remboursable. Si KOMOJU ne peut pas rembourser automatiquement (certains moyens, comme konbini, exigent les coordonnées bancaires du client), son erreur s’affiche et rien n’est enregistré : traitez ces remboursements dans le tableau de bord KOMOJU. Un remboursement n’est considéré effectué qu’après confirmation de KOMOJU. Un remboursement réussi est ajouté aux notes de commande.
Pour les paiements convertis par KOMOJU dans une autre devise (par exemple konbini en JPY pour une commande en EUR), seul un remboursement total est possible depuis WooCommerce. Effectuez les remboursements partiels dans le tableau de bord KOMOJU.
Les remboursements du tableau de bord KOMOJU arrivent par webhook et sont automatiquement enregistrés dans WooCommerce. Un remboursement total passe la commande à Remboursée. Les remboursements partiels du tableau de bord pour des paiements convertis sont seulement notés sur la commande : enregistrez le montant correspondant dans WooCommerce avec "Refund manually".
Clé de licence
L’extension fonctionne avec une clé de licence VibeFox de vibefox.net. Le bloc de licence est en haut de WooCommerce > Settings > Payments > KOMOJU Payment. Collez la clé dans License key et cliquez sur Activate. Le bloc indique le statut, par exemple la date de validité et votre domaine. Utilisez Check now pour revérifier, Change key pour saisir une autre clé et Remove key pour la retirer du site. Le lien Manage licenses and domains in your account ouvre votre compte vibefox.net.
Une clé fonctionne sur un domaine. La retirer du site ne libère pas son emplacement de domaine. Libérez-le dans votre compte vibefox.net.
Sans clé active, KOMOJU est masqué aux clients au paiement. Si un paiement démarre malgré tout, le client voit This payment method is not available. Please choose another one. Les gestionnaires de boutique connectés voient toujours le moyen, marqué (unlicensed — visible to admins only), pour configurer et tester l’extension avant l’achat d’une clé. Un rappel apparaît sur la page des extensions et les pages WooCommerce. Les commandes existantes ne sont pas affectées : les paiements démarrés sont toujours confirmés et les remboursements fonctionnent.
À l’expiration d’une licence, l’extension continue de fonctionner, mais les mises à jour et l’assistance nécessitent un renouvellement. Le statut est revérifié automatiquement en arrière-plan.
Dépannage
KOMOJU n’apparaît pas au paiement : vérifiez la licence active, Enable/Disable activé et la clé secrète du mode actuel : Sandbox Secret Key en sandbox, Live Secret Key en production. La devise doit être prise en charge par KOMOJU. Les réglages signalent les éléments manquants.
Le paiement a abouti, mais la commande reste Pending payment : le webhook ne fonctionne pas. Dans le tableau de bord KOMOJU, vérifiez son existence pour le bon mode, son URL exacte et les événements sélectionnés. Vérifiez son jeton secret dans le bon champ (Live Webhook Secret Token ou Sandbox Webhook Secret Token) et consultez WooCommerce > Status > Logs, source wcp_komoju_payment. Les cartes sont aussi confirmées au retour du client, les paiements konbini et par virement uniquement par webhook.
Le webhook répond Failed to verify KOMOJU webhook signature : le jeton secret manque ou appartient à un autre webhook. KOMOJU réessaie la notification.
Le webhook répond Mode mismatch, ignored : il a été signé avec le jeton de l’autre mode que celui du paiement. Utilisez des webhooks et jetons distincts pour la production et les tests.
Le webhook répond Order is busy, retry later ou Temporary error, retry later : une autre requête modifiait la commande ou le paiement n’a pas pu être vérifié à cet instant. KOMOJU réessaie la notification.
La commande est On hold : lisez sa note. Un bordereau attend le paiement, un paiement attend la capture dans KOMOJU, le montant ou la devise différaient, ou le paiement est arrivé après l’annulation.
Le remboursement échoue : lisez le message. La clé secrète du mode initial peut manquer, le paiement peut ne pas être remboursable automatiquement (remboursez-le dans KOMOJU) ou un paiement converti n’autoriser qu’un remboursement total.
Le bloc de licence affiche une erreur : suivez son message. Si la clé est déjà utilisée sur un autre domaine, libérez un emplacement dans votre compte vibefox.net et cliquez sur Check now. Si l’adresse du site a changé, cliquez sur Check now pour activer la clé sur le nouveau domaine. Si le serveur de licences est injoignable, l’extension conserve le dernier statut connu.
Les développeurs peuvent modifier les devises avec le filtre komoju_p_supported_currencies et la session de paiement, par exemple les moyens proposés, avec komoju_p_session_params.
Désinstallation
La désactivation conserve toutes les données. Pour supprimer l’extension, désactivez-la et supprimez-la sur Plugins. Sa clé et son statut de licence sont toujours supprimés. Les réglages de la passerelle et les journaux ne sont supprimés que si Delete data on uninstall était activé. Sinon, ils restent pour une réinstallation ultérieure. Les commandes existantes conservent leurs notes de paiement et identifiants de transaction.
KOMOJU est une marque de son propriétaire respectif. Cette extension n’est ni affiliée à KOMOJU ni approuvée par KOMOJU.