VibeFox Culqi for WooCommerce — Aide

Prérequis

WordPress : 5.8 ou ultérieur.

WooCommerce : 6.0 ou ultérieur, installé et activé. L'extension refuse de s'activer sans lui.

PHP : 8.0 ou ultérieur.

Devise de la boutique : sol péruvien (PEN) ou dollar américain (USD). Culqi n'accepte aucune autre devise, et le moyen de paiement est masqué sur la page de paiement pour toute autre devise de la boutique.

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) se trouvent sur integ-panel.culqi.com, les clés de production (live) sur mipanel.culqi.com, dans CulqiPanel > Desarrollo > API Keys. La clé publique est utilisée par la fenêtre contextuelle 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 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_culqi_payment dans /wp-content/plugins/ par FTP.

2. Cliquez sur Activate.

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

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

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

6. Activez Enable/Disable. Laissez Test Mode activé pendant vos tests, puis décochez-le pour accepter de vrais paiements.

7. Vérifiez que la devise de la boutique est PEN ou USD.

Configuration

Tous les réglages se trouvent sur une seule page : WooCommerce > Settings > Payments > Culqi. 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 lorsque la devise de la boutique n'est pas prise en charge par Culqi. Dans les deux cas, le moyen de paiement est masqué sur la page de paiement. Dans la liste des moyens de paiement, Culqi est signalé comme nécessitant une configuration tant que les deux clés du mode actuel ne sont pas renseignées.

Général

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

Title: le nom du moyen de paiement que les clients voient sur la page de paiement. Par défaut : Credit/Debit Card or Yape (Culqi).

Description: le texte affiché sous le moyen de paiement sur la page de 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, le mode production que les clés de production. Chaque clé doit commencer par le préfixe de son champ. Une clé avec un mauvais préfixe n'est pas enregistrée : la page affiche une erreur et conserve la valeur précédente.

Test Mode: Use the Culqi integration (test) environment. 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écochez-le pour accepter de vrais paiements avec les clés de production.

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.

Si vous effectuez la mise à jour depuis la version 1.0, la paire de clés unique de cette version est transférée vers les champs de test ou de production selon son préfixe. Vérifiez les clés après la mise à jour.

Moyens 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 cette extension.

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: Log API requests and payment steps écrit les détails dans WooCommerce > Status > Logs, source wcp_culqi_payment. Les erreurs sont toujours journalisées. Les clés, les données de carte et les données client ne sont jamais journalisées. Par défaut : désactivé.

Delete Data on Uninstall: Delete the gateway settings and logs when the plugin is deleted. Désactiver l'extension ne supprime jamais rien. Les données Culqi enregistrées sur les commandes sont toujours conservées. Par défaut : désactivé.

Page de paiement

Le client choisit le moyen 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 de la commande et la devise. Le client y saisit les données de sa carte ou paie avec Yape. Tant que le mode test est activé, le moyen de paiement affiche TEST MODE: No real charges will be made.

Culqi transforme les données de paiement en un jeton à usage unique, et la commande est envoyée à votre boutique avec ce jeton. Votre serveur crée le débit avec la Culqi Charges API pour le total de la commande dans la devise de la commande, avec le numéro de commande dans la description du débit. La commande n'est marquée payée qu'après que Culqi a confirmé le débit et que le montant et la devise débités correspondent à la commande. Le client est ensuite redirigé vers la page de commande reçue.

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 du motif, 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 de nouveau la commande.

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

L'extension ne prend que les paiements uniques par carte et par Yape, capturés immédiatement. Elle 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

Pending payment: la commande a été créée mais pas encore débitée, ou Culqi n'a pas répondu. Dans ce cas, une note indique Culqi did not confirm the charge. Cherchez dans CulqiPanel un débit pour cette commande avant d'accepter un autre paiement.

Processing: le paiement a été confirmé (valeur par défaut de WooCommerce ; les commandes contenant uniquement des produits virtuels téléchargeables passent à Terminée). La note de commande indique l'ID du débit Culqi, le mode (test ou production) et si 3-D Secure a été utilisé. L'ID de transaction est l'ID du débit Culqi.

On hold: 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 de commande l'explique et indique l'ID du débit. Vérifiez le débit dans CulqiPanel et terminez ou remboursez la commande manuellement.

Failed: la carte a été refusée. La note de commande indique le motif, le code de refus et l'ID du débit. Le client peut payer de nouveau avec une autre carte.

Une commande déjà payée ou qui possède déjà un débit Culqi, y compris une commande en attente, n'est jamais débitée à nouveau. Une seule demande de paiement par commande est traitée à la fois.

Remboursements

Ouvrez la commande, cliquez sur Refund, saisissez le montant et cliquez sur Refund via Culqi. Les remboursements totaux et partiels sont pris en charge. 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 ; la clé secrète de ce mode doit donc être renseignée. Si Culqi n'accepte pas le remboursement, WooCommerce affiche l'erreur et aucun remboursement n'est enregistré. Un remboursement réussi est ajouté aux notes de la commande avec l'ID du remboursement Culqi, le montant et le motif.

Les remboursements effectués dans CulqiPanel ne sont pas resynchronisés avec WooCommerce. Si nécessaire, créez un remboursement manuel dans WooCommerce sans Refund via Culqi.

Clé de licence

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

Une clé fonctionne sur un seul domaine. Retirer 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, Culqi n'est pas proposé aux clients sur 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. Les gestionnaires de boutique connectés voient toujours le moyen de paiement, signalé par (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 Extensions et sur les pages WooCommerce. Les commandes existantes ne sont pas affectées : les remboursements fonctionnent toujours.

Lorsqu'une licence expire, l'extension continue de fonctionner, mais les mises à jour et le support nécessitent un renouvellement. Le statut est revérifié automatiquement en arrière-plan.

Dépannage

Culqi n'apparaît pas sur la page de 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 de la boutique est PEN ou USD. La page de réglages affiche un avertissement dans chacun de ces cas.

Le paiement est passé, mais la commande reste en Pending payment : 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 note de commande indique Culqi did not confirm the charge. Retrouvez le débit de cette commande dans CulqiPanel et, s'il existe, terminez la commande manuellement.

La commande est On hold après le paiement : lisez la note de commande. Le montant ou la devise débités différaient de la commande, ou le paiement n'a pas été capturé. Vérifiez le débit dans CulqiPanel (son ID figure dans la note), puis terminez ou remboursez la commande.

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 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 de la fenêtre Culqi appartient à l'autre mode, par exemple après avoir basculé Test Mode alors que la page de paiement était ouverte. Le client doit recharger la page et payer de 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 d'optimisation.

Le client voit This order is already being paid : une autre demande de paiement pour la même commande était en cours au même moment. Le client doit patienter et consulter ses e-mails avant de réessayer.

Le remboursement échoue avec un message sur 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.

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 est injoignable, l'extension continue de fonctionner avec le dernier statut connu.

Pour les développeurs, la documentation de l'extension énumère les filtres culqi_p_supported_currencies, culqi_p_charge_data, culqi_p_icon et culqi_p_lock_timeout.

Désinstallation

Désactiver l'extension conserve toutes les données. Pour la supprimer, désactivez-la puis 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 sont conservés pour une réinstallation ultérieure. Les commandes existantes conservent leurs notes de paiement et leurs ID de transaction.

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