VibeFox Khipu for PrestaShop — Aide

Prérequis

PrestaShop : 8.0 à 9.x.

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

Devise : peso chilien (CLP), peso argentin (ARS) ou sol péruvien (PEN). Pour les paniers dans d'autres devises, le moyen de paiement est masqué lors du paiement.

Compte Khipu : vous avez besoin du Receiver ID (« Id de cobrador »), de l'API key et de la Secret key de votre compte de recouvrement Khipu. Vous les trouvez dans votre compte Khipu, sous le profil marchand (khipu.com/merchant/profile). Les trois sont obligatoires : sans la Secret key, aucun paiement ne peut être confirmé. Rien n'est à configurer dans le compte Khipu.

Boutique accessible : Khipu confirme les paiements en appelant votre boutique. L'URL de notification doit donc être accessible depuis Internet, sans protection par mot de passe ni pare-feu bloquant Khipu. Le mode maintenance de la boutique ne la bloque pas.

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 Khipu Gateway 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, puis cliquez sur Activate (voir Clé de licence).

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

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

À l'installation, le module crée le statut de commande Khipu payment on hold. PrestaShop propose un nouveau module de paiement pour toutes les devises, tous les pays et tous les groupes de clients. Vous pouvez les restreindre dans Payment > Preferences.

Configuration

Tous les réglages se trouvent sur la page du module : Modules > Module Manager > VibeFox Khipu Gateway > Configure. Chaque section a son propre bouton Save, qui enregistre la page entière. Au-dessus des champs, la page vous avertit lorsque le Receiver ID, l'API key ou la Secret key manque (Khipu n'est alors pas proposé au paiement) et lorsque la devise par défaut de la boutique n'est pas prise en charge par Khipu.

Khipu

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 lors du paiement. C'est aussi le nom du moyen de paiement enregistré dans la commande. Par défaut : Khipu. Obligatoire.

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

Compte Khipu

Copiez le Receiver ID, l'API key et la Secret key depuis votre compte de recouvrement Khipu (khipu.com/merchant/profile). Khipu n'a pas de serveur de test distinct, et le module n'a pas d'interrupteur de mode test. Pour tester, utilisez les clés d'un compte de recouvrement développeur (« desarrollo ») : il paie via 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 lorsque vous ouvrez la boutique.

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

API key : sert à créer les paiements et à vérifier chaque paiement auprès de Khipu.

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

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

Clear saved secrets : cochez API key ou Secret key et cliquez sur Save pour la supprimer. Un champ vide conserve la valeur enregistrée.

Notifications de paiement

Notification URL : Khipu confirme les paiements en appelant l'URL affichée ici. Avec des URL conviviales, elle ressemble à https://your-shop/module/wcp_khipu_gateway/webhook, éventuellement avec un code de langue. L'URL est transmise automatiquement avec chaque paiement : rien n'est à configurer dans votre compte Khipu, mais l'URL doit être accessible depuis Internet.

Chaque notification doit porter une signature valide, créée avec votre Secret key. Les notifications sans signature valide sont rejetées. Le module ne fait jamais confiance au contenu de la notification : il demande à Khipu le statut du paiement et agit selon ce que Khipu indique :

done : le virement est confirmé. La commande est créée après les vérifications du Receiver ID, du panier et du montant.

done, reversed : le paiement a été annulé. Aucune commande n'est créée pour un panier non payé. Une commande payée reçoit une note, et son statut ne change pas.

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

Status after payment : le statut de la commande une fois que Khipu confirme le paiement. Le statut est appliqué immédiatement, avec un seul changement de statut.

Processing : la commande reçoit Payment accepted (par défaut).

Completed : la commande reçoit Delivered.

Avancé

Debug log : enregistre les appels à l'API et les notifications dans logs/wc_khp_debug.log.php, dans le dossier du module. Le fichier ne peut pas être ouvert depuis le web. Les erreurs sont toujours journalisées, même lorsque l'interrupteur est désactivé. Les clés et les données du payeur ne sont jamais écrites. 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 données de commande (identifiants de paiement Khipu des commandes) sont toujours conservées. Par défaut : désactivé.

Paiement

Lors du paiement, le client choisit le moyen de paiement (par défaut Khipu) avec sa description et confirme la commande. Le module crée un paiement Khipu pour le total du panier dans la devise du panier et envoie le client sur la page de paiement Khipu. Chez Khipu, le paiement apparaît sous Order # avec le numéro du panier et le nom de la boutique, ainsi que la liste des produits. L'e-mail du client est transmis à Khipu lorsqu'il est valide. Sur la page Khipu, le client paie par virement bancaire depuis sa propre banque. Aucune commande n'existe encore à ce stade.

Après le paiement, le client revient sur votre boutique. La commande n'est marquée comme payée qu'après confirmation de Khipu : par la notification signée, ou par une demande de statut adressée à Khipu lorsque le client revient. Le retour lui-même ne marque jamais rien comme payé. Une fois la commande créée, le client voit la page standard de confirmation de commande. Si la banque vérifie encore le virement ou si Khipu est injoignable, une page Payment confirmation affiche Khipu is confirming your bank transfer. Your order will be created automatically as soon as Khipu confirms the payment, and you will receive an e-mail. avec les boutons Check again et Back to checkout. Si le dernier paiement Khipu du panier ne peut pas lui être associé (par exemple, il appartient à un autre Receiver ID), le client revient au paiement avec le message We could not match this payment to an order. If you paid, please contact us.

Si le client quitte la page Khipu sans payer, ou si le paiement n'a pas abouti, il revient au paiement avec le message The Khipu payment was not completed. You can try again or choose another payment method. Le panier est conservé. Une nouvelle tentative supprime le paiement Khipu précédent non payé, afin que l'ancien lien ne puisse plus être réglé. Si Khipu a déjà reçu le paiement précédent, la commande est créée et aucun nouveau paiement n'est effectué. 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 Khipu ne peut pas créer le paiement, le client reste au paiement avec un bref 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 inscrits dans le journal.

La notification fonctionne lorsque la boutique est en mode maintenance et n'est pas bloquée par la restriction par pays de votre boutique.

Le module ne gère que les paiements ponctuels par virement bancaire. Les remboursements ne sont pas envoyés à Khipu depuis PrestaShop, et le module ne gère ni les abonnements, ni les moyens de paiement enregistrés, ni les préautorisations. Les paiements non réglés ne sont pas liés à une réservation de stock.

Commandes

Statuts de commande

No order yet : le client a été envoyé vers Khipu et n'a pas payé, ou Khipu n'a pas encore confirmé le virement. Seul le panier existe.

Payment accepted or Delivered : Khipu a confirmé le paiement. Le statut suit Status after payment. Le paiement est enregistré avec l'identifiant de paiement Khipu comme identifiant de transaction, et une note affiche Khipu payment verified. Payment ID: avec l'identifiant de paiement et le montant.

Khipu payment on hold : Khipu a confirmé un paiement dont le montant ou la devise ne correspond pas à la commande (par exemple, le panier a été modifié après le début du paiement), ou le paiement est arrivé après l'annulation de la commande. Le montant réellement reçu est enregistré sur la commande (pas lorsque la devise diffère), et une note l'explique. Vérifiez le paiement dans votre compte Khipu, puis finalisez la commande ou remboursez le client. Si un paiement ultérieur du bon montant arrive pour le même panier, la commande passe au statut payé.

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 invite à rembourser le client s'il s'agit d'un second paiement. Si Khipu signale un paiement payé comme annulé, la commande reçoit une note et son statut ne change pas.

Bloc de paiement Khipu

La page de commande affiche un bloc Khipu payment avec les tentatives de paiement Khipu du panier de la commande (date, montant, identifiant de paiement Khipu, statut et résultat Khipu), un avertissement Manual review tant que la commande est en Khipu payment on hold, et les Khipu notes de la commande. Le bloc est en lecture seule.

Remboursements

Les remboursements ne sont pas envoyés à Khipu depuis PrestaShop, car Khipu ne propose pas de remboursement via son API. Remboursez le client depuis votre compte Khipu ou par virement bancaire, puis enregistrez le remboursement manuellement dans PrestaShop.

Clé de licence

Le module fonctionne avec une clé de licence VibeFox depuis vibefox.net. Le bloc de licence License — VibeFox Khipu Gateway est le premier bloc de Modules > Module Manager > VibeFox Khipu Gateway > 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) et 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. Plus bas figurent la ligne Product: presta-payment-khipu 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, Khipu 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 vitrine PrestaShop ne sait pas que vous êtes connecté au back-office : le moyen de paiement est donc masqué pour vous aussi. 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, dans l'onglet Alerts. Les commandes existantes ne sont pas affectées : les paiements déjà lancés sont toujours confirmés.

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 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 licence.

Dépannage

Khipu n'apparaît pas lors du paiement : vérifiez que la licence est active, que Enable / Disable est activé et que le Receiver ID, l'API key et la Secret key sont tous saisis. La devise du panier doit être CLP, ARS ou PEN. La page des 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 : Khipu confirme un virement après que la banque l'a vérifié. La commande est créée à l'arrivée de la notification Khipu ou lorsque le client clique sur Check again. Vérifiez que votre boutique est accessible depuis Internet à l'URL indiquée dans Notification URL (sans protection par mot de passe ni pare-feu bloquant Khipu), et consultez le champ Log de la page du module.

La notification répond Secret key not configured : la Secret key est vide. Saisissez-la. Khipu renvoie la notification.

La notification répond Invalid signature, Missing signature ou Malformed signature : la Secret key n'appartient pas au compte de recouvrement dont vous utilisez les clés, ou la requête ne provient pas de Khipu.

La notification répond Order not found ou Payment does not belong to this order : le paiement a été effectué vers un autre Receiver ID ou pour un autre panier. Vérifiez le Receiver ID.

La notification répond 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 notification répond Busy, retry later ou Order could not be created, retry later : la commande était en cours de confirmation par une autre requête au même moment, ou la commande n'a pas pu être créée (par exemple, le module est désactivé). Khipu renvoie la notification. La raison figure dans le journal.

La commande est en Khipu payment on hold : lisez les notes du bloc Khipu payment. 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 » : l'API key est absente ou incorrecte. Vérifiez les clés dans votre compte Khipu.

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

Désinstallation

Allez dans Modules > Module Manager, ouvrez le menu à côté de VibeFox Khipu Gateway 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 tentatives de paiement Khipu et le statut de commande Khipu payment on hold sont toujours conservés. Les commandes existantes conservent leurs notes de paiement et leurs identifiants de transaction.

Khipu est une marque de son propriétaire respectif. Ce module n'est ni affilié à Khipu, ni approuvé par Khipu.