VibeFox KOMOJU for PrestaShop — Aide

Prérequis

PrestaShop : 8.0 à 9.x.

PHP : 8.0 ou ultérieur. Le module refuse de s’installer sur les versions antérieures de PHP.

Compte KOMOJU : il vous faut la clé secrète (sk_live_... et, pour le mode test, 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. KOMOJU doit pouvoir atteindre l’URL du webhook de votre boutique.

Devise du panier : JPY, USD, EUR, TWD, KRW, PLN, GBP, HKD, SGD, NZD, AUD, IDR, MYR, PHP, THB, CNY, BRL, CHF, CAD ou VND. Pour les paniers dans d’autres devises, le moyen de paiement est masqué.

Clé de licence VibeFox : achetée sur vibefox.net. Une clé fonctionne sur un seul domaine.

Installation

1. Dans le back-office, allez dans Modules > Module Manager et cliquez sur Upload a module. Choisissez le fichier ZIP du module.

2. Une fois le téléversement terminé, cliquez sur Configure, ou retrouvez plus tard VibeFox KOMOJU Payment dans la liste des modules et cliquez sur Configure.

3. Saisissez votre clé de licence VibeFox dans License key, dans le bloc de licence en haut de la page de configuration, puis cliquez sur Activate (voir Clé de licence).

4. Dans le tableau de bord KOMOJU, ajoutez un webhook avec l’URL et les événements indiqués dans la section Webhook URL, puis copiez son jeton secret (voir Configuration).

5. Saisissez la clé secrète de production et le jeton secret du webhook de production, ainsi que ceux du mode test. Activez Enable/Disable et cliquez sur Save.

À l’installation, le module crée deux statuts de commande : Awaiting KOMOJU payment et KOMOJU payment on hold. PrestaShop ne rattache un nouveau module de paiement qu’aux pays actifs à ce moment-là : un pays que vous activez plus tard doit être coché pour le module dans Payment > Preferences. Vous pouvez aussi y limiter les devises et les groupes de clients.

Configuration

Tous les réglages se trouvent sur la page du module : Modules > Module Manager > VibeFox KOMOJU Payment > Configure. Chaque section a son propre bouton Save, qui enregistre toute la page. Au-dessus des champs, la page affiche KOMOJU Sandbox Mode is enabled. tant que le mode test est activé. Elle vous avertit lorsque le mode en cours n’a pas de clé secrète (le moyen de paiement est alors masqué à l’étape de paiement) ou pas de jeton secret de webhook (les notifications KOMOJU sont alors rejetées, donc les paiements konbini et virement bancaire ne sont jamais confirmés), et lorsque KOMOJU ne prend pas en charge la devise par défaut de la boutique (le moyen de paiement est alors masqué pour les paniers dans cette devise).

Paiement KOMOJU

Enable/Disable : Enable KOMOJU Payment Gateway active ou désactive le moyen de paiement. Par défaut : désactivé.

Title : le nom du moyen de paiement affiché aux clients lors du paiement. C’est aussi le nom enregistré dans la commande. Par défaut : KOMOJU Payment.

Description : le texte affiché sous le moyen de paiement lors du 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

Les clés se trouvent dans le tableau de bord KOMOJU : la clé secrète sous Settings > API keys, le jeton secret du webhook sous Settings > Webhooks (ajoutez d’abord à cet endroit l’URL du webhook indiquée dans la section Webhook URL).

Live Secret Key : votre clé secrète KOMOJU de production. Elle commence par sk_live_.

Live Webhook Secret Token : le jeton secret du webhook de production. Il sert à vérifier la signature de chaque notification.

Mode test

KOMOJU utilise la même adresse d’API pour les paiements de test et de production : c’est la clé qui détermine le mode. Les paiements conservent le mode dans lequel ils ont été effectués, donc les remboursements et les contrôles de statut d’une commande utilisent toujours la clé de ce mode.

Sandbox Mode : Enable test mode (use the test keys below, no real payments). Par défaut : désactivé. Lorsqu’il est activé, le paiement affiche Test mode au-dessus de la description.

Sandbox Secret Key : votre clé secrète de test KOMOJU. Elle commence par sk_test_.

Sandbox Webhook Secret Token : le jeton secret du webhook du mode test.

Les clés et jetons enregistrés ne sont plus jamais affichés. Le champ reste vide et affiche Saved — leave empty to keep it. Ne saisissez une nouvelle valeur que pour la modifier.

Effacer les secrets enregistrés : cochez une clé ou un jeton et cliquez sur Save pour le supprimer. Un champ vide conserve la valeur enregistrée.

URL du webhook

Le webhook informe votre boutique des paiements, y compris des paiements konbini et virement bancaire différés. Dans le tableau de bord KOMOJU, sous Settings > Webhooks, ajoutez l’URL indiquée dans cette section, pour le mode production et pour le mode test. Avec des URL conviviales, elle ressemble à https://your-shop/module/wcp_komoju_payment/webhook, éventuellement avec un code de langue comme /en/. Copiez l’URL exactement telle qu’elle apparaît dans les 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 (ils figurent aussi dans cette section) :

Les événements d’expiration, d’annulation et d’échec ne modifient la commande que pour son paiement en cours : un paiement issu d’une tentative antérieure ne peut donc pas annuler une commande qui est payée autrement. Les webhooks sans signature valide sont rejetés. Les webhooks signés avec l’un ou l’autre jeton secret sont acceptés, mais seulement pour les paiements du même mode. Sans webhook, les paiements par carte sont tout de même confirmés au retour du client dans la boutique, mais les paiements konbini et virement bancaire ne sont jamais confirmés.

Avancé

Invoice Prefix : le préfixe des numéros de commande envoyés à KOMOJU, suivi du numéro du panier. Si vous utilisez plusieurs boutiques avec le même compte KOMOJU, rendez-le unique pour chaque boutique. Par défaut : PS-.

Enable Logging : écrit les événements KOMOJU et les appels à l’API dans logs/komoju_p_debug.log.php, dans le dossier du module. Le fichier ne peut pas être ouvert depuis le web. Les clés et les données clients ne sont pas journalisées. Les erreurs et les avertissements sont toujours écrits. Par défaut : désactivé.

Log : affiche la taille et les dernières entrées du journal. Cliquez sur Clear log pour le vider.

Delete data on uninstall : lorsqu’il est activé, la désinstallation du module supprime les réglages de la passerelle et le journal. Les commandes, les transactions et remboursements KOMOJU et les statuts de commande sont toujours conservés, donc les anciennes commandes peuvent encore être confirmées et remboursées après une réinstallation. Par défaut : désactivé.

Paiement

À l’étape de paiement, le client choisit le moyen de paiement (par défaut KOMOJU Payment) et confirme. Le module crée une session de paiement KOMOJU pour le total du panier dans la devise du panier et envoie le client sur la page de paiement KOMOJU. L’adresse e-mail, le nom, les adresses de facturation et de livraison ainsi que les articles commandés sont transmis à KOMOJU. La page s’affiche en japonais, en anglais ou en coréen, selon la langue du panier (en 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 du panier. À ce stade, aucune commande n’existe encore.

Après le paiement, le client revient dans votre boutique. Le module lit la session de paiement depuis l’API KOMOJU avec la clé du mode du paiement. La commande n’est marquée payée qu’après la confirmation de KOMOJU : par le webhook signé ou par la lecture de la session au retour du client. La commande est alors créée et le client voit la page standard de confirmation de commande avec Your payment with KOMOJU has been received. Si KOMOJU est injoignable à ce moment-là, une page Payment confirmation affiche 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. et un bouton Check again.

Pour les paiements konbini et virement bancaire, le client reçoit un bordereau de paiement. La commande est créée dans Awaiting KOMOJU payment, et la page de confirmation invite le client à effectuer le paiement selon les instructions de KOMOJU (par exemple dans une supérette ou par virement bancaire). La commande passe en Payment accepted lorsque le client paie et que KOMOJU envoie le webhook. Si le bordereau expire ou si le paiement échoue plus tard, la page de confirmation affiche Your KOMOJU payment was not completed. Please contact us about this order.

Si le paiement n’a pas été effectué, le client revient à l’étape de paiement avec The payment was not completed. You can try again or choose another payment method. Le panier est conservé. Une nouvelle tentative réutilise la session KOMOJU ouverte si le total n’a pas changé. Une session avec un ancien total est annulée dans KOMOJU, et une session payée entre-temps crée la commande au lieu d’un nouveau paiement.

Si KOMOJU ne peut pas démarrer le paiement, le client reste à l’étape de paiement avec un bref message, par exemple KOMOJU could not accept this payment: suivi du motif, 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. Le motif technique est écrit dans le journal.

Si un bon de réduction du panier cesse d’être valable entre le paiement et sa confirmation, PrestaShop le retire de la commande. La commande passe alors en KOMOJU payment on hold avec une note, car le client a payé le prix avec la remise.

Le webhook fonctionne lorsque la boutique est en mode maintenance et n’est pas bloqué par la restriction par pays de votre boutique.

Le module ne propose ni formulaire de carte sur votre site, ni cartes enregistrées, ni abonnements. Il ne restreint pas les moyens de paiement : ceux-ci sont choisis sur la page KOMOJU. Il n’a pas d’action de capture manuelle : les paiements autorisés pour une capture manuelle doivent être capturés dans le tableau de bord KOMOJU, et la commande reste dans Awaiting KOMOJU payment jusque-là.

Commandes et remboursements

Statuts de commande

No order yet : le client a été envoyé vers KOMOJU et n’a pas encore payé, ou KOMOJU n’a pas encore confirmé le paiement. Seul le panier existe.

Payment accepted : KOMOJU a confirmé le paiement. Le paiement est enregistré avec l’ID de paiement KOMOJU comme ID de transaction, et une note indique l’ID de paiement, le moyen de paiement et le mode de confirmation (webhook ou retour).

Awaiting KOMOJU payment : un bordereau konbini ou virement bancaire a été émis et attend le paiement, ou un paiement attend sa capture dans le tableau de bord KOMOJU.

KOMOJU payment on hold : KOMOJU a signalé un montant ou une devise différent du total de la commande (par exemple, le panier a été modifié après le début du paiement), un bon de réduction a été retiré, ou le paiement a été capturé après l’annulation de la commande. La note l’explique. Vérifiez la commande et traitez-la, ou remboursez le paiement.

Canceled : le bordereau de paiement a expiré ou le paiement a été annulé.

Payment error : un paiement d’une commande existante a échoué.

Refunded : le paiement a été entièrement remboursé, depuis la page de commande ou dans le tableau de bord KOMOJU.

Si un second paiement est capturé pour une commande déjà payée, la commande ne change pas. Une note vous invite à le rembourser dans le tableau de bord KOMOJU s’il s’agit d’un doublon. Les commandes remboursées ne sont jamais rouvertes.

Bloc paiement KOMOJU

La page de commande affiche un bloc KOMOJU payment avec l’ID de paiement KOMOJU (lié au paiement dans le tableau de bord KOMOJU) et le moyen de paiement, la session, le numéro de commande chez KOMOJU, le statut, le montant payé et le montant remboursé, un badge Test mode pour les paiements de test, l’historique des remboursements et les KOMOJU notes de la commande.

Remboursements

Dans le bloc KOMOJU payment, saisissez le montant (le montant non encore remboursé est prérempli), facultativement un motif, puis cliquez sur Refund via KOMOJU. Confirmez la question Refund this amount through KOMOJU? This cannot be undone. Les remboursements totaux et partiels sont pris en charge. Vous devez disposer du droit de modifier les commandes. Les remboursements sont limités au montant réellement encaissé par KOMOJU : après un écart de montant, vous pouvez donc rembourser jusqu’au montant payé par le client, et non jusqu’au total de la commande. Le remboursement est envoyé avec la clé du mode dans lequel le paiement a été effectué ; la clé secrète de ce mode doit donc être renseignée. Le module vérifie d’abord le paiement dans KOMOJU et refuse les remboursements supérieurs au montant encore remboursable. Si KOMOJU ne peut pas rembourser un paiement automatiquement (certains moyens, par exemple konbini, nécessitent les coordonnées bancaires du client), le message d’erreur de KOMOJU s’affiche et rien n’est enregistré : traitez ces remboursements dans le tableau de bord KOMOJU. Un remboursement n’est considéré comme effectué que lorsque KOMOJU le confirme. Un remboursement réussi est ajouté à l’historique des remboursements et aux notes. Un remboursement total place la commande en Refunded. Un remboursement partiel ne modifie pas le statut. Les remboursements sont disponibles une fois que KOMOJU a capturé le paiement.

Pour les paiements que KOMOJU a convertis dans une autre devise (par exemple konbini en JPY pour un panier en EUR), seul un remboursement total est possible depuis PrestaShop. Effectuez les remboursements partiels dans le tableau de bord KOMOJU.

Le module ne crée pas d’avoirs. Les boutons de remboursement standard de PrestaShop sur la page de commande ne renvoient pas d’argent via KOMOJU.

Les remboursements effectués dans le tableau de bord KOMOJU arrivent par webhook et sont ajoutés à l’historique des remboursements avec une note. Lorsque le paiement entier est remboursé, la commande passe en Refunded. Les remboursements partiels effectués dans le tableau de bord pour des paiements convertis dans une autre devise ne sont notés que sur la commande : enregistrez manuellement le montant correspondant dans PrestaShop (avoir).

Clé de licence

Le module fonctionne avec une clé de licence VibeFox obtenue sur vibefox.net. Le bloc de licence License — VibeFox KOMOJU Payment est le premier bloc de Modules > Module Manager > VibeFox KOMOJU Payment > Configure, au-dessus des réglages. Saisissez la clé dans License key et cliquez sur Activate. Ensuite, le bloc affiche la clé masquée, le statut (par exemple la date jusqu’à laquelle la licence est active et votre domaine) ainsi que les boutons Check now pour vérifier à nouveau le statut, Change key pour saisir une autre clé et Remove key pour retirer la clé de cette boutique. En dessous figurent la ligne Product: presta-payment-komoju et le lien Manage licenses and domains in your account, qui ouvre votre compte vibefox.net. Seuls les employés disposant de la permission Configure pour le module peuvent modifier la clé. Les textes du bloc suivent la langue du back-office (l’anglais et le russe sont inclus).

Si la clé n’est pas acceptée, le bloc indique la raison, par exemple Key not found, This key belongs to another product, Domain limit reached ou License expired on suivi d’une date. Après un changement d’adresse de la boutique, ou après avoir libéré un emplacement de domaine dans votre compte, cliquez sur Check now. Si le serveur de licences est injoignable, le module continue de fonctionner avec le dernier statut connu.

Une clé fonctionne sur un seul domaine : le domaine de la boutique principale, y compris dans une configuration multiboutique. Retirer la clé de la boutique ne libère pas son emplacement de domaine. Libérez l’emplacement dans votre compte vibefox.net.

Sans clé active, KOMOJU n’est pas affiché aux clients lors du paiement. Si un paiement est tout de même lancé, le client voit This payment method is not available. Please choose another one. La boutique PrestaShop ne sait pas que vous êtes connecté au back-office : le moyen de paiement vous est donc masqué également. Vous pouvez configurer le module avant d’acheter une clé, mais pas le tester lors du paiement. Un rappel apparaît dans Modules > Module Manager, sous l’onglet Alerts. Les commandes existantes ne sont pas affectées : les paiements déjà lancés sont toujours confirmés, et les remboursements fonctionnent.

Lorsqu’une licence expire, le module continue de fonctionner, mais les mises à jour et le support nécessitent un renouvellement. Le statut est vérifié à nouveau automatiquement pendant votre travail dans le back-office : une fois par jour pendant les 14 premiers jours après la saisie de la clé, puis une fois par semaine. Aucune tâche cron n’est nécessaire. Désinstaller ou réinitialiser le module supprime toujours la clé de licence et le statut de la licence.

Dépannage

KOMOJU n’apparaît pas au paiement : vérifiez que la licence est active, que Enable/Disable est activé et que le mode en cours a une clé secrète : Sandbox Secret Key en mode test, Live Secret Key en mode production. La devise du panier doit être prise en charge par KOMOJU. La page de réglages affiche un avertissement lorsqu’un élément manque. Dans Payment > Preferences, vérifiez que le module est autorisé pour la devise du panier, le pays du client et le groupe du client.

Le paiement a abouti, mais aucune commande n’a été créée : le webhook ne fonctionne pas. Dans le tableau de bord KOMOJU, vérifiez que le webhook existe pour le mode que vous utilisez, que son URL est exactement celle indiquée dans la section Webhook URL et que les événements sont sélectionnés. Vérifiez que son jeton secret se trouve dans le champ correspondant (Live Webhook Secret Token ou Sandbox Webhook Secret Token), et consultez le champ Log sur la page du module. Les paiements par carte sont aussi confirmés lorsque le client revient dans votre boutique, mais les paiements konbini et virement bancaire ne sont confirmés que par le webhook.

Le webhook répond Failed to verify KOMOJU webhook signature.: le jeton secret est absent ou appartient à un autre webhook. KOMOJU renouvelle la notification.

Le webhook répond Mode mismatch, ignored.: le webhook a été signé avec le jeton secret de l’autre mode que celui du paiement. Utilisez des webhooks et des jetons distincts pour la production et le mode test, et vérifiez qu’ils ne sont pas inversés.

Le webhook répond Order is busy, retry later. ou Temporary error, retry later.: la commande était en cours de mise à jour par une autre requête, la commande n’a pas pu être créée à ce moment-là (par exemple, le module est désactivé), ou le paiement n’a pas pu être vérifié. KOMOJU renouvelle la notification. Le motif figure dans le journal.

L’URL du webhook affiche une erreur dans le navigateur : c’est normal. L’URL n’accepte que les requêtes signées envoyées par KOMOJU.

La commande est en KOMOJU payment on hold ou Awaiting KOMOJU payment : lisez les KOMOJU notes dans le bloc de commande. Un bordereau attend le paiement, un paiement attend sa capture dans le tableau de bord KOMOJU, le montant ou la devise ne correspondait pas, un bon de réduction a été retiré, ou le paiement est arrivé après l’annulation de la commande.

Le remboursement échoue : lisez le message. La clé secrète du mode dans lequel le paiement a été effectué est peut-être absente, le paiement ne peut peut-être pas être remboursé automatiquement (remboursez-le dans le tableau de bord KOMOJU), KOMOJU ne reconnaît peut-être pas le paiement avec la clé configurée, ou seul un remboursement total est possible pour un paiement converti.

Les développeurs peuvent modifier la liste des devises avec le hook actionKomojuPSupportedCurrencies, et la session de paiement, par exemple les moyens de paiement, avec le hook actionKomojuPSessionParams.

Désinstallation

Allez dans Modules > Module Manager, ouvrez le menu à côté de VibeFox KOMOJU Payment et choisissez Uninstall. La clé de licence et le statut de licence de ce module sont toujours supprimés. Si Delete data on uninstall est activé, les réglages de la passerelle et le journal sont supprimés. S’il est désactivé, tous les réglages sont conservés pour une réinstallation ultérieure. Les transactions et remboursements KOMOJU et les statuts de commande Awaiting KOMOJU payment et KOMOJU payment on hold sont toujours conservés, donc les anciennes commandes peuvent encore être confirmées et remboursées après une réinstallation. Les commandes existantes conservent leurs notes de paiement et leurs ID de transaction.

KOMOJU est une marque appartenant à son propriétaire respectif. Ce module n’est ni affilié à KOMOJU ni approuvé par KOMOJU.