VibeFox Culqi for PrestaShop — Aide

Prérequis

PrestaShop : 8.0 à 9.x.

PHP : 8.0 ou ultérieur. Le module refuse de s'installer sur les versions antérieures de PHP.

Devise de la boutique : sol péruvien (PEN) ou dollar américain (USD). Culqi n'accepte aucune autre devise, et le mode de paiement n'est affiché que pour les paniers en PEN ou 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, et les clés de production (live) 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 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 transfert terminé, cliquez sur Configure, ou retrouvez plus tard VibeFox Culqi Payment dans la liste des modules et cliquez sur Configure.

3. Saisissez votre clé de licence VibeFox dans License key du bloc de licence en haut de la page Configure et cliquez sur Activate (voir Clé de licence).

4. Collez 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 recevoir de vrais paiements.

6. Vérifiez que PEN ou USD est une devise active de votre boutique.

À l'installation, le module crée le statut de commande Culqi 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 limiter dans Payment > Preferences.

Configuration

Tous les réglages se trouvent sur la page du module : Modules > Module Manager > VibeFox Culqi Payment > Configure. Chaque section a son propre bouton Save, qui enregistre toute la page. Au-dessus des champs, 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 actuel sont absentes, et lorsqu'aucune devise de la boutique n'est prise en charge par Culqi. Dans les deux cas, le mode de paiement est masqué lors du paiement. Si votre devise par défaut n'est ni PEN ni USD, la page indique que Culqi n'est proposé que pour les paniers dans les devises prises en charge.

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 affiché aux clients lors du paiement. C'est aussi le nom du mode de paiement enregistré dans la commande. Par défaut : Credit/Debit Card or Yape (Culqi). Obligatoire.

Description : le texte affiché sous le mode de paiement lors du paiement. Par défaut : Pay securely with your credit/debit card or Yape via Culqi.

Clés d'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. Le mode test n'utilise que les clés de test, et le mode production uniquement les clés de production. Chaque clé doit commencer par le préfixe de son champ. Une clé au mauvais préfixe n'est pas enregistrée : la page affiche une erreur, par exemple Live Secret Key must start with sk_live_ — the previous value was kept., et les autres champs sont enregistrés.

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 recevoir de vrais paiements avec les clés de production. Tant qu'il est activé, les clients voient TEST MODE: No real charges will be made. sous le mode de paiement.

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 partagée avec le 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 partagée avec le navigateur.

Les clés secrètes enregistrées ne sont jamais réaffichées. Le champ reste vide et affiche Saved — leave empty to keep it. Saisissez une nouvelle valeur uniquement si vous voulez la modifier.

Clear saved secret keys : cochez Test Secret Key ou Live Secret Key et cliquez sur Save pour la supprimer. Un champ vide conserve la valeur enregistrée.

Modes de paiement

Les cartes sont toujours proposées. Le virement bancaire, les agents, les portefeuilles et Cuotéalo nécessitent la Culqi Orders API et ne sont pas proposés par ce module.

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

Avancé

Debug log : consigne les requêtes API et les étapes de paiement dans logs/culqi_p_debug.log.php, dans le dossier du module. Le fichier ne peut pas être ouvert depuis le web. Les erreurs, y compris les refus de carte avec leur code, sont toujours consignées. Les clés, les données de carte et les données client ne sont jamais consigné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 du module supprime les réglages de la passerelle, les enregistrements de débits et de remboursements Culqi du module, ainsi que le journal. Le statut de commande et les données Culqi des commandes (paiements, notes) sont toujours conservés. Par défaut : désactivé.

Paiement

À l'étape de paiement, le client choisit le mode de paiement (par défaut Credit/Debit Card or Yape (Culqi)) et clique sur le bouton de validation de la commande. La fenêtre contextuelle Culqi Checkout s'ouvre sur la même page, avec le nom de votre boutique, le total du panier et la devise. Le client y saisit les données de sa carte ou paie avec Yape. Les scripts Culqi ne sont chargés que sur la page de paiement.

Culqi transforme les données de paiement en un jeton à usage unique, et ce jeton est envoyé à votre boutique. Votre serveur crée le débit avec la Culqi Charges API pour le total du panier, dans la devise du panier, capturé immédiatement. Le débit apparaît dans CulqiPanel sous le nom Cart et le numéro du panier, avec l'e-mail du client. Aucune commande n'existe avant ce point. La commande n'est marquée payée qu'après confirmation de Culqi : la commande est créée lorsque Culqi répond par un débit réussi, et le client voit la page standard de confirmation de commande.

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 renvoyé 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, par exemple Payment failed: suivi de la raison, et peut réessayer avec une autre carte. 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. Si le client ferme la fenêtre Culqi, rien n'est débité, le client voit The payment window was closed before the payment was completed. et peut passer à nouveau commande. Le panier est conservé dans tous ces cas. Les tentatives échouées sont consignées dans le journal du module, car aucune commande n'existe encore.

Un panier n'est jamais débité deux fois. Si le client valide à nouveau alors qu'un paiement pour le même panier 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 prélevé l'argent mais que la commande n'a pas pu être créée, 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 crée la commande à partir de celui-ci, sans nouveau débit.

Le module n'accepte que les paiements uniques par carte et par Yape, capturés immédiatement. Il ne gère ni codes PagoEfectivo ou CIP, ni application bancaire, ni agents, ni portefeuilles, ni Cuotéalo, ni cartes enregistrées, ni abonnements ou paiements échelonnés, ni webhooks Culqi, ni autorisation et capture séparées.

Commandes et remboursements

Statuts de commande

No order yet : la carte a été refusée, le client a fermé la fenêtre Culqi ou Culqi n'a pas répondu. Seul le panier existe. Le journal du module contient les détails.

Payment accepted : le débit a été confirmé et correspond au panier. Le paiement est enregistré avec l'identifiant du débit Culqi (chr_...) comme identifiant de transaction, et une note indique le mode (test ou production) et si 3-D Secure a été utilisé.

Culqi payment on hold : Culqi a signalé un débit dont le montant ou la devise ne correspond pas au panier, ou un paiement autorisé mais non capturé. La note l'explique et indique l'identifiant du débit. Un débit capturé dans la devise du panier est enregistré comme un paiement du montant réellement débité. Vérifiez le débit dans CulqiPanel, puis traitez la commande ou remboursez le paiement.

Refunded : le paiement a été intégralement remboursé via le module.

Si un second débit arrive pour un panier qui possède déjà une commande, la commande n'est pas modifiée. Une note vous invite à vérifier le débit dans CulqiPanel et à le rembourser si nécessaire.

Bloc de paiement Culqi

La page de commande affiche un bloc Culqi payment avec l'identifiant du débit, le montant débité (avec 3-D Secure si utilisé), un badge Test pour les paiements de test, une indication de vérification pour les commandes en attente, les montants payés et remboursés, ainsi que l'historique des remboursements.

Remboursements

Dans le bloc Culqi payment, saisissez le montant (le montant non encore remboursé est pré-rempli), éventuellement un motif, 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 disposer du droit de modifier les commandes ; l'accès aux modules n'est pas nécessaire. Les remboursements sont effectués dans le montant et la devise débités par Culqi : après un écart de montant, vous pouvez donc rembourser jusqu'au montant que le client a réellement payé, et non le total de la commande. Le remboursement est envoyé avec les clés du mode dans lequel le paiement a été effectué (test ou production), même si vous avez changé de mode depuis, donc la clé secrète de ce mode doit être renseignée. Si Culqi n'accepte pas le remboursement, le bloc affiche l'erreur et aucun remboursement n'est enregistré. Un remboursement réussi est ajouté à l'historique des remboursements et aux notes de la commande, avec l'identifiant du remboursement Culqi, le montant et votre motif. Un remboursement total passe la commande en Refunded. Un remboursement partiel ne modifie pas le statut.

Le module ne crée pas d'avoirs. Les boutons de remboursement standard de PrestaShop sur la page de commande ne renvoient pas d'argent via Culqi. Les remboursements effectués dans CulqiPanel ne sont pas synchronisés avec PrestaShop. Mettez la commande à jour manuellement si nécessaire.

Clé de licence

Le module fonctionne avec une clé de licence VibeFox obtenue sur vibefox.net. Le bloc de licence License — VibeFox Culqi Payment est le premier bloc de Modules > Module Manager > VibeFox Culqi Payment > Configure, 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: presta-payment-culqi 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-le dans votre compte vibefox.net.

Sans clé active, Culqi 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 de PrestaShop ne sait pas que vous êtes connecté au back-office : le mode de paiement est donc masqué pour vous aussi. Vous pouvez configurer le module avant d'acheter une clé, mais pas le tester au 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, et les remboursements fonctionnent.

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 votre travail dans le back-office : une fois par jour pendant les 14 premiers jours suivant 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

Culqi n'apparaît pas au paiement : vérifiez que la licence est active, que Enable/Disable est activé, que les deux clés du mode actuel sont renseignées (Test Public Key et Test Secret Key en mode test, Live Public Key et Live Secret Key en mode production) et que la devise du panier est PEN ou USD. La page des réglages affiche un avertissement lorsque des clés manquent. 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 été effectué, mais aucune commande n'a été créée : le module 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, le journal du module indique Culqi did not confirm the charge avec le numéro du panier. Retrouvez le débit avec ce cart_id 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 pour le même panier crée la commande sans nouveau débit.

La commande est en Culqi payment on hold après le paiement : lisez la note de la commande. Le montant ou la devise débités différaient du panier, ou le paiement n'a pas été capturé. Vérifiez le débit dans CulqiPanel (son identifiant figure dans la note), puis traitez 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 type et de son 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 actuel sont absentes, 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 provenant 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 un module de cache ou d'optimisation.

Le client voit Security check failed. Please reload the page and try again.: la page de paiement est restée ouverte trop longtemps ou dans une autre session. Recharger la page règle le problème.

Le client voit This order is already being paid : une autre demande de paiement pour le même panier était en cours au même moment. Le client doit attendre et consulter son e-mail avant de réessayer.

Une carte a été refusée et vous voulez connaître la raison : consultez le champ Log sur la page du module. Les refus sont consignés avec le code de refus Culqi, même lorsque Debug log est désactivé.

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

Désinstallation

Allez dans Modules > Module Manager, ouvrez le menu à côté de VibeFox Culqi Payment 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, les enregistrements de débits et de remboursements Culqi du module, ainsi que le journal, sont supprimés. Les commandes payées auparavant ne peuvent alors plus être remboursées depuis la page de commande. Si l'option est désactivée, tout est conservé pour une réinstallation ultérieure. Le statut de commande Culqi payment on hold est toujours conservé. Les commandes existantes conservent leurs notes de paiement et leurs identifiants de transaction.

Culqi est une marque déposée de son propriétaire respectif. Ce module n'est pas affilié à Culqi et n'est pas approuvé par Culqi.