VibeFox Kushki for WooCommerce — Aide
Prérequis
WordPress : 6.0 ou ultérieur.
WooCommerce : 8.0 ou ultérieur, installé et actif. L'extension refuse de s'activer sans lui.
PHP : 8.0 ou ultérieur.
Devise de la boutique : USD (Équateur) ou COP (Colombie). Pour les autres devises, le mode de paiement est masqué au paiement.
HTTPS : Kushki exige que le paiement soit servi en HTTPS en mode réel.
Compte Kushki : vous avez besoin des Merchant ID 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).
Clé de licence VibeFox : achetée sur vibefox.net. Une clé fonctionne sur un domaine.
Installation
1. Dans WordPress, allez dans Plugins > Add New > Upload Plugin, choisissez le fichier ZIP de l'extension et cliquez sur Install Now. Vous pouvez aussi téléverser le dossier wcp_kushki_payment dans /wp-content/plugins/ par FTP.
2. Cliquez sur Activate.
3. Ouvrez les réglages : WooCommerce > Settings > Payments > Kushki > Manage, ou cliquez sur Settings sous le nom de l'extension sur la page Extensions.
4. Saisissez votre clé de licence VibeFox dans le bloc de licence en haut de la page et cliquez sur Activate.
5. Saisissez les Merchant ID publics et privés de test et laissez Test mode activé. Vous pouvez aussi configurer le webhook dans la Kushki Console et coller sa clé de signature (voir Configuration).
6. Activez Enable / Disable et passez une commande test. Une fois prêt, saisissez les Merchant ID réels (et la signature du webhook réel) puis décochez Test mode.
Configuration
Tous les réglages se trouvent sur une seule page : WooCommerce > Settings > Payments > Kushki. Au-dessus des champs, la page vous avertit lorsque le mode de paiement est activé mais que les Merchant ID du mode actuel sont absents (le mode de paiement est alors masqué au paiement), lorsque la devise de la boutique n'est pas prise en charge, 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 Test mode is on: the Kushki test environment is used, no real money is charged. Lorsque vous enregistrez avec le mode de paiement activé mais sans les Merchant ID du mode actuel, une erreur vous le rappelle. Les espaces autour des identifiants sont supprimés à l'enregistrement.
Général
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 au paiement. Par défaut : Credit / debit card (Kushki).
Description: le texte affiché au-dessus du formulaire de carte au 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 Merchant ID 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: Use the Kushki test (UAT) environment fait basculer ensemble les Merchant ID, le formulaire de carte et l'API vers l'environnement de test Kushki. Aucun argent réel n'est débité, et un badge TEST MODE s'affiche au paiement. Par défaut : activé. Décochez-le pour encaisser de vrais paiements.
Test Public Merchant ID: le Merchant ID public de votre compte de test Kushki. Il charge le formulaire de carte.
Test Private Merchant ID: le Merchant ID privé de votre compte de test Kushki. Il est utilisé côté serveur pour les débits et les remboursements.
Live Public Merchant ID: le Merchant ID public de votre compte de production Kushki.
Live Private Merchant ID: le Merchant ID privé de votre compte de production Kushki. Gardez-le secret.
Webhook (recommandé)
Les paiements sont confirmés immédiatement par la réponse de l'API Kushki, le webhook n'est donc pas obligatoire. Il confirme en plus les paiements dont la réponse a été perdue (par exemple après un délai dépassé) et signale les annulations et remboursements effectués dans la Kushki Console. Dans la Kushki Console (Webhooks), ajoutez l'URL affichée dans cette section des réglages pour les paiements par carte. Elle ressemble à https://your-site/wc-api/webhook_kushki_p/. Faites-le pour le compte de test et pour le compte de production.
L'extension gère 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.
Les webhooks sans signature valide sont rejetés. 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: Log API calls and webhooks écrit les requêtes et les webhooks Kushki dans WooCommerce > Status > Logs, source wcp_kushki_payment. Les erreurs sont toujours journalisées. Les journaux ne contiennent jamais de Merchant ID, de jetons de carte ni d'adresses e-mail de clients. Par défaut : désactivé.
Delete data on uninstall: lorsqu'il est activé, la suppression de l'extension efface les réglages et les journaux. Les commandes et leurs références Kushki sont conservées. Par défaut : désactivé.
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 de la commande dans la devise de la commande. Sur la page Pay for order, le formulaire utilise le total de la commande. Le client saisit la carte, choisit les paiements en plusieurs fois si le formulaire Kushki les propose, et appuie sur le bouton de paiement à l'intérieur du formulaire Kushki.
Sur le paiement classique, le bouton Place order de WooCommerce est masqué tant que Kushki est sélectionné : une fois la carte acceptée, la commande est envoyée automatiquement. Sur le bloc Paiement, le client appuie également sur le bouton de paiement à l'intérieur du formulaire Kushki. S'il tente de valider la commande sans cela, le message Please enter your card details in the Kushki form and press its pay button. s'affiche.
Votre boutique débite ensuite la carte côté serveur. La commande n'est marquée payée que lorsque Kushki la confirme avec un numéro de ticket, et le client accède directement à la page de confirmation de commande. Si Kushki signale un montant ou une devise approuvés, ils sont comparés à la commande.
Si la carte est refusée, le client voit Your payment was declined avec le motif fourni par Kushki et peut essayer une autre carte dans le même formulaire. En cas de problème réseau, de clé ou de serveur, le client voit The payment could not be processed right now. Please try again in a moment or choose another payment method. Le motif technique est ajouté aux notes de commande et au journal. Un second clic pendant le traitement d'un paiement affiche A payment for this order is already being processed. Please wait a moment and check your order status.
Le mode 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). Le 3-D Secure, les règles antifraude et les paiements en plusieurs fois proposés se configurent dans la Kushki Console.
L'extension ne gère que les paiements par carte en une étape. Elle ne prend en charge ni remboursements partiels, ni cartes enregistrées, ni abonnements, ni Add payment method, ni paiements en espèces, virements bancaires (PSE) ou paiements par carte de débit avec redirection, ni autorisation et capture séparées.
Commandes et remboursements
Statuts de commande
Pending payment: la commande a été créée et la carte n'a pas encore été débitée.
Processing: Kushki a confirmé le débit (par la réponse de l'API ou par le webhook). Les commandes ne contenant que des produits virtuels téléchargeables passent à Completed, la valeur par défaut de WooCommerce. La note de commande indique le mode, le numéro de ticket Kushki et la référence. L'ID de transaction est la référence de transaction Kushki (ou le numéro de ticket).
On hold: Kushki a renvoyé un succès sans numéro de ticket, ou a signalé un montant ou une devise différents de ceux de la commande. La note de commande l'explique. Vérifiez la transaction dans la Kushki Console, puis exécutez la commande ou remboursez le paiement.
Failed: la carte a été refusée ou le débit n'a pas pu être effectué. La note de commande indique le code et le message Kushki. Le client peut payer à nouveau.
Si un webhook 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 invite à vérifier un double débit et à le rembourser dans la Kushki Console. Un webhook de l'environnement de test pour une commande réelle (ou l'inverse) est ignoré avec une note.
Remboursements
Ouvrez la commande, cliquez sur Refund, saisissez le total complet de la commande et cliquez sur Refund via Credit / debit card (Kushki) (le bouton affiche votre Title). Kushki rembourse la totalité du paiement, seuls les remboursements complets sont donc acceptés. Pour un montant partiel, l'extension affiche Kushki refunds the full payment only. Enter the full order total as the refund amount, or make a partial refund manually in the Kushki Console. Un paiement ne peut être remboursé qu'une seule fois.
Le remboursement est envoyé dans le mode où le paiement a été effectué (test ou réel), le Merchant ID privé de ce mode doit donc être renseigné. Si Kushki n'accepte pas le remboursement, WooCommerce affiche l'erreur et aucun remboursement n'est enregistré. Un remboursement réussi est ajouté aux notes de commande avec le ticket de remboursement Kushki.
Les annulations et les remboursements effectués dans la Kushki Console arrivent par webhook et sont ajoutés aux notes de commande. Ils ne sont pas enregistrés automatiquement comme remboursements WooCommerce.
Clé de licence
L'extension fonctionne avec une clé de licence VibeFox obtenue sur vibefox.net. Le bloc de licence se trouve en haut de WooCommerce > Settings > Payments > Kushki. Collez la clé dans License key et cliquez sur Activate. Le bloc affiche le statut, par exemple la date jusqu'à laquelle la licence est active, ainsi que votre domaine. Utilisez Check now pour vérifier à nouveau le statut, Change key pour saisir une autre clé et Remove key pour la retirer de ce site. Le lien Manage licenses and domains in your account ouvre votre compte vibefox.net.
Une clé fonctionne sur un domaine. Retirer la clé d'un site ne libère pas son emplacement de domaine. Libérez l'emplacement dans votre compte vibefox.net.
Sans clé active, Kushki n'est pas proposé aux clients au paiement. Si un paiement est tout de même lancé, le client voit This payment method is not available. Please choose another one. Les gestionnaires de la boutique connectés voient toujours le mode de paiement, marqué (unlicensed — visible to admins only), afin que vous puissiez configurer et tester l'extension avant d'acheter une clé. Un rappel apparaît sur la page Extensions et sur les pages WooCommerce. Les commandes existantes ne sont pas affectées : les webhooks sont toujours traités et les remboursements fonctionnent.
Lorsqu'une licence expire, l'extension continue de fonctionner, mais les mises à jour et le support nécessitent un renouvellement. Le statut est vérifié à nouveau automatiquement en arrière-plan.
Dépannage
Kushki n'apparaît pas au paiement : vérifiez que la licence est active, que Enable / Disable est activé et que le mode actuel dispose des deux Merchant ID : les identifiants de test en mode test, les identifiants réels en mode réel. Vérifiez que la devise de la boutique (ou la devise de la commande sur la page Pay for order) est USD ou COP. La page des réglages affiche un avertissement pour chacun de ces problèmes.
Le paiement a été effectué, mais la commande est Failed ou reste en Pending payment : la réponse de l'API Kushki a été perdue, par exemple à cause d'un délai dépassé. Le webhook confirme ces paiements. Dans la Kushki Console, vérifiez que l'URL du webhook correspond exactement à celle affichée dans les réglages, 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 le montant et la devise payés met plutôt la commande en attente.
Le webhook répond Webhook signature not configured : aucune signature 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 à cette commande (clé de commande ou transaction incorrecte). La commande n'est pas modifiée.
Le webhook répond Busy, retry later : la commande était traitée par une autre requête au même moment. Kushki peut renvoyer la notification.
Le formulaire de carte ne se charge pas : le client voit The Kushki card form could not be loaded. Please reload the page or choose another payment method. Vérifiez le Merchant ID public du mode actuel.
Le client voit This payment option is not available in this store. Please pay by card. : une option de paiement autre que la carte a été choisie dans le formulaire Kushki. L'extension n'encaisse que les cartes.
Le client voit une erreur lors du paiement : ouvrez les notes de commande ou activez le Debug log et consultez WooCommerce > Status > Logs, source wcp_kushki_payment. Un Merchant ID privé erroné ou absent donne le message général indiquant que le paiement n'a pas pu être traité.
Le remboursement échoue avec un message sur le mode : le paiement a été effectué en mode test ou réel, et le Merchant ID privé de ce mode n'est pas renseigné. Saisissez-le et réessayez.
Le remboursement échoue avec No Kushki ticket number found for this order : la commande n'a pas de débit Kushki confirmé. Remboursez-la dans la Kushki Console.
Autres devises : les développeurs peuvent modifier la liste des devises avec le filtre kushki_p_supported_currencies, à leurs propres risques. La devise doit être activée sur votre compte Kushki.
Le bloc de licence affiche une erreur : suivez le message affiché dans le bloc. Par exemple, 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é pour le nouveau domaine. Si le serveur de licences est injoignable, l'extension continue de fonctionner avec le dernier statut connu.
Désinstallation
La désactivation de l'extension conserve toutes les données. Pour la supprimer, désactivez-la puis supprimez-la sur la page Plugins. La clé de licence et le statut de licence de cette extension sont toujours supprimés. Les réglages du mode de paiement et les journaux ne sont supprimés que si Delete data on uninstall était activé. Sinon, ils restent en place pour une réinstallation ultérieure. Les commandes existantes conservent leurs notes de paiement, leurs numéros de ticket Kushki et leurs ID de transaction.
Kushki est une marque de son propriétaire respectif. Cette extension n'est ni affiliée à Kushki ni approuvée par Kushki.