VibeFox Khipu for OpenCart — Aide

Prérequis

OpenCart : 3.0.x (testé sur 3.0.5.0) ou 4.0.2 et ultérieur (testé sur 4.1.0.3).

PHP : 8.0 ou ultérieur.

Devise : peso chilien (CLP), peso argentin (ARS) ou sol péruvien (PEN). La devise doit exister dans System > Localisation > Currencies. Khipu n'est proposé que lorsque le client paie dans l'une de ces devises ; pour les autres devises, le mode de paiement est masqué à la commande.

Compte Khipu : vous avez besoin de l'identifiant du récepteur (« Id de cobrador »), de la clé d'API et de la clé secrète de votre compte d'encaissement Khipu. Vous les trouvez dans votre compte Khipu, sous le profil marchand (khipu.com/merchant/profile). Les trois sont obligatoires : sans elles, Khipu n'est pas proposé à la commande, et sans la clé secrète 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 pour un seul domaine.

Installation

Le téléchargement est un fichier zip unique contenant les paquets des deux versions d'OpenCart. Décompressez-le sur votre ordinateur. Il contient README.txt, le paquet OpenCart 3 wcp_khipu_gateway-oc3-(version).ocmod.zip et le paquet OpenCart 4 wcp_khipu_gateway.ocmod.zip. N'installez que le paquet correspondant à votre version d'OpenCart. La clé de licence est la même pour les deux versions.

OpenCart 3

1. Dans l'administration, allez dans Extensions > Installer, cliquez sur Upload et choisissez le fichier wcp_khipu_gateway-oc3-(version).ocmod.zip. L'extension ne comporte aucune modification OCMOD, il n'est donc pas nécessaire de rafraîchir Extensions > Modifications. Au lieu de l'installateur, vous pouvez aussi copier le contenu du dossier upload de ce paquet dans le dossier racine de votre boutique.

2. Allez dans Extensions > Extensions et choisissez le type Payments. Repérez VibeFox Khipu Gateway et cliquez sur Install (le bouton vert +). Votre utilisateur administrateur doit avoir le droit de modifier la liste des extensions de paiement.

3. Cliquez sur Edit (le bouton en forme de crayon) pour ouvrir la page des réglages. Collez votre clé de licence VibeFox dans License key, dans le bloc de licence en haut de la page, puis cliquez sur Activate (voir License key).

4. Saisissez le Receiver ID, la API key et la Secret key de votre compte d'encaissement 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.

OpenCart 4

1. Dans l'administration, allez dans Extensions > Installer, cliquez sur Upload et choisissez le fichier wcp_khipu_gateway.ocmod.zip. Ne renommez pas le fichier : OpenCart 4 prend le code de l'extension dans le nom du fichier, et un paquet renommé ne fonctionne pas.

2. Le paquet apparaît dans la liste des extensions installées sur la même page. Cliquez sur Install (le bouton vert +) à côté.

3. Allez dans Extensions > Extensions et choisissez le type Payments. Repérez VibeFox Khipu Gateway, cliquez sur Install (le bouton vert +), puis sur Edit (le bouton en forme de crayon).

4. Saisissez la clé de licence et les clés Khipu comme aux étapes 3 à 5 pour OpenCart 3. La page de configuration et ses champs sont identiques dans les deux versions. Seule l'URL de notification est différente (voir Notifications de paiement).

Une nouvelle installation démarre avec le mode de paiement désactivé.

Configuration

Tous les réglages se trouvent sur la page de l'extension : Extensions > Extensions > Payments > VibeFox Khipu Gateway > Edit. Les sections sont listées à gauche ; le bouton Save situé sous la liste enregistre la page entière. Au-dessus des réglages, la page vous avertit lorsque le Receiver ID, l'API key ou la Secret key est manquant (Khipu n'est alors pas proposé à la commande) et lorsque la devise par défaut de la boutique n'est pas prise en charge par Khipu (Khipu n'est alors proposé que lorsque le client paie en CLP, ARS ou PEN). Sans le droit de modifier l'extension, la page affiche les réglages mais ne peut pas les enregistrer.

À l'enregistrement, Title ne doit pas être vide ni dépasser 128 caractères, Sort Order doit être un nombre entier, Total doit être un nombre égal ou supérieur à 0, et la zone géographique et les statuts de commande doivent exister. Sinon, rien n'est enregistré et la page indique le champ concerné. Les clés manquantes n'empêchent pas l'enregistrement.

Khipu

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

Title : le nom du mode de paiement que voit le client à la commande. C'est aussi le nom du mode de paiement enregistré dans la commande. Par défaut : Khipu. Obligatoire, de 1 à 128 caractères.

Description : le texte affiché au client à l'étape Confirm Order, au-dessus du bouton de confirmation. Par défaut : Payez par virement bancaire avec Khipu.

Sort Order : la position de Khipu parmi les modes de paiement à la commande. Laissez le champ vide ou saisissez un nombre entier.

Geo Zone : proposer Khipu uniquement pour les adresses de paiement de la zone géographique sélectionnée. Par défaut : All zones. Les zones géographiques se configurent dans System > Localisation > Geo Zones.

Total : le total de la commande, dans la devise par défaut de la boutique, que doit atteindre une commande pour que Khipu soit proposé. Laissez le champ vide pour proposer Khipu quel que soit le montant.

Compte Khipu

Copiez le Receiver ID, l'API key et la Secret key depuis votre compte d'encaissement Khipu (la section renvoie vers khipu.com/merchant/profile). Khipu n'a pas de serveur sandbox séparé, et l'extension n'a pas d'interrupteur de mode test. Pour tester, utilisez les clés d'un compte d'encaissement 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 d'encaissement de production lorsque vous passez en production.

Receiver ID : votre identifiant de récepteur (« cobrador ») Khipu. Les paiements vers 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é.

Les clés 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 pour la modifier. Pour supprimer une clé enregistrée, cochez Clear the saved value sous le champ et cliquez sur Save.

Notifications de paiement

Notification URL : Khipu confirme les paiements en appelant l'URL affichée ici. Sous OpenCart 3, elle ressemble à https://your-store/index.php?route=extension/payment/wcp_khipu_gateway/webhook, et sous OpenCart 4 à https://your-store/index.php?route=extension/wcp_khipu_gateway/payment/wcp_khipu_gateway.webhook. Elle est construite à partir de l'adresse de la vitrine de votre installation OpenCart. 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 accessible depuis Internet.

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

done : le virement est confirmé. La commande reçoit son statut après les contrôles du Receiver ID, de la tentative de paiement et du montant.

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

pending ou 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 que reçoit la commande une fois que Khipu confirme le paiement. Le statut est défini immédiatement, en un seul changement de statut.

Processing : la commande reçoit le Paid Order Status (par défaut).

Completed : la commande reçoit le Complete Order Status.

OpenCart crée la commande à l'étape Confirm Order sans statut (une commande manquante). Elle ne reçoit un statut qu'après que Khipu a confirmé le paiement. Chaque champ ci-dessous liste vos statuts de commande OpenCart.

Paid Order Status : le statut après un paiement confirmé lorsque Status after payment est sur Processing. Par défaut : En cours.

Complete Order Status : le statut après un paiement confirmé lorsque Status after payment est sur Completed. Par défaut : Terminée.

On Hold (Review) Status : les paiements dont le montant ou la devise ne correspondent pas à la commande, ou qui arrivent après l'annulation de la commande, reçoivent ce statut et une note qui en explique la raison. Par défaut : En attente, car OpenCart n'a pas de statut « En suspens ». Vous pouvez créer votre propre statut dans System > Localisation > Order Statuses et le sélectionner ici.

Avancé

Debug log : enregistre les appels à l'API et les notifications dans wc_khp_debug.log.php, dans le dossier des journaux d'OpenCart (storage/logs). Le fichier ne peut pas être ouvert depuis le web ; à 5 Mo, il est renommé en wc_khp_debug.old.log.php. 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 de l'extension supprime les réglages de la passerelle et le journal. Les données de commande (identifiants des paiements Khipu des commandes) sont toujours conservées. Par défaut : désactivé.

Import / Export

Export : Download JSON enregistre les réglages dans un fichier JSON. La clé d'API et la clé secrète ne sont pas exportées.

Import : collez un JSON exporté précédemment et cliquez sur Import pour restaurer les réglages. La clé d'API et la clé secrète enregistrées sont conservées.

Commande

À l'étape Payment Method, le client choisit le mode de paiement (par défaut Khipu). À l'étape Confirm Order, le client voit votre description au-dessus du bouton de confirmation. OpenCart crée la commande à cette étape, toujours sans statut. Lorsque le client clique sur Confirm Order, l'extension crée un paiement Khipu pour le total de la commande dans la devise de la commande et envoie le client sur la page de paiement Khipu. Le paiement apparaît chez Khipu sous la forme Order # avec le numéro de commande et le nom de la boutique, avec 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.

Sous OpenCart 4, le client choisit le mode de paiement avec le bouton Choose du bloc du mode de paiement, dans la fenêtre Payment method options, puis clique sur Confirm Order en bas de la page de paiement.

Après le paiement, le client revient dans votre boutique. La commande n'est marquée 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é. La commande reçoit alors son statut de la manière standard d'OpenCart, avec les e-mails habituels de commande et la mise à jour du stock, et le client voit la page de confirmation de commande d'OpenCart. 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 confirmed 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 de la commande ne peut pas être rattaché à celle-ci (par exemple parce qu'il appartient à un autre Receiver ID), le client revient à la commande avec le message We could not match this payment to an order. If you paid, please contact us.

Si le client annule sur la page Khipu, ou si le paiement n'a pas été finalisé, le client revient à la commande avec le message The Khipu payment was not completed. You can try again or choose another payment method. Le panier est conservé. Sous OpenCart 4, ces messages s'affichent au-dessus de la page de paiement. Chaque nouvelle tentative (OpenCart 3 crée une nouvelle commande à chaque affichage de l'étape Confirm Order ; OpenCart 4 met à jour la commande du paiement et la règle avec un nouveau paiement Khipu) supprime le paiement Khipu non payé précédent de la commande ou du panier, de sorte que l'ancien lien ne peut plus être payé. Si Khipu a déjà reçu le paiement précédent, il est pris en compte et le client va à la page de confirmation, sans nouveau paiement. Si le virement précédent est encore en cours de vérification par la banque, 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 le paiement précédent est en cours d'examen, le client est invité à contacter la boutique avant de payer à nouveau. Une modification du panier, y compris une nouvelle quantité, compte comme un nouveau panier qui nécessite son propre paiement.

OpenCart 4 conserve la commande dans le paiement jusqu'à l'affichage de la page de succès. Si cette commande a été fermée sans paiement entre-temps (par exemple vous l'avez annulée), le client est renvoyé au paiement avec Your previous order was cancelled without a payment. Please confirm the order again to pay with a new order. Si la commande est déjà enregistrée et que le panier a changé depuis, le message est Your previous order has already been placed. Your cart has changed since — please confirm the order again to pay for the current cart with a new order. Dans les deux cas, le prochain Confirm Order règle une nouvelle commande du panier.

Si Khipu ne peut pas créer le paiement, le client reste à l'étape Confirm Order avec un bref message au-dessus du bouton, 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.

La notification fonctionne aussi lorsque la boutique est en mode maintenance : OpenCart 3 laisse passer les requêtes des extensions de paiement, et sous OpenCart 4 l'extension ajoute une action de démarrage qui laisse passer la notification et le retour du client.

L'extension ne prend en charge que les virements bancaires ponctuels. Les remboursements ne sont pas envoyés à Khipu depuis OpenCart, et il n'y a ni abonnements, ni moyens de paiement enregistrés, ni pré-autorisations. Les paiements non réglés ne sont liés à aucune réservation de stock.

Commandes

Statuts de commande

Aucun statut (commande manquante) : le client a été envoyé vers Khipu et n'a pas payé, ou Khipu n'a pas encore confirmé le virement. Dans Sales > Orders, ces commandes ne s'affichent qu'avec le filtre Order Status défini sur Missing Orders.

Paid Order Status ou Complete Order Status (par défaut En cours ou Terminée) : Khipu a confirmé le paiement. Le statut suit Status after payment. Une note affiche Khipu payment verified. Payment ID: avec l'identifiant du paiement et le montant.

On Hold (Review) Status (par défaut En attente) : Khipu a confirmé un paiement dont le montant ou la devise ne correspond pas à la commande, ou le paiement est arrivé après l'annulation ou le refus de la commande. 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 la même commande, la commande passe au statut payé et le client est informé par e-mail. Si le paiement arrive après que la commande a été passée à un autre statut de traitement, le statut n'est pas modifié et seule une note est ajoutée.

Si un paiement arrive pour une commande déjà payée, ou pour une autre commande d'un panier déjà payé, la commande n'est pas modifiée. Une note vous demande de le rembourser au 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 n'est pas modifié.

Les notes sont des entrées de l'History de la commande que le client ne voit pas. Elles commencent par le mot Khipu.

Onglet VibeFox Khipu Gateway

Dans Sales > Orders, ouvrez une commande payée avec Khipu. En bas de la page de la commande, à côté de History et Additional, l'onglet VibeFox Khipu Gateway affiche les tentatives de paiement Khipu de la commande (date, montant, identifiant du paiement Khipu, statut Khipu et résultat), un avertissement Manual review tant que la commande est au statut d'examen, et les Khipu notes de la commande. L'onglet est en lecture seule et est affiché aux utilisateurs ayant accès à l'extension.

Remboursements

Les remboursements ne sont pas envoyés à Khipu depuis OpenCart, car Khipu ne propose aucun remboursement via son API. L'onglet l'indique. Remboursez le client depuis votre compte Khipu ou par virement bancaire, puis modifiez manuellement le statut de la commande dans OpenCart.

Clé de licence

L'extension fonctionne avec une clé de licence VibeFox obtenue sur vibefox.net. Le bloc de licence License — VibeFox Khipu Gateway est le premier bloc de Extensions > Extensions > Payments > VibeFox Khipu Gateway > Edit, 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 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. En dessous, figurent la ligne Product: opencart-payment-khipu et le lien Manage licenses and domains in your account, qui ouvre votre compte vibefox.net. Seuls les utilisateurs administrateurs disposant du droit Modify sur l'extension peuvent modifier la clé. Les textes du bloc suivent la langue de l'administration (l'anglais et le russe sont inclus).

Si la clé n'est pas acceptée, le bloc indique pourquoi, 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é une place de domaine dans votre compte, cliquez sur Check now. Si le serveur de licences est injoignable, l'extension continue de fonctionner avec le dernier statut connu.

Une clé fonctionne pour un seul domaine : l'adresse de la boutique issue de la configuration d'OpenCart. Retirer la clé de la boutique ne libère pas sa place de domaine. Libérez la place dans votre compte vibefox.net.

Sans clé active, Khipu n'est pas affiché aux clients à la commande. Si un paiement est tout de même lancé, le client voit This payment method is not available. Please choose another one. Un utilisateur administrateur connecté à l'administration dans le même navigateur voit toujours le mode de paiement dans la boutique, marqué (unlicensed — visible to admins only), afin de pouvoir configurer et tester l'extension avant d'acheter une clé. Sous OpenCart 4, cet aperçu n'est pas disponible : la boutique ne voit pas la connexion administrateur, donc sans clé active le mode de paiement est masqué pour tout le monde. Une fois la page Edit ouverte une fois, un rappel apparaît sur le Dashboard de l'administration. Fermez-le avec × pour le masquer pendant 7 jours. 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 l'assistance nécessitent un renouvellement. Le statut est vérifié à nouveau automatiquement lorsque vous ouvrez le Dashboard ou la page Edit de l'administration : 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 de l'extension supprime toujours la clé de licence et le statut de licence.

Dépannage

Khipu n'apparaît pas à la commande : 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 tous saisis. Le client doit payer en CLP, ARS ou PEN. La page des réglages affiche un avertissement lorsqu'un élément manque. Vérifiez aussi que l'adresse de paiement se trouve dans la Geo Zone sélectionnée et que la commande atteint le Total défini dans les réglages.

Le paiement a abouti, mais la commande reste sans statut : Khipu confirme un virement une fois que la banque l'a vérifié. La commande reçoit son statut lorsque la notification Khipu arrive ou lorsque le client clique sur Check again. Vérifiez que votre boutique est accessible depuis Internet à l'URL affichée dans Notification URL (aucune protection par mot de passe ni pare-feu ne bloquant Khipu), et consultez le champ Log sur la page de l'extension.

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 d'encaissement dont vous utilisez les clés, ou la requête ne provient pas de Khipu.

La notification répond Order not found, Payment not found for this account ou Payment does not belong to this order : le paiement a été effectué vers un autre Receiver ID, avec d'autres clés ou pour une autre commande. Vérifiez le Receiver ID et les clés.

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 updated, retry later : la commande était en cours de confirmation par une autre requête au même moment, ou le statut de la commande n'a pas pu être défini. Khipu renvoie la notification. La raison figure dans le journal.

La commande est au statut d'examen après paiement : lisez les notes dans l'onglet VibeFox Khipu Gateway. 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é d'API est manquante ou incorrecte. Vérifiez les clés dans votre compte Khipu.

Pour les développeurs : l'extension déclenche les événements OpenCart wc_khp_supported_currencies (pour ajouter une devise acceptée par votre compte Khipu, par exemple EUR pour Khipu Espagne), wc_khp_currency_decimals et wc_khp_payment_data.

Désinstallation

Allez dans Extensions > Extensions, choisissez le type Payments et cliquez sur Uninstall (le bouton rouge −) à côté de VibeFox Khipu Gateway. La clé de licence et le statut de licence de cette extension sont toujours supprimés. OpenCart supprime toujours ses propres réglages de l'extension : Enable / Disable, Sort Order, Geo Zone, Total et les trois statuts de commande, qui reprennent leurs valeurs par défaut lors d'une réinstallation. Sous OpenCart 4, son événement et son action de démarrage, qui laisse passer la notification et le retour du client en mode maintenance, sont aussi supprimés. Si Delete data on uninstall est activé, les autres réglages de la passerelle (titre, description, Receiver ID, clés, statut après paiement, journal de débogage) et le journal sont supprimés. S'il est désactivé, ils sont conservés pour une future réinstallation. Les tentatives de paiement Khipu sont toujours conservées, de sorte que les notifications tardives concernant des commandes payées auparavant sont toujours traitées après une réinstallation. Les commandes existantes conservent leurs notes de paiement.

Sous OpenCart 4, pour supprimer aussi les fichiers de l'extension, allez dans Extensions > Installer après la désinstallation, cliquez sur Uninstall (le bouton orange −) à côté de VibeFox Khipu Gateway dans la liste des extensions installées, puis sur Delete (le bouton rouge en forme de poubelle) pour supprimer le paquet téléversé.

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