VibeFox Kushki 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.
Devise : USD (Équateur) ou COP (Colombie). Pour les paniers dans d'autres devises, le mode de paiement est masqué à l'étape de paiement.
HTTPS : Kushki exige que la page de paiement soit servie en HTTPS en mode réel.
Compte Kushki : vous avez besoin des identifiants marchands publics et privés de votre compte de test (UAT) Kushki et de votre compte de production. Ils se trouvent dans la Kushki Console, sous Developers > Credentials. Pour le webhook facultatif, vous avez aussi besoin de la clé de signature du webhook de chaque compte (voir Configuration).
VibeFox license key : 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 Kushki 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 Configure, puis cliquez sur Activate (voir Clé de licence).
4. Saisissez les identifiants marchands publics et privés de test et laissez Test mode activé. Facultativement, configurez le webhook dans la Kushki Console et collez sa clé de signature (voir Configuration).
5. Activez Enable / Disable, cliquez sur Save et passez une commande de test. Quand tout est prêt, saisissez les identifiants marchands réels (et la signature du webhook réel) et désactivez Test mode.
À l'installation, le module crée le statut de commande Kushki payment on hold. PrestaShop attribue un nouveau module de paiement aux devises, pays et groupes de clients de votre boutique. Dans Payment > Preferences, vérifiez que le module est autorisé pour USD ou COP et pour l'Équateur ou la Colombie.
Configuration
Tous les réglages se trouvent sur la page du module : Modules > Module Manager > VibeFox Kushki Payment > Configure. Chaque section a son propre bouton Save, qui enregistre la page entière. Au-dessus des champs, la page vous avertit lorsque le mode de paiement est activé mais que les identifiants marchands du mode actuel manquent (le mode de paiement est alors masqué à l'étape de paiement), lorsque la devise par défaut de votre boutique n'est ni USD ni COP, lorsque le mode réel est utilisé sans HTTPS et lorsque le mode actuel n'a pas de signature de webhook. Tant que le mode test est activé, elle affiche Mode test activé : l'environnement de test de Kushki est utilisé, aucun paiement réel n'est débité. Si vous enregistrez alors que le mode de paiement est activé sans les identifiants marchands du mode actuel, les réglages sont enregistrés et un message vous rappelle de les saisir. Les espaces autour des identifiants sont supprimés à l'enregistrement.
Kushki
Enable / Disable : Enable Kushki card payments active ou désactive le mode de paiement. Par défaut : désactivé.
Title : le nom du mode de paiement que voient les clients à l'étape de paiement. C'est aussi le nom du mode de paiement enregistré dans la commande. Par défaut : Credit / debit card (Kushki). Obligatoire.
Description : le texte affiché au-dessus du formulaire de carte à l'étape de paiement. Par défaut : Pay securely with your card. Card details are entered in a Kushki form and never stored on this site.
Identifiants API
Copiez les identifiants marchands publics et privés depuis la Kushki Console (Developers > Credentials). Les comptes de test (UAT) et de production ont des identifiants différents. Le mode test n'utilise que les identifiants de test, le mode réel uniquement les identifiants réels.
Test mode : utilise l'environnement de test (UAT) de Kushki : les identifiants marchands de test, le formulaire de carte de test et l'API de test ensemble. Aucun paiement réel n'est débité, et un badge TEST MODE est affiché à l'étape de paiement. Par défaut : activé. Désactivez-le pour encaisser de vrais paiements. Les remboursements vont toujours vers l'environnement dans lequel le paiement a été effectué.
Test Public Merchant ID : l'identifiant marchand public de votre compte de test Kushki. Il charge le formulaire de carte.
Test Private Merchant ID : l'identifiant marchand privé de votre compte de test Kushki. Il est utilisé côté serveur pour les débits et les remboursements.
Live Public Merchant ID : l'identifiant marchand public de votre compte de production Kushki.
Live Private Merchant ID : l'identifiant marchand privé de votre compte de production Kushki. Gardez-le secret.
Les identifiants marchands privés et les signatures de webhook enregistrés ne sont plus jamais affichés. Le champ reste vide et affiche Enregistré : laissez vide pour le conserver. Saisissez une nouvelle valeur uniquement pour la modifier.
Webhook (recommandé)
Les paiements sont confirmés immédiatement par la réponse de l'API Kushki, donc le webhook n'est pas obligatoire. Il crée en plus la commande pour un paiement dont la réponse a été perdue (par exemple à cause d'un délai d'attente) et signale les annulations et remboursements effectués dans la Kushki Console. Dans la Kushki Console (Webhooks), ajoutez l'URL affichée sous Webhook URL pour les paiements par carte. Avec les URL conviviales, elle ressemble à https://your-shop/module/wcp_kushki_payment/webhook, éventuellement avec un code de langue comme /es/. Copiez l'URL exactement telle qu'elle apparaît dans les réglages. Faites-le pour le compte de test et pour le compte de production.
Le module traite ces notifications de carte :
Test webhook signature : la clé de signature du webhook du compte de test Kushki (Console > Webhooks).
Live webhook signature : la clé de signature du webhook du compte de production Kushki.
Clear saved secrets : cochez un identifiant marchand privé ou une signature de webhook puis cliquez sur Save pour le supprimer. Un champ vide conserve la valeur enregistrée.
Les webhooks sans signature valide sont rejetés. Une notification doit être signée avec la clé du mode dans lequel le paiement a été effectué : ainsi, une notification de test ne confirme jamais un paiement réel. Sans clé de signature, toutes les notifications de webhook sont rejetées, mais les paiements fonctionnent toujours, car ils sont confirmés par la réponse de l'API.
Avancé
Debug log : écrit les requêtes et les webhooks Kushki dans logs/kushki_p_debug.log.php, dans le dossier du module. Le fichier ne peut pas être ouvert depuis le web. Les erreurs sont toujours journalisées. Les journaux ne contiennent jamais d'identifiants marchands, de jetons de carte ni d'adresses e-mail de clients. 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'elle est activée, la désinstallation du module supprime les réglages et les journaux. Les enregistrements de paiements Kushki (débits et remboursements) et le statut de commande Kushki payment on hold sont toujours conservés, afin que les anciennes commandes puissent encore être remboursées après une réinstallation. Par défaut : désactivé.
Paiement
À l'étape de paiement, le client choisit le mode de paiement (par défaut Credit / debit card (Kushki)). Le formulaire de carte Kushki apparaît en dessous, avec le total du panier dans la devise du panier. Le client saisit sa carte, choisit les paiements en plusieurs fois si le formulaire Kushki les propose, puis appuie sur le bouton de paiement à l'intérieur du formulaire Kushki.
Le bouton Place order de PrestaShop reste visible, car il porte les conditions générales de vente. Si les conditions sont déjà acceptées, le paiement est envoyé automatiquement après le bouton de paiement Kushki. Sinon, le client voit Votre carte a été acceptée par Kushki. Acceptez les conditions générales de vente et cliquez sur « Place order » pour payer. Si le client clique sur Place order sans utiliser le formulaire Kushki, le message Veuillez saisir les données de votre carte dans le formulaire Kushki et cliquer sur son bouton de paiement. s'affiche.
Votre boutique débite ensuite la carte côté serveur. La commande n'est marquée comme payée qu'après la confirmation de Kushki avec un numéro de ticket. Elle est alors créée, et le client voit la page standard de confirmation de commande avec Votre paiement par carte a bien été reçu. Si Kushki signale un montant ou une devise, ils sont comparés au panier. Une commande en attente affiche Votre paiement est en cours de vérification. Nous mettrons votre commande à jour dès que la vérification sera terminée.
Si la carte est refusée, aucune commande n'est créée et le client revient à l'étape de paiement avec Votre paiement a été refusé et le motif indiqué par Kushki, et peut essayer une autre carte. En cas de problème réseau, de clé ou de serveur, le client voit Le paiement ne peut pas être traité pour le moment. Veuillez réessayer dans un instant ou choisir un autre mode de paiement. Le motif technique est écrit dans le journal. Un second clic pendant qu'un paiement est en cours de traitement affiche Un paiement pour cette commande est déjà en cours de traitement. Veuillez patienter un instant et vérifier le statut de votre commande.
Si la réponse de Kushki est perdue (par exemple à cause d'un délai d'attente), le client voit le message général, mais la tentative de débit est conservée. Lorsque le webhook signé signale le débit approuvé, la commande est créée. Un panier qui a déjà une commande, ou un débit approuvé dont la commande n'a pas encore été créée, n'est jamais débité à nouveau : le client voit la confirmation de cette commande. Si le client paie à nouveau avant l'arrivée de tout webhook, il s'agit d'un nouveau débit ; une approbation tardive du premier débit ajoute alors seulement une note signalant un éventuel double débit.
Le webhook fonctionne même lorsque la boutique est en mode maintenance et n'est pas bloqué par la restriction géographique de votre boutique. Le 3-D Secure, les règles antifraude et les paiements en plusieurs fois proposés se configurent dans la Kushki Console.
Le module ne gère que les paiements par carte en une étape. Il ne prend en charge ni remboursements partiels, ni cartes enregistrées ou abonnements, ni paiements en espèces, par virement bancaire (PSE) ou par carte de débit avec redirection, ni autorisation et capture séparées.
Commandes et remboursements
Statuts de commande
No order yet : le client n'a pas payé, la carte a été refusée, ou la réponse de Kushki a été perdue et le webhook n'est pas encore arrivé. Seul le panier existe.
Payment accepted : Kushki a confirmé le débit (par la réponse de l'API ou par le webhook). Le paiement est enregistré avec la référence de transaction Kushki (ou le numéro de ticket) comme ID de transaction. Une note indique le mode, le numéro de ticket Kushki et la référence.
Kushki payment on hold : Kushki a renvoyé un succès sans numéro de ticket, a signalé un montant ou une devise différents de ceux du panier, ou le panier a été modifié pendant le paiement. La note l'explique. Vérifiez la transaction dans la Kushki Console, puis traitez la commande ou remboursez le paiement. Une approbation signée ultérieure avec un numéro de ticket et un montant correspondant fait passer la commande à Payment accepted.
Payment error : le webhook a signalé que le débit d'une commande en attente a été refusé.
Refunded : le paiement a été remboursé via le module.
Si Kushki signale un autre débit approuvé pour une commande déjà payée, annulée ou remboursée, la commande n'est pas modifiée. Une note vous demande de vérifier s'il y a un double débit et de le rembourser dans la Kushki Console. Un webhook provenant de l'environnement de test pour un paiement réel (ou l'inverse) est ignoré, avec une note.
Bloc de paiement Kushki
La page de commande affiche un bloc Kushki payment avec le numéro de ticket, la référence de transaction, l'environnement (avec un badge Test pour les paiements de test), le statut du débit, le montant débité et le total de la commande, le formulaire de remboursement, l'historique des remboursements et les Kushki notes de la commande.
Remboursements
Kushki rembourse la totalité du débit, donc seuls les remboursements complets sont possibles. Dans le bloc Kushki payment, le montant débité par Kushki est déjà renseigné. Si vous le souhaitez, saisissez un motif et cliquez sur Refund via Kushki, puis confirmez la question Rembourser la totalité du paiement via Kushki ? Cette action est irréversible. Vous devez avoir le droit de modifier les commandes. Pour tout autre montant, le module affiche Kushki rembourse uniquement la totalité du paiement. Saisissez le montant total débité avec le montant, et rien n'est envoyé. Le remboursement est effectué dans le montant et la devise débités par Kushki : en cas d'écart de montant, le client récupère donc ce qui a réellement été débité, et non le total de la commande. Un paiement ne peut être remboursé qu'une fois.
Le remboursement est envoyé dans le mode dans lequel le paiement a été effectué (test ou réel), donc l'identifiant marchand privé de ce mode doit être renseigné. Si Kushki n'accepte pas le remboursement, le bloc affiche Échec du remboursement Kushki avec le code et le message de Kushki, et aucun remboursement n'est enregistré. Un remboursement réussi est ajouté à l'historique des remboursements et aux notes avec le ticket de remboursement Kushki, et la commande passe à Refunded. Les remboursements nécessitent un débit Kushki confirmé avec un numéro de ticket.
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 Kushki. Les annulations et remboursements effectués dans la Kushki Console arrivent par le webhook et sont ajoutés aux notes. Le statut de la commande n'est pas modifié automatiquement.
Clé de licence
Le module fonctionne avec une clé de licence VibeFox obtenue sur vibefox.net. Le bloc de licence License — VibeFox Kushki Payment est le premier bloc de Modules > Module Manager > VibeFox Kushki Payment > Configure, au-dessus des réglages. Collez la clé dans License key et cliquez sur Activate. Ensuite, le bloc affiche la clé masquée, le statut (par exemple la date de fin de validité de la licence 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-kushki 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 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 : celui 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, Kushki n'est pas affiché aux clients à l'étape de paiement. Si un paiement est tout de même lancé, le client voit This payment method is not available. Please choose another one. La vitrine PrestaShop ne sait pas que vous êtes connecté au back-office : le mode de paiement est donc aussi masqué pour vous. Vous pouvez configurer le module avant d'acheter une clé, mais pas le tester à l'étape de 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 l'assistance nécessitent un renouvellement. Le statut est vérifié automatiquement pendant que vous travaillez 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 la licence.
Dépannage
Kushki n'apparaît pas à l'étape de paiement : vérifiez que la licence est active, que Enable / Disable est activé et que le mode actuel dispose des deux identifiants marchands : les identifiants de test en mode test, les identifiants réels en mode réel. Vérifiez que la devise du panier est USD ou COP. Dans Payment > Preferences, vérifiez que le module est autorisé pour la devise du panier, le pays du client et le groupe du client. La page des réglages affiche un avertissement lorsque des identifiants manquent.
Le paiement a abouti, mais aucune commande n'a été créée : la réponse de l'API Kushki a été perdue, par exemple à cause d'un délai d'attente. Le webhook crée la commande pour de tels paiements. Dans la Kushki Console, vérifiez que l'URL du webhook est exactement celle affichée sous Webhook URL, pour le compte du mode que vous utilisez, et que la clé de signature de ce compte se trouve dans le champ correspondant (Test webhook signature ou Live webhook signature). Un débit approuvé sans montant et devise payés crée la commande dans Kushki payment on hold.
Le webhook répond Webhook signature not configured : aucune des deux signatures de webhook n'est définie. Collez la clé de signature dans les réglages.
Le webhook répond Invalid signature : la clé de signature appartient à un autre compte ou mode, ou la notification a été modifiée en cours de route.
Le webhook répond Order mismatch : la notification n'appartient pas à un débit de ce panier (clé de tentative ou transaction incorrecte). Rien n'est modifié.
Le webhook répond Busy, retry later : la commande était en cours de traitement par une autre requête au même moment, ou la commande n'a pas pu être créée (par exemple parce que le module est désactivé). Kushki peut renvoyer la notification. Les erreurs sont toujours écrites dans le journal.
L'URL du webhook affiche POST seulement dans le navigateur : c'est normal. L'URL n'accepte que les notifications de Kushki.
Le formulaire de carte ne se charge pas : le client voit Le formulaire de carte Kushki n'a pas pu être chargé. Veuillez recharger la page ou choisir un autre mode de paiement. Vérifiez l'identifiant marchand public du mode actuel.
Le client voit Cette option de paiement n'est pas disponible dans cette boutique. Veuillez payer par carte. : une option de paiement autre que la carte a été choisie dans le formulaire Kushki. Le module ne débite que les cartes.
Le client voit une erreur lors du paiement : activez le Debug log et consultez le champ Log sur la page du module. Un identifiant marchand privé incorrect ou manquant produit le message général indiquant que le paiement n'a pas pu être traité.
Le client voit Votre paiement a bien été reçu, mais la commande n'a pas pu être finalisée automatiquement : Kushki a approuvé le débit, mais PrestaShop n'a pas pu créer la commande. Le journal indique la raison. La prochaine tentative de paiement du même panier crée la commande sans nouveau débit.
Le remboursement échoue avec un message concernant le mode : le paiement a été effectué en mode test ou réel, et l'identifiant marchand privé de ce mode n'est pas renseigné. Saisissez-le et réessayez.
Le remboursement n'est pas proposé, avec le message « Aucun numéro de ticket Kushki trouvé pour cette commande » : la commande n'a pas de débit Kushki confirmé. Remboursez-la dans la Kushki Console.
Désinstallation
Allez dans Modules > Module Manager, ouvrez le menu à côté de VibeFox Kushki 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 les journaux sont supprimés. S'il est désactivé, tous les réglages sont conservés pour une future réinstallation. Les enregistrements de paiements Kushki (débits et remboursements) et le statut de commande Kushki payment on hold 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, leurs numéros de ticket Kushki et leurs ID de transaction.
Kushki est une marque appartenant à son titulaire. Ce module n'est ni affilié à Kushki, ni approuvé par elle.