VibeFox Omise for PrestaShop — Aide

Prérequis

PrestaShop : 8.0 à 9.x.

PHP : 8.0 ou ultérieur. Le module refuse de s'installer sur les anciennes versions de PHP.

HTTPS : les champs de carte se trouvent sur votre page de paiement, la page doit donc être servie en HTTPS. Les données de carte n'atteignent toujours pas votre serveur. Omise n'envoie les webhooks qu'à des adresses HTTPS, et la page 3-D Secure de la banque doit être une adresse HTTPS.

Devise : l'une de THB, JPY, SGD, MYR, USD, EUR, GBP, AUD, CAD, CHF, CNY, DKK, HKD. Pour un panier dans une autre devise, le moyen de paiement est masqué à l'étape de paiement.

Compte Omise : vous avez besoin de la clé publique et de la clé secrète de votre compte Omise, pour le mode test et pour le mode production, à récupérer dans Settings > Keys du tableau de bord Omise, ainsi que d'un point de terminaison de webhook dans Settings > Webhooks (voir Configuration).

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 Omise Payment dans la liste des modules et cliquez sur Configure.

3. Saisissez votre clé de licence VibeFox dans le champ License key du bloc de licence en haut de la page Configure et cliquez sur Activate (voir Clé de licence).

4. Saisissez vos clés Omise de test et de production, et ajoutez dans le tableau de bord Omise l'URL du webhook affichée sur la page de réglages (voir Configuration).

5. Activez Enable/Disable et cliquez sur Save. Testez un paiement en mode test avec une carte de test Omise, par exemple 4242 4242 4242 4242, puis désactivez Test mode.

À l'installation, le module crée trois statuts de commande : Omise payment authorized, Omise payment on hold et Awaiting Omise payment. Le moyen de paiement est proposé dans les pays actifs au moment de l'installation. Si vous activez d'autres pays plus tard, autorisez-y le module dans Payment > Preferences, où vous pouvez aussi le limiter par devise et par groupe de clients.

Configuration

Tous les réglages se trouvent sur la page du module : Modules > Module Manager > VibeFox Omise Payment > Configure. Chaque section a son propre bouton Save, qui enregistre la page entière. Au-dessus des champs, la page affiche Test mode is on — orders are charged with the test keys, no real money is moved. tant que le mode test est activé, vous avertit si la clé publique ou secrète du mode actuel manque, et vous avertit lorsque Omise n'accepte pas la devise par défaut de votre boutique. Dans ces cas, le moyen de paiement est masqué à l'étape de paiement.

Omise

Enable/Disable : Enable card payments via Omise active ou désactive le moyen de paiement. Par défaut : off.

Title : le nom du moyen de paiement que le client voit à l'étape de paiement. C'est aussi le nom du moyen de paiement enregistré dans la commande. Par défaut : Credit / Debit Card. Obligatoire.

Description : le texte affiché au-dessus du formulaire de carte à l'étape de paiement. Par défaut : Pay securely with your credit or debit card via Omise.

Clés API

Vos clés se trouvent dans le tableau de bord Omise, sous Settings > Keys. Les clés de test commencent par pkey_test_ et skey_test_, les clés de production par pkey_ et skey_. À l'enregistrement, une clé au mauvais préfixe (par exemple une clé de test dans un champ de production) n'est pas enregistrée : la valeur précédente est conservée et un avertissement s'affiche.

Test mode : utilise les clés de test, sans débit réel. Les deux clés changent ensemble. Les captures, remboursements et vérifications de statut d'une commande utilisent toujours les clés du mode dans lequel la commande a été payée. Par défaut : on.

Test public key : la clé publique du mode test, pkey_test_...

Test secret key : la clé secrète du mode test, skey_test_...

Live public key : la clé publique du mode production, pkey_...

Live secret key : la clé secrète du mode production, skey_...

Les clés secrètes enregistrées ne sont jamais réaffichées. Le champ reste vide et affiche Saved — leave empty to keep it. Ne saisissez une nouvelle valeur que si vous voulez la changer.

Clear saved secrets : cochez une clé secrète et cliquez sur Save pour la supprimer. Un champ vide conserve la valeur enregistrée.

Paiement et webhook

Webhook URL : l'adresse du webhook de votre boutique. Avec des URL conviviales, elle ressemble à https://your-shop/module/wcp_omise_payment/webhook. Copiez-la exactement telle qu'elle est affichée dans les réglages et ajoutez-la dans le tableau de bord Omise, sous Settings > Webhooks (HTTPS uniquement). Le module gère ces événements (ils sont aussi listés dans cette section) :

Omise ne signe pas les webhooks : le contenu du webhook n'est donc jamais considéré comme fiable. Le débit doit avoir été créé par cette boutique pour ce panier, et son statut est relu depuis l'API Omise avec la clé secrète du mode du paiement. Sans webhook, une commande dont le client ferme le navigateur pendant le 3-D Secure n'est pas créée automatiquement, et les captures effectuées dans le tableau de bord Omise ne sont pas prises en compte tant que vous ne cliquez pas sur Sync payment status.

Payment action : ce qui arrive au montant de la carte.

Per-charge webhook : envoie l'URL du webhook avec chaque débit. Utile lorsque plusieurs boutiques partagent un même compte Omise. Ne fonctionne que si la boutique utilise HTTPS ; sinon, le webhook du tableau de bord est utilisé. Par défaut : off.

Avancé

Debug log : écrit les requêtes API et les événements de paiement dans logs/omise_p_debug.log.php, dans le dossier du module. Le fichier ne peut pas être lu depuis le web. Les clés, jetons et données de carte ne sont jamais journalisés. Par défaut : off. Rien n'est écrit tant qu'il est désactivé, erreurs comprises ; activez-le donc lorsque vous cherchez un problème.

Log : affiche la taille et les dernières entrées du journal, avec un bouton pour le vider.

Delete data on uninstall : lorsqu'il est activé, la désinstallation du module supprime les réglages et le journal de débogage. Les débits et remboursements Omise des commandes font partie de l'historique de paiement et sont toujours conservés. Par défaut : off.

Paiement

À l'étape de paiement, le client choisit le moyen de paiement (par défaut Credit / Debit Card) et remplit le formulaire de carte : Name on card, Card number, Expiry month (MM), Expiry year (YYYY) et Security code (CVV). En mode test, le formulaire affiche TEST MODE — use Omise test cards (e.g. 4242 4242 4242 4242), no real charges are made. Lorsque le client passe commande, Omise.js transforme la carte en jeton à usage unique dans le navigateur, en utilisant l'adresse de facturation du panier. Les champs de carte ne sont jamais transmis à votre boutique. Les champs manquants ou invalides s'affichent sous le formulaire, par exemple Please enter a valid card number.

Votre boutique crée ensuite le débit avec la clé secrète pour le total du panier, dans la devise du panier. La description du débit est le nom de la boutique et le numéro de panier, et l'ID du panier est enregistré dans les métadonnées du débit. Aucune commande n'existe encore à ce stade. Si la banque exige le 3-D Secure, le client est envoyé sur la page de la banque puis revient dans votre boutique, et le résultat est relu depuis l'API Omise.

La commande n'est marquée payée qu'après confirmation d'Omise : le débit doit être capturé, et son montant et sa devise doivent correspondre au panier. Le client voit la page standard de confirmation de commande avec Your card payment has been received. Avec Authorize only, la page indique Your card payment has been authorized. The amount will be charged when your order is processed. Si Omise signale encore le paiement comme en attente, la commande est créée en Awaiting Omise payment et la page indique Your payment is being confirmed by Omise. You will receive an e-mail as soon as it is confirmed — please do not pay again. Si le paiement ne peut pas être confirmé juste après le 3-D Secure, une page Payment confirmation affiche We could not confirm your payment yet. If your card was charged, the order will be updated automatically — please do not pay again. ainsi qu'un bouton Check again.

Si la carte est refusée, aucune commande n'est créée. Le client reste sur la page de paiement avec Payment failed: et un motif, par exemple fonds insuffisants, code de sécurité invalide ou refus de l'émetteur de la carte, et peut réessayer avec le même panier. Si le 3-D Secure échoue, le client revient aussi sur la page de paiement avec le motif ; si le débit a expiré ou a été annulé entre-temps, le message est The payment was not completed. Please try again.

Une nouvelle tentative ne débite jamais deux fois : si le débit précédent du panier est déjà payé ou autorisé, la commande est créée sans nouveau débit. Une tentative 3-D Secure inachevée est expirée avant tout nouveau débit. Si un second débit reste payé pour un panier qui a déjà une commande (par exemple dans un autre onglet du navigateur), la commande n'est pas modifiée et une note vous demande de le rembourser ou de l'annuler dans le tableau de bord Omise.

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

Le module n'accepte que les cartes. Il ne propose aucun autre moyen de paiement Omise (PromptPay, TrueMoney, banque mobile, paiements en plusieurs fois), aucune carte enregistrée ni client Omise, aucun abonnement et aucune capture partielle.

Commandes et remboursements

Statuts de commande

No order yet : le client est en 3-D Secure, ou la carte a été refusée. Seul le panier existe.

Payment accepted : le paiement a été confirmé. Le paiement est enregistré avec l'ID de débit Omise (chrg_...) comme ID de transaction, et une note indique le montant, le débit et la manière dont il a été confirmé (paiement, retour du 3-D Secure, webhook, nouvelle tentative, capture manuelle ou synchronisation manuelle). Les notes sont des messages privés de la commande, visibles uniquement dans le back-office.

Omise payment authorized : la carte a été autorisée avec Authorize only. Utilisez Capture payment ou Void authorization.

Awaiting Omise payment : Omise n'a pas encore confirmé le paiement. Le webhook ou Sync payment status met la commande à jour.

Omise payment on hold : le montant ou la devise du débit ne correspond pas à la commande, par exemple parce que le panier a été modifié pendant le 3-D Secure. La note affiche les deux valeurs. Un paiement capturé reste enregistré sur la commande. Vérifiez la commande, puis traitez-la ou remboursez le paiement.

Payment error : un paiement en attente a échoué par la suite. Une commande payée n'est jamais rétrogradée par un événement d'échec ultérieur.

Canceled : le débit a expiré ou l'autorisation a été annulée.

Refunded : le paiement a été intégralement remboursé via le module.

Si un débit payé ou autorisé arrive pour une commande déjà Annulée ou Remboursée, la commande n'est pas rouverte. Une note vous demande de vérifier le tableau de bord Omise et de rembourser ou rouvrir la commande manuellement.

Bloc de paiement Omise

La page de commande affiche un bloc Omise payment avec l'ID du débit, l'action de paiement, le statut du débit, la marque et les derniers chiffres de la carte, les montants débité, de la commande et remboursé, un badge Test mode pour les paiements de test et l'historique des remboursements. Les boutons du bloc nécessitent le droit de modifier les commandes et la clé secrète du mode dans lequel le paiement a été effectué. L'accès aux pages des modules n'est pas nécessaire. Le résultat de chaque action s'affiche en haut du bloc.

Capture payment : capture le montant autorisé en totalité et passe la commande en Payment accepted. Affiché uniquement pour les commandes autorisées.

Void authorization : annule l'autorisation ; aucun argent n'est capturé et la commande passe en Canceled. Affiché uniquement pour les commandes autorisées.

Sync payment status : relit le débit depuis Omise et met la commande à jour. La note affiche aussi le total remboursé chez Omise.

Remboursements

Dans le bloc Omise payment, saisissez le montant (le montant non encore remboursé est prérempli), éventuellement un motif, puis cliquez sur Refund via Omise. Confirmez la question Refund this amount through Omise? This cannot be undone. Les remboursements totaux et partiels sont pris en charge. Les remboursements s'effectuent dans le montant et la devise débités par Omise ; après un écart de montant ou de devise, vous pouvez donc rembourser jusqu'à concurrence de ce que le client a réellement payé, et non jusqu'au total de la commande. Le remboursement est envoyé dans le mode dans lequel le paiement a été effectué ; la clé secrète de ce mode doit donc être renseignée. Le motif est enregistré avec le remboursement chez Omise. Un remboursement réussi est ajouté à l'historique des remboursements et aux notes, avec l'ID de remboursement Omise. Un remboursement total passe la commande en Refunded ; un remboursement partiel ne modifie pas le statut. Pour une autorisation pas encore capturée, seul un remboursement total est possible, et il annule l'autorisation. Si Omise refuse le remboursement, le bloc affiche Refund failed. avec le message d'Omise, et aucun remboursement n'est enregistré.

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 Omise. Les remboursements effectués dans le tableau de bord Omise ne sont pas enregistrés dans PrestaShop ; Sync payment status affiche le total remboursé.

Clé de licence

Le module fonctionne avec une clé de licence VibeFox obtenue sur vibefox.net. Le bloc de licence License — VibeFox Omise Payment est le premier bloc de Modules > Module Manager > VibeFox Omise 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-omise et le lien Manage licenses and domains in your account, qui ouvre votre compte vibefox.net. Seuls les employés disposant de l'autorisation 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 Clé introuvable, Cette clé appartient à un autre produit, Limite de domaines atteinte ou Licence expirée le 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, Omise n'est pas affiché aux clients au moment de la commande. Si un paiement est lancé malgré tout, le client voit Ce moyen de paiement n'est pas disponible. Veuillez en choisir un autre. La vitrine PrestaShop ne sait pas que vous êtes connecté au back-office ; le moyen de paiement est donc masqué aussi pour vous : vous pouvez configurer le module avant d'acheter une clé, mais pas le tester au moment de la commande. Un rappel apparaît dans Modules > Module Manager, sur l'onglet Alerts. Les commandes existantes ne sont pas affectées : les paiements déjà commencés sont toujours confirmés, et les remboursements continuent de fonctionner.

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. La désinstallation ou la réinitialisation du module supprime toujours la clé de licence et le statut de licence.

Dépannage

Omise does not appear at checkout : vérifiez que la licence est active, que Enable/Disable est activé, que les deux clés du mode actuel sont saisies (clés de test en mode test, clés de production sinon) et que la devise du panier fait partie des devises prises en charge. La page des réglages affiche un avertissement lorsque des clés manquent. Dans Payment > Preferences, vérifiez que le module est autorisé pour la devise du panier, le pays du client et le groupe du client.

The payment went through, but no order was created or the order stays Awaiting Omise payment : le webhook ne fonctionne pas. Dans le tableau de bord Omise, vérifiez que l'URL du webhook est exactement celle affichée dans Webhook URL et qu'elle utilise HTTPS. Sur une commande existante, cliquez sur Sync payment status. Activez Debug log pour voir les réponses du webhook.

Webhook answers Charge ID does not match order or Order not found : le débit de l'événement n'a pas été créé par cette boutique pour ce panier. Rien n'est modifié.

Webhook answers Order is being processed, retry later or Failed to verify charge : le panier a été verrouillé par une autre requête au même moment, l'API Omise n'a pas pu être jointe, ou la clé secrète du mode du paiement est manquante. Omise relance le webhook.

Webhook answers The order could not be created, retry later : la commande n'a pas pu être créée, par exemple parce que le module est désactivé. Activez Debug log pour voir la raison.

The webhook URL shows Method not allowed in the browser : c'est normal. L'URL n'accepte que les requêtes provenant d'Omise.

Warning on save: key must start with ... or must be a live key : une clé a été collée dans le mauvais champ et n'a pas été enregistrée. Les clés de test commencent par pkey_test_ / skey_test_, les clés de production par pkey_ / skey_.

The customer sees Card payments are temporarily unavailable : les clés sont incorrectes, ou le jeton de carte appartient à l'autre mode (un jeton de test en production, ou l'inverse). Vérifiez les clés et Test mode.

The customer sees We could not reach the payment provider : aucune réponse valide n'est venue d'Omise lors de la création du débit. Un débit a pu quand même être créé ; vérifiez le tableau de bord Omise avant que le client ne paie à nouveau.

The customer sees This order is already being paid : le paiement a été soumis deux fois au même moment. Le client patiente un instant et vérifie ses e-mails avant de réessayer.

Order is Omise payment on hold after payment : lisez la note de la commande (voir Statuts de commande), puis traitez la commande ou remboursez le paiement.

Refund fails with a message about the mode : le paiement a été effectué en mode test ou production, et la clé secrète de ce mode n'est pas renseignée. Saisissez-la et réessayez.

Partial refund of an authorized order fails : le paiement est seulement autorisé. Capturez-le d'abord, ou remboursez le montant total pour l'annuler.

Désinstallation

Allez dans Modules > Module Manager, ouvrez le menu à côté de VibeFox Omise 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 et le journal de débogage sont supprimés. S'il est désactivé, tous les réglages sont conservés pour une réinstallation ultérieure. Les débits et remboursements Omise ainsi que les statuts de commande Omise payment authorized, Omise payment on hold et Awaiting Omise payment sont toujours conservés, afin que les commandes payées auparavant puissent encore être remboursées après une réinstallation. Les commandes existantes conservent leurs notes de paiement et leurs ID de transaction.

Omise est une marque commerciale de son propriétaire respectif. Ce module n'est pas affilié à Omise et n'est pas approuvé par Omise.