VibeFox Khipu for WooCommerce — Aide

Prérequis

WordPress : 6.0 ou version ultérieure.

WooCommerce : 8.0 ou version ultérieure, installé et actif. Sans WooCommerce, l'extension refuse de s'activer.

PHP : 8.0 ou version ultérieure.

Devise de la boutique : peso chilien (CLP), peso argentin (ARS) ou sol péruvien (PEN). Le moyen de paiement est masqué au paiement lorsque la boutique, ou la commande sur la page Pay for order, utilise une autre devise.

Compte Khipu : vous avez besoin du Receiver ID (« Id de cobrador »), de la clé API et de la clé secrète (« llave ») de votre compte de recouvrement Khipu. Vous les trouverez dans votre compte Khipu, sous le profil marchand (khipu.com/merchant/profile). Les trois sont obligatoires : sans la clé secrète, aucun paiement ne peut être confirmé.

Site joignable : Khipu confirme les paiements en appelant votre boutique, le site doit donc être accessible depuis Internet (pas de mode maintenance, d'authentification de base ni de pare-feu bloquant Khipu).

Clé de licence VibeFox : achetée sur vibefox.net. Une clé fonctionne sur un seul 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_khipu_gateway dans /wp-content/plugins/ par FTP.

2. Cliquez sur Activate.

3. Ouvrez les réglages : WooCommerce > Settings > Payments > Khipu > Manage, ou cliquez sur Settings sous le nom de l'extension sur la page Plugins.

4. Saisissez votre clé de licence VibeFox dans le bloc de licence en haut de la page et cliquez sur Activate.

5. Saisissez le Receiver ID, la API key et la Secret key de votre compte de recouvrement Khipu (voir Configuration).

6. Activez Enable / Disable et enregistrez. Pour tester d'abord, utilisez les clés d'un compte développeur Khipu, puis remplacez-les par celles de votre compte de production.

Configuration

Tous les réglages se trouvent sur une seule page : WooCommerce > Settings > Payments > Khipu. Au-dessus des champs, la page vous avertit lorsque le Receiver ID, la clé API ou la clé secrète manque (Khipu n'est alors pas proposé au paiement) et lorsque la devise de la boutique n'est pas prise en charge. Dans la liste des moyens de paiement, Khipu est indiqué comme nécessitant une configuration tant que les trois clés ne sont pas saisies.

Général

Enable / Disable: Enable Khipu payments active ou désactive le moyen de paiement. Par défaut : désactivé.

Title: le nom du moyen de paiement que les clients voient au paiement. Par défaut : Khipu.

Description: le texte affiché sous le moyen de paiement au paiement. Par défaut : Pay by bank transfer with Khipu.

Compte Khipu

Copiez le Receiver ID, la clé API et la clé secrète depuis votre compte de recouvrement Khipu (khipu.com/merchant/profile). Khipu n'a pas de serveur sandbox distinct et l'extension n'a pas d'interrupteur de mode test. Pour tester, utilisez les clés d'un compte de recouvrement développeur (« desarrollo ») : il paie avec la banque de test DemoBank et aucun argent réel n'est déplacé. Passez aux clés de votre compte de recouvrement de production au moment de la mise en ligne.

Receiver ID: votre identifiant de recouvrement Khipu (« cobrador »). Les paiements d'autres comptes Khipu sont rejetés.

API key: utilisée pour créer les paiements et pour vérifier chaque paiement auprès de Khipu.

Secret key: utilisée pour vérifier la signature (HMAC-SHA256) des notifications de paiement Khipu. Sans elle, aucun paiement ne peut être confirmé.

Notifications de paiement

Khipu confirme les paiements en appelant l'URL de notification indiquée dans cette section des réglages. Elle ressemble à https://your-site/wc-api/webhook_wc_khipu/. L'URL est envoyée automatiquement avec chaque paiement, il n'y a donc rien à configurer dans votre compte Khipu, mais l'URL doit être joignable depuis Internet.

Chaque notification doit porter une signature valide créée avec votre Secret key. Les notifications sans signature valide sont rejetées. L'extension demande ensuite à Khipu le statut du paiement et agit selon ce que Khipu rapporte :

done: le virement a été confirmé. La commande est marquée comme payée après vérification du Receiver ID, de la commande et du montant.

done, reversed: le paiement a été annulé. Une commande non payée n'est pas marquée comme payée. Une commande payée reçoit une note et son statut n'est pas modifié.

pending or verifying: le virement n'est pas encore définitif. L'extension répond « retry later » et Khipu renvoie la notification.

Status after payment: le statut de la commande une fois que Khipu a confirmé le paiement. Le statut est appliqué immédiatement, avec un seul changement de statut et un seul envoi d'e-mails.

Processing: laisse WooCommerce décider (par défaut). Les commandes virtuelles téléchargeables sont automatiquement terminées.

Completed: toute commande payée passe à Terminée.

Avancé

Debug log: Log API calls and notifications dans WooCommerce > Status > Logs, source wcp_khipu_gateway. Les erreurs sont toujours journalisées. Les clés et les données du payeur ne sont jamais écrites. Par défaut : désactivé.

Delete data on uninstall: Remove the gateway settings and logs when the plugin is deleted. Les données de commande (ID de paiement Khipu dans les commandes) sont toujours conservées. Par défaut : désactivé.

Paiement

Le client choisit le moyen de paiement (par défaut Khipu) et valide sa commande. L'extension crée un paiement Khipu pour le total de la commande dans la devise de celle-ci, avec le numéro de commande, le nom de la boutique et les articles commandés, puis redirige le client vers la page de paiement Khipu. L'e-mail de facturation est transmis à Khipu lorsqu'il est valide. Sur la page Khipu, le client paie par virement bancaire depuis sa propre banque et choisit parmi les types de virement proposés par Khipu.

Après avoir payé, le client revient sur la page de confirmation de commande de votre boutique. La commande n'est marquée comme payée qu'après confirmation du virement par Khipu : par la notification signée, ou par une demande de statut à Khipu lorsque le client ouvre la page de confirmation de commande. Le retour en lui-même ne marque jamais une commande comme payée. Tant que le virement n'est pas confirmé, la page affiche Khipu is confirming your bank transfer. Your order will be updated automatically as soon as Khipu confirms the payment, and you will receive an e-mail.

Si le client quitte la page Khipu sans payer, il arrive sur la page Pay for order avec le message The Khipu payment was not completed. You can try again or choose another payment method. Une nouvelle tentative supprime le paiement Khipu précédent non payé, l'ancien lien ne peut donc plus être payé. Si Khipu a déjà reçu le paiement précédent, la commande est finalisée et aucun nouveau paiement n'est créé. Si le virement précédent est encore en cours de vérification, le client voit Your previous Khipu payment for this order is still being verified by the bank. Please wait a few minutes before paying again.

Si la gestion des stocks est activée, le paiement Khipu expire en même temps que le délai Hold stock (minutes) de WooCommerce, le client ne peut donc pas payer une commande déjà annulée.

Si Khipu ne peut pas créer le paiement, le client voit un court message, par exemple Khipu could not create the payment for this order. Please check your billing details and try again, or contact the store. ou Khipu is temporarily unavailable. Please try again in a few minutes. Les détails sont écrits dans le journal.

Le moyen de paiement fonctionne sur le paiement classique, sur le bloc Checkout et sur la page Pay for order. Il est compatible avec le stockage haute performance des commandes (HPOS) de WooCommerce.

L'extension ne prend en charge que les paiements ponctuels par virement bancaire. Les remboursements depuis WooCommerce ne sont pas pris en charge et elle ne gère ni abonnements, ni moyens de paiement enregistrés, ni préautorisations.

Commandes

Statuts de commande

Pending payment: le client a été envoyé vers Khipu et n'a pas encore payé, ou Khipu n'a pas encore confirmé le virement. La note de commande indique l'ID de paiement Khipu.

Processing or Completed: Khipu a confirmé le paiement. Le statut suit Status after payment. La note de commande indique l'ID de paiement Khipu, et l'ID de transaction est l'ID de paiement Khipu.

On hold: Khipu a signalé un paiement dont le montant ou la devise ne correspond pas à la commande, ou le paiement est arrivé après l'annulation de la commande (par exemple après le délai de réservation du stock). La note de commande l'explique. Vérifiez le paiement dans votre compte Khipu et finalisez la commande ou remboursez le client.

Si un paiement arrive pour une commande déjà payée ou clôturée après paiement, la commande n'est pas modifiée. Une note vous demande de le rembourser au client s'il s'agit d'un second paiement.

Remboursements

Les remboursements ne sont pas envoyés à Khipu depuis WooCommerce. Remboursez le client depuis votre compte Khipu ou par virement bancaire, puis enregistrez le remboursement manuellement dans WooCommerce.

Clé de licence

L'extension fonctionne avec une clé de licence VibeFox provenant de vibefox.net. Le bloc de licence se trouve en haut de WooCommerce > Settings > Payments > Khipu. 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, et votre domaine. Utilisez Check now pour vérifier à nouveau le statut, Change key pour saisir une autre clé et Remove key pour la supprimer de ce site. Le lien Manage licenses and domains in your account ouvre votre compte vibefox.net.

Une clé fonctionne sur un seul domaine. Supprimer 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, Khipu 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 boutique connectés voient toujours le moyen 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 Plugins et sur les pages WooCommerce. Les commandes existantes ne sont pas affectées : les paiements déjà lancés sont toujours confirmés.

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

Khipu n'apparaît pas au paiement : vérifiez que la licence est active, que Enable / Disable est activé et que le Receiver ID, la API key et la Secret key sont bien tous saisis. La devise de la boutique doit être CLP, ARS ou PEN. La page des réglages affiche un avertissement lorsqu'il manque quelque chose.

Le paiement a abouti, mais la commande reste En attente de paiement : Khipu confirme un virement après vérification par la banque. La commande est mise à jour lorsque la notification Khipu arrive ou lorsque le client ouvre la page de confirmation de commande. Vérifiez que votre site est joignable depuis Internet à l'URL de notification indiquée dans les réglages (pas de mode maintenance, d'authentification de base ni de pare-feu bloquant Khipu), et consultez WooCommerce > Status > Logs, source wcp_khipu_gateway.

La notification renvoie « Secret key not configured » : la Secret key est vide. Saisissez-la. Khipu renvoie la notification.

La notification renvoie « Invalid signature », « Missing signature » ou « Malformed signature » : la Secret key ne correspond pas au compte de recouvrement dont vous utilisez les clés, ou la requête ne provient pas de Khipu.

La notification renvoie « Payment does not belong to this order » : le paiement a été effectué vers un autre Receiver ID ou pour une autre commande. Vérifiez le Receiver ID.

La notification renvoie « Payment not final yet » ou « Verification unavailable » : le virement est encore en cours de vérification, ou Khipu n'a pas pu être joint. Khipu renvoie la notification.

La commande est En attente : lisez la note de commande. Le montant ou la devise ne correspondait pas à la commande, ou le paiement est arrivé après l'annulation de la commande.

Le client voit « Khipu payments are not available right now » : la clé API est absente ou erronée. Vérifiez les clés dans votre compte Khipu.

Le bloc de licence affiche une erreur : suivez le message du 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 ne peut pas être joint, l'extension continue de fonctionner avec le dernier statut connu.

Si votre compte Khipu accepte une autre devise, par exemple EUR pour Khipu Espagne, les développeurs peuvent l'ajouter avec le filtre wc_khp_supported_currencies.

Désinstallation

Les données sont toutes conservées lors de la désactivation de l'extension. Pour la supprimer, désactivez-la et 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 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 leurs ID de transaction.

Khipu est une marque de son propriétaire respectif. Cette extension n'est ni affiliée à Khipu, ni approuvée par Khipu.