VibeFox Culqi for OpenCart — Aide

Prérequis

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

PHP : 8.0 ou ultérieur.

Devise de la boutique : le sol péruvien (PEN) ou le dollar américain (USD) doit être une devise activée dans votre boutique. Culqi n'accepte aucune autre devise, et le mode de paiement n'est affiché que lorsque le client paie en PEN ou en USD.

Compte Culqi : vous avez besoin de la clé publique et de la clé secrète de votre compte Culqi. Les clés d'intégration (test) proviennent de integ-panel.culqi.com, les clés de production (réelles) de mipanel.culqi.com, dans CulqiPanel > Desarrollo > API Keys. La clé publique est utilisée par la fenêtre Culqi dans le navigateur. La clé secrète n'est utilisée que sur votre serveur et n'est jamais envoyée au navigateur. Aucun webhook n'est nécessaire.

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 pour les deux versions d'OpenCart. Décompressez-le sur votre ordinateur. Il contient README.txt, le paquet OpenCart 3 wcp_culqi_payment-oc3-(version).ocmod.zip et le paquet OpenCart 4 wcp_culqi_payment.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_culqi_payment-oc3-(version).ocmod.zip. L'extension ne comporte aucune modification OCMOD ; Extensions > Modifications n'a donc pas besoin d'être actualisé. Au lieu de passer par 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 Culqi Payment 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 Clé de licence).

4. Saisissez les clés d'intégration et, pour les paiements réels, les clés de production (voir Configuration).

5. Activez Enable/Disable et cliquez sur Save. Gardez Test Mode activé pendant vos tests, puis désactivez-le pour encaisser de vrais paiements.

OpenCart 4

1. Dans l'administration, allez dans Extensions > Installer, cliquez sur Upload et choisissez le fichier wcp_culqi_payment.ocmod.zip. Ne renommez pas le fichier : OpenCart 4 tire le code de l'extension du 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 Culqi Payment, cliquez sur Install (le bouton vert +), puis sur Edit (le bouton crayon).

4. Saisissez la clé de licence et les clés Culqi comme aux étapes 3 à 5 pour OpenCart 3. La page de configuration et ses champs sont identiques dans les deux versions.

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

Configuration

Tous les réglages se trouvent sur la page de l'extension : Extensions > Extensions > Payments > VibeFox Culqi Payment > Edit. Les sections sont listées à gauche ; le bouton Save situé sous la liste enregistre toute la page. Au-dessus des réglages, la page affiche Test mode is active: the integration keys are used and no real money is charged. tant que le mode test est activé. Elle vous avertit lorsque la passerelle est activée mais que les clés du mode en cours sont manquantes, et lorsqu'aucune devise activée de la boutique n'est prise en charge par Culqi. Dans les deux cas, le mode de paiement est masqué à la page de paiement. Si votre devise par défaut n'est ni PEN ni USD, la page indique que Culqi n'est proposé que lorsque le client paie dans une devise prise en charge. Sans le droit de modifier l'extension, la page affiche les réglages mais ne peut pas les enregistrer.

Lors de l'enregistrement, une valeur incorrecte n'est pas enregistrée et conserve sa valeur précédente, tandis que les autres champs sont enregistrés. La page affiche une erreur pour chacun de ces champs : une clé au mauvais préfixe (par exemple Live Secret Key must start with sk_live_ — the previous value was kept.), un Title vide ou dépassant 128 caractères, un Sort Order qui n'est pas un nombre entier, un Total qui n'est pas un nombre supérieur ou égal à 0, ou une zone géographique ou un statut de commande qui n'existe pas.

Culqi

Enable/Disable : Enable Culqi Payment Gateway active ou désactive le mode de paiement. Par défaut : désactivé.

Title : le nom du mode de paiement que le client voit à la page de paiement. C'est aussi le nom du mode de paiement enregistré dans la commande. Par défaut : Credit/Debit Card or Yape (Culqi). Obligatoire, jusqu'à 128 caractères.

Description : le texte affiché au client à l'étape Confirm Order, au-dessus du bouton de confirmation. Par défaut : Pay securely with your credit/debit card or Yape via Culqi.

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

Geo Zone : proposer Culqi uniquement pour les adresses de facturation situées dans 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 montant total du panier, dans la devise par défaut de la boutique, que doit atteindre une commande avant que Culqi ne soit proposé. Laissez le champ vide pour proposer Culqi quel que soit le montant.

Clés API

Copiez les clés depuis CulqiPanel > Desarrollo > API Keys : les clés d'intégration (test) sur integ-panel.culqi.com, les clés de production sur mipanel.culqi.com (la page contient les liens). Le mode test n'utilise que les clés de test, le mode réel uniquement les clés réelles. Chaque clé doit commencer par le préfixe de son champ.

Test Mode : lorsqu'il est activé, les clés de test (pk_test_ / sk_test_) sont utilisées et aucun argent réel n'est débité. Par défaut : activé. Désactivez-le pour encaisser de vrais paiements avec les clés réelles. Tant qu'il est activé, les clients voient TEST MODE: No real charges will be made. à l'étape Confirm Order.

Test Public Key : la clé publique de l'environnement d'intégration. Elle commence par pk_test_.

Test Secret Key : la clé secrète de l'environnement d'intégration. Elle commence par sk_test_ et n'est jamais transmise au navigateur.

Live Public Key : la clé publique de l'environnement de production. Elle commence par pk_live_.

Live Secret Key : la clé secrète de l'environnement de production. Elle commence par sk_live_ et n'est jamais transmise au navigateur.

Les clés secrètes 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 si vous voulez la modifier. Pour supprimer une clé secrète enregistrée, cochez Clear the saved key on save sous le champ, puis cliquez sur Save.

Modes de paiement

Les cartes sont toujours proposées. Le virement bancaire, les agents, les portefeuilles et Cuotéalo nécessitent l'API Culqi Orders et ne sont pas proposés par cette extension.

Yape : Offer Yape in the Culqi popup affiche Yape à côté des cartes dans la fenêtre Culqi. Par défaut : activé.

Commandes

OpenCart crée la commande à l'étape Confirm Order sans statut (commande manquante). La commande ne reçoit un statut qu'une fois que Culqi a confirmé le débit. Chacun des champs ci-dessous présente les statuts de commande de votre OpenCart.

Order Status After Payment : Culqi a confirmé le débit, et son montant et sa devise correspondent à la commande. Par défaut : Processing.

On Hold (Review) Status : Culqi a débité un montant ou une devise qui ne correspond pas à la commande, ou n'a pas capturé le paiement. Une note explique ce qu'il faut vérifier dans CulqiPanel. Par défaut : Pending, car OpenCart n'a pas de statut On hold. Vous pouvez créer votre propre statut dans System > Localisation > Order Statuses et le sélectionner ici.

Refunded Status : le paiement a été intégralement remboursé depuis la page de la commande. Les remboursements partiels ajoutent seulement une note. Par défaut : Refunded.

Avancé

Debug log : enregistre les requêtes API et les étapes de paiement dans culqi_p_debug.log.php, dans le dossier des journaux d'OpenCart (storage/logs). Le fichier ne peut pas être ouvert depuis le web et, à 5 Mo, il est déplacé vers culqi_p_debug.old.log.php. Les erreurs, y compris les refus de carte avec leur code, sont toujours journalisées. Les clés, les données de carte et les données clients ne sont jamais journalisées. 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 débits et remboursements Culqi sont toujours conservés, de sorte que les commandes payées auparavant peuvent encore être remboursées après une réinstallation. Par défaut : désactivé.

Import / Export

Export : Download JSON enregistre les réglages dans un fichier JSON. Les clés secrètes ne sont pas exportées.

Import : collez le JSON exporté précédemment et cliquez sur Import pour restaurer les réglages. Les clés secrètes enregistrées sont conservées.

Paiement

À l'étape Payment Method, le client choisit le mode de paiement (par défaut Credit/Debit Card or Yape (Culqi)). À l'étape Confirm Order, le client voit votre description, et OpenCart crée la commande, toujours sans statut. Lorsque le client clique sur Confirm Order, la fenêtre Culqi Checkout s'ouvre sur la même page avec le nom de votre boutique, le total de la commande et la devise. Le client y saisit les données de sa carte ou paie avec Yape. Les scripts de Culqi sont toujours chargés depuis Culqi. Sur OpenCart 4, le client choisit le mode de paiement avec le bouton Choose du bloc de mode de paiement, dans la fenêtre Payment method options, puis clique sur Confirm Order dans le bloc de confirmation en bas de la page de paiement. Si la boutique ne demande pas d'adresse de facturation (valeur par défaut d'OpenCart 4), les coordonnées du client transmises avec le débit sont reprises de l'adresse de livraison et du nom du client.

Culqi transforme les données de paiement en un jeton à usage unique, et seul ce jeton est envoyé à votre boutique. Votre serveur crée le débit avec l'API Culqi Charges pour le total de la commande dans la devise de la commande, capturé immédiatement. Le débit apparaît dans CulqiPanel sous Order avec le numéro de commande, ainsi que l'adresse e-mail du client. La commande n'est marquée payée qu'après confirmation de Culqi. Elle reçoit ensuite 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 exige 3-D Secure, le client voit Your bank requires additional verification (3-D Secure). Please complete it in the window that opens. Après l'authentification, le débit est envoyé de nouveau automatiquement. Si la vérification n'est pas terminée, le client voit The 3-D Secure verification was not completed. Please try again or use another card.

Si la carte est refusée, le client voit le message de Culqi après Payment failed: et peut réessayer avec une autre carte à la même étape. Si Culqi ne répond pas, le client voit We could not confirm your payment with Culqi. Please check your email or contact us before trying again. Dans ces cas, la commande reste sans statut et une note dans l'historique de la commande enregistre la tentative. Si le client ferme la fenêtre Culqi, rien n'est débité et le bouton Confirm Order peut être cliqué de nouveau. Le panier est conservé dans tous ces cas.

Une commande n'est jamais débitée deux fois. Si le client soumet à nouveau alors qu'un paiement de la même commande est en cours, il voit This order is already being paid. Please wait a moment and check your email before trying again. Si Culqi a encaissé l'argent mais que le statut de la commande n'a pas pu être défini, le client voit Your payment was received, but the order could not be completed automatically. Please contact us — do not pay again. Le débit est conservé, et la tentative suivante avec le même panier définit le statut de la commande à partir de celui-ci, sans nouveau débit. Un panier n'est payé qu'une fois : si une autre commande du même panier (OpenCart 3 crée une nouvelle commande à chaque affichage de l'étape Confirm Order) est déjà payée, le client est redirigé vers la page de succès et n'est pas débité à nouveau. Sur OpenCart 4, la commande du paiement est conservée et mise à jour : après une carte refusée, le client paie donc la même commande.

OpenCart 4 conserve la commande dans le paiement jusqu'à l'affichage de la page de succès. Si cette commande a été fermée entre-temps (par exemple annulée ou remboursée), ou si elle est déjà payée et que le panier a changé depuis (autres produits ou quantités), Confirm Order renvoie le client à la page de paiement, où une nouvelle commande du panier est créée avec son propre paiement. Une commande payée puis fermée ne retient plus le panier.

L'extension n'accepte que les paiements uniques par carte et Yape, capturés immédiatement. Elle ne propose ni application bancaire, ni agents, ni portefeuilles, ni Cuotéalo, ni cartes enregistrées, abonnements ou paiements échelonnés, ni webhooks Culqi, ni autorisation et capture séparées.

Commandes et remboursements

Statuts de commande

No status (missing order) : le client n'a pas encore payé, la carte a été refusée ou Culqi n'a pas répondu. Dans Sales > Orders, ces commandes ne s'affichent qu'avec le filtre Order Status défini sur Missing Orders. Les notes de l'historique de la commande expliquent les tentatives échouées.

Order Status After Payment (default Processing) : le débit a été confirmé et correspond à la commande. Une note affiche Culqi payment successful avec le mode (test ou réel), 3-D Secure si utilisé, et l'identifiant du débit Culqi (chr_...).

On Hold (Review) Status (default Pending) : Culqi a signalé un débit dont le montant ou la devise ne correspond pas à la commande, ou un paiement autorisé mais non capturé. La note l'explique et affiche l'identifiant du débit. Vérifiez le débit dans CulqiPanel, puis exécutez la commande ou remboursez le paiement.

Refunded Status (default Refunded) : le paiement a été intégralement remboursé via l'extension.

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

Onglet VibeFox Culqi Payment

Dans Sales > Orders, ouvrez une commande payée avec Culqi. En bas de la page de la commande, à côté de History et Additional, l'onglet VibeFox Culqi Payment affiche le Charge ID avec une étiquette Test pour les paiements de test, le Amount débité (avec 3-D Secure si utilisé), une indication Review pour les commandes en attente, les montants Paid / refunded, le formulaire de remboursement, l'historique des remboursements et les Culqi notes de la commande. L'onglet est affiché aux utilisateurs qui ont accès à l'extension.

Remboursements

Dans l'onglet VibeFox Culqi Payment, saisissez le Amount (le montant non encore remboursé est pré-rempli), éventuellement un Reason (optional), puis cliquez sur Refund via Culqi. Confirmez la question Refund this amount through Culqi? This cannot be undone. Les remboursements totaux et partiels sont pris en charge. Vous devez avoir le droit de modifier l'extension (à définir dans System > Users > User Groups). Les remboursements sont effectués dans le montant et la devise que Culqi a débités ; après un écart de montant, vous pouvez donc rembourser jusqu'au montant réellement payé par le client, et non au total de la commande. Le remboursement est envoyé avec les clés du mode dans lequel le paiement a été effectué (test ou réel), même si vous avez changé de mode depuis, de sorte que la clé secrète de ce mode doit être renseignée. Si Culqi n'accepte pas le remboursement, l'onglet affiche l'erreur et aucun remboursement n'est enregistré. Un remboursement réussi est ajouté à l'historique des remboursements et aux notes, avec l'identifiant du remboursement Culqi, le montant et votre motif. Un remboursement total fait passer la commande en Refunded Status sans en informer le client et sans remettre les produits en stock, comme un changement manuel de statut. Un remboursement partiel ne modifie pas le statut.

Les retours de produits dans Sales > Returns ne renvoient pas d'argent via Culqi. Les remboursements effectués dans CulqiPanel ne sont pas synchronisés avec OpenCart. Mettez la commande à jour manuellement si nécessaire.

Clé de licence

L'extension fonctionne avec une clé de licence VibeFox obtenue sur vibefox.net. Le bloc de licence License — VibeFox Culqi Payment est le premier bloc de Extensions > Extensions > Payments > VibeFox Culqi Payment > 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) 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: opencart-payment-culqi et le lien Manage licenses and domains in your account, qui ouvre votre compte vibefox.net. Seuls les utilisateurs administrateurs disposant du droit Modify pour 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 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, 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 son emplacement de domaine. Libérez-le dans votre compte vibefox.net.

Sans clé active, Culqi n'est pas affiché aux clients à la page de paiement. 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 que vous puissiez configurer et tester l'extension avant d'acheter une clé. Sur OpenCart 4, cet aperçu n'est pas disponible : la boutique ne voit pas la connexion à l'administration, donc sans clé active le mode de paiement est masqué pour tout le monde. Après avoir ouvert une fois la page Edit, 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 concernées : les paiements déjà lancés sont toujours confirmés, et les remboursements fonctionnent.

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é automatiquement à l'ouverture du Dashboard ou de 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

Culqi n'apparaît pas à la page de paiement : vérifiez que la licence est active, que Enable/Disable est activé, que les deux clés du mode en cours sont renseignées (Test Public Key et Test Secret Key en mode test, Live Public Key et Live Secret Key en mode réel) et que le client paie en PEN ou en USD. La page des réglages affiche un avertissement lorsque des clés manquent. Vérifiez aussi que l'adresse de facturation 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 : l'extension n'utilise pas de webhooks. Le débit n'est confirmé que par la réponse de Culqi à votre serveur. Si Culqi n'a pas répondu à temps, la commande porte la note Culqi did not confirm the charge. Retrouvez le débit de cette commande dans CulqiPanel. Si le client a vu le message indiquant que la commande n'a pas pu être finalisée, la tentative de paiement suivante dans la même session client définit le statut sans débiter à nouveau.

La commande est en statut de vérification après le paiement : lisez les notes dans l'onglet VibeFox Culqi Payment. Le montant ou la devise débité différait de la commande, ou le paiement n'a pas été capturé. Vérifiez le débit dans CulqiPanel, puis exécutez la commande ou remboursez le paiement.

La clé n'est pas enregistrée : l'erreur indique que le champ doit commencer par un préfixe, par exemple sk_live_. Chaque champ n'accepte que les clés de son propre type et de son propre mode : pk_test_, sk_test_, pk_live_ ou sk_live_.

Le client voit Payment gateway misconfiguration. Please contact the store owner.: les clés du mode en cours sont manquantes, ou Culqi a rejeté la clé secrète. Vérifiez les clés dans les réglages.

Le client voit Payment token is invalid. Please try again.: le jeton issu de la fenêtre Culqi appartient à l'autre mode, par exemple après un changement de Test Mode alors que la page de paiement était ouverte. Le client doit recharger la page et payer à nouveau.

La fenêtre Culqi ne s'ouvre pas : le client voit The Culqi payment window could not be loaded. Please reload the page and try again. Vérifiez que les scripts de js.culqi.com et 3ds.culqi.com ne sont pas bloqués sur votre page de paiement, par exemple par une extension de cache ou d'optimisation.

Le client voit Security check failed. Please reload the page and try again.: la page de paiement était ouverte dans une autre session. Recharger la page résout le problème.

Le client voit This payment method is not available.: la session de paiement n'a plus de commande Culqi, ou le mode de paiement a été désactivé entre-temps. Le client recharge la page de paiement.

Une carte a été refusée et vous voulez en connaître la raison : lisez la note de la commande ou le champ Log de la page de l'extension. Les refus sont journalisés avec le code de refus Culqi, même lorsque Debug log est désactivé.

Pas de formulaire de remboursement dans l'onglet : l'onglet indique la raison : le paiement est entièrement remboursé, votre groupe d'utilisateurs n'a pas le droit de modifier l'extension, ou la clé secrète du mode de paiement est manquante.

Le remboursement échoue avec un message concernant les clés : le paiement a été effectué en mode test ou réel, et la clé secrète de ce mode n'est pas renseignée. Saisissez-la et réessayez.

Désinstallation

Allez dans Extensions > Extensions, choisissez le type Payments et cliquez sur Uninstall (le bouton rouge −) à côté de VibeFox Culqi Payment. 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 statuts de commande de la section Orders, qui reprennent leurs valeurs par défaut lors d'une réinstallation. Si Delete data on uninstall est activé, les autres réglages de la passerelle (titre, description, mode test, clés, Yape, journalisation) et le journal sont supprimés. S'il est désactivé, ils sont conservés pour une réinstallation ultérieure. Les débits et remboursements Culqi sont toujours conservés, de sorte que les commandes payées auparavant peuvent encore être remboursées après une réinstallation. Les commandes existantes conservent leurs notes de paiement.

Sur OpenCart 4, pour supprimer aussi les fichiers de l'extension, allez dans Extensions > Installer après la désinstallation et cliquez sur Uninstall (le bouton orange −) à côté de VibeFox Culqi Payment dans la liste des extensions installées, puis sur Delete (le bouton rouge corbeille) pour supprimer le paquet téléchargé.

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