VibeFox 2C2P for PrestaShop — Aide

Prérequis

PrestaShop : 8.0 à 9.x.

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

Compte 2C2P : vous avez besoin de l'identifiant marchand (Merchant ID) et de la clé secrète (Secret Key) de votre compte marchand 2C2P. 2C2P les délivre à l'ouverture de votre compte marchand. Les comptes sandbox et production ont des clés différentes. La documentation développeur et les cartes de test du sandbox se trouvent sur developer.2c2p.com.

Devise : la devise du panier doit être prise en charge par le module et activée sur votre compte 2C2P. Sont notamment prises en charge : THB, SGD, MYR, PHP, IDR, VND, MMK, KHR, LAK, CNY, HKD, TWD, JPY, KRW, INR, AUD, NZD, USD, EUR et GBP. Si la devise du panier n'est pas prise en charge, le moyen de paiement n'est pas affiché au moment du paiement.

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 2C2P Payment dans la liste des modules et cliquez sur Configure.

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

4. Saisissez votre identifiant marchand et votre clé secrète de sandbox, activez Enable/Disable, cliquez sur Save et passez une commande test.

5. Lorsque vous êtes prêt, saisissez les identifiants de production et désactivez Sandbox Mode.

À l'installation, le module crée deux statuts de commande : Awaiting 2C2P payment et 2C2P payment on hold. PrestaShop active le nouveau module de paiement pour toutes les devises, tous les pays et tous les groupes de clients. Vous pouvez restreindre cela dans Payment > Preferences. Les URL de retour et de notification sont envoyées à chaque paiement. Rien n'a besoin d'être configuré dans le portail 2C2P.

Configuration

Tous les réglages se trouvent sur la page du module : Modules > Module Manager > VibeFox 2C2P Payment > Configure. Chaque section a son propre bouton Save, qui enregistre la page entière. Au-dessus des champs, la page affiche Sandbox mode is active. No real transactions will be processed. tant que le mode sandbox est activé. Elle vous avertit lorsque la passerelle est activée mais que le Merchant ID ou la Secret Key du mode en cours est vide, et lorsque la devise par défaut de la boutique n'est pas prise en charge. Dans les deux cas, le moyen de paiement est masqué au moment du paiement. Si vous enregistrez avec Sandbox Mode désactivé, le module affiche Please enter your live Merchant ID. ou Please enter your live Secret Key. si un champ de production est vide. Les réglages sont tout de même enregistrés.

2C2P

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

Title : le nom du moyen de paiement que voit le client au moment du paiement. C'est aussi le nom du moyen de paiement enregistré dans la commande. Par défaut : 2C2P Payment.

Description : le texte affiché sous le moyen de paiement au moment du paiement. Par défaut : Pay securely via credit/debit card, e-wallet, or internet banking through 2C2P. En mode sandbox, (TEST MODE) lui est ajouté.

Mode test (sandbox)

Sandbox Mode : envoie les paiements vers le sandbox 2C2P (demo2.2c2p.com) avec les identifiants sandbox ci-dessous. Par défaut : activé. Désactivez-le pour encaisser de vrais paiements.

Sandbox Merchant ID : votre identifiant marchand 2C2P sandbox.

Sandbox Secret Key : votre clé secrète 2C2P sandbox.

Identifiants API de production

Utilisés lorsque le mode sandbox est désactivé.

Merchant ID : votre identifiant marchand 2C2P de production.

Secret Key : votre clé secrète 2C2P de production. La clé est enregistrée exactement telle que vous la saisissez, y compris les guillemets et les barres obliques inverses.

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. Ne saisissez une nouvelle valeur que pour la modifier.

Effacer les secrets enregistrés : cochez Sandbox Secret Key ou Secret Key, puis cliquez sur Save pour la supprimer. Un champ vide conserve la valeur enregistrée.

Les résultats sont toujours vérifiés avec le Merchant ID et la Secret Key du mode dans lequel le paiement a été effectué. Un paiement lancé en mode sandbox reste vérifié avec la clé sandbox après le passage en production, et un résultat signé avec la clé de l'autre mode est rejeté.

Page de paiement

URL de résultat : affiche, à titre de référence, la Frontend return URL et la Backend notification URL. Avec les URL conviviales, elles ressemblent à https://your-shop/module/wcp_2c2p_payment/return et https://your-shop/module/wcp_2c2p_payment/notify, éventuellement avec un code de langue comme /en/. Elles sont envoyées automatiquement à chaque paiement.

Payment Page Language : la langue de la page de paiement 2C2P. Par défaut : English.

Redirect API version : gardez 8.5, sauf si 2C2P vous a indiqué que votre compte utilise encore l'ancienne version 7.0 (signatures SHA-1). Les résultats des paiements commencés avant un changement sont toujours vérifiés.

Order ID prefix : facultatif, lettres et chiffres uniquement (10 caractères maximum), par exemple SHOP1. 2C2P refuse un identifiant de commande qu'il a déjà reçu. Définissez un préfixe unique lorsque plusieurs boutiques partagent un compte 2C2P, et en sandbox, où les comptes marchands de test sont partagés. Les autres caractères sont supprimés à l'enregistrement, avec un avertissement.

Réglages avancés

Enable Logging : écrit les événements 2C2P dans logs/tc2p_p_debug.log.php, dans le dossier du module. Le fichier ne peut pas être ouvert depuis le web. Aucune donnée de carte, clé secrète, adresse e-mail de client ni jeton de paiement n'est journalisé. Par défaut : désactivé. Tant qu'il est désactivé, rien n'est écrit, erreurs comprises.

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 transactions 2C2P, les commandes et les statuts de commande du module sont toujours conservés, afin qu'un résultat tardif d'un ancien paiement soit encore traité après une réinstallation. Par défaut : désactivé.

Paiement

À l'étape de paiement, le client choisit le moyen de paiement (par défaut 2C2P Payment) et confirme. La page suivante affiche Thank you for your order. You will be redirected to 2C2P to complete your payment. et envoie le client vers la page de paiement 2C2P après un court instant. Si cela ne se produit pas, le client clique sur Pay via 2C2P. La page comporte aussi un bouton Back to checkout. Aucune commande n'existe encore à ce stade.

Sur la page 2C2P, le client paie avec n'importe quel moyen activé sur votre compte 2C2P, par exemple cartes, portefeuilles électroniques, paiements par QR code, banque en ligne ou paiements en espèces. Le module transmet le total du panier dans la devise du panier, l'adresse e-mail du client et les noms des produits du panier. Le paiement peut être finalisé dans les 24 heures. Chaque tentative de paiement reçoit son propre identifiant de commande 2C2P (le numéro de panier et le numéro de tentative, après le préfixe facultatif), car 2C2P n'accepte jamais deux fois le même identifiant de commande.

2C2P transmet le résultat deux fois : le navigateur du client revient vers la boutique, et 2C2P envoie une notification serveur à serveur. Les deux sont traités de la même façon. La commande n'est marquée comme payée qu'après que 2C2P l'a confirmée avec une signature valide. Le résultat doit aussi appartenir au paiement : l'identifiant de commande 2C2P doit avoir été émis par votre boutique, et l'identifiant marchand ainsi que le jeton aléatoire de la tentative sont vérifiés. Les résultats sans signature valide sont rejetés. La notification fonctionne même lorsque la boutique est en mode maintenance, et elle n'est pas bloquée par la restriction de pays de votre boutique.

Après un paiement réussi, la commande est créée et le client voit la page standard de confirmation de commande avec Your 2C2P payment has been received. Pour un paiement en attente, la page affiche Your 2C2P payment is pending (for example a cash or bank payment that is not made yet). The order will be processed as soon as 2C2P confirms the payment. Pour une commande mise en attente, elle affiche Your payment was received and is being reviewed by the shop. Si un paiement en attente est annulé par la suite, elle affiche Your 2C2P payment was not completed. Please contact us about this order.

Si le paiement n'a pas été finalisé, aucune commande n'est créée. Le client revient à l'étape de paiement avec le message Payment was not completed. Please try again or choose a different payment method. Le panier est conservé, et le client peut payer à nouveau ou choisir un autre moyen de paiement. Si le résultat ne peut pas être confirmé, le client voit We could not confirm the payment result. If your account was charged, please contact us before paying again. Si le paiement ne peut pas être lancé, par exemple parce que la devise du panier n'est pas prise en charge, le message est This payment method is currently unavailable for this order. Please contact us or choose another payment method.

Si le panier a déjà une commande (payée ou en attente d'un paiement en attente), aucun second formulaire de paiement n'est généré. Le client est renvoyé vers la page de confirmation de commande.

Le module ne gère pas les remboursements depuis PrestaShop, ni les cartes enregistrées, ni les paiements récurrents ou abonnements, ni les champs de carte sur votre site, et il ne prend pas en charge l'API 2C2P PGW 4.x.

Commandes

Statuts de commande

No order yet : le client a été envoyé vers 2C2P et aucun résultat n'est encore arrivé, ou le paiement a échoué. Seul le panier existe.

Payment accepted : 2C2P a signalé un paiement réussi (statut 000). Le paiement est enregistré avec la référence de transaction 2C2P comme identifiant de transaction. Une note privée sur la commande affiche la transaction 2C2P, le code d'autorisation, la date et le canal de paiement.

Awaiting 2C2P payment : le paiement est en attente chez 2C2P (statut 001), par exemple un paiement en espèces que le client n'a pas encore effectué. La commande passe en Payment accepted lorsque 2C2P signale le paiement.

2C2P payment on hold : 2C2P a signalé un montant ou une devise différent du total de la commande. La note affiche les valeurs reçues et attendues. Vérifiez la commande et la transaction dans le portail 2C2P.

Canceled : un paiement en attente a ensuite été refusé, annulé ou a échoué (statuts 002, 003, 999). La note affiche le statut et la raison. Un résultat d'échec d'une tentative plus ancienne n'annule pas une commande créée par une autre tentative.

Une commande payée n'est jamais modifiée par un résultat ultérieur, et un ancien résultat répété ne rouvre pas une commande annulée. Si un second paiement arrive pour une commande déjà payée, la commande n'est pas modifiée. Une note vous demande de la vérifier et de rembourser le doublon dans le portail marchand 2C2P.

Bloc de paiement 2C2P

La page de commande affiche un bloc 2C2P payment avec l'identifiant de commande 2C2P, la transaction, le statut du paiement, le canal, le code d'autorisation, le numéro de carte masqué, la date, la réponse du canal et le montant reçu, ainsi qu'un badge Sandbox pour les paiements sandbox.

Remboursements

Les remboursements depuis PrestaShop ne sont pas pris en charge. Remboursez le paiement dans le portail marchand 2C2P, puis enregistrez le remboursement manuellement dans PrestaShop.

Clé de licence

Le module fonctionne avec une clé de licence VibeFox obtenue sur vibefox.net. Le bloc de licence License — VibeFox 2C2P Payment est le premier bloc de Modules > Module Manager > VibeFox 2C2P Payment > 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) 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: presta-payment-2c2p 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 : le domaine 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 cet emplacement dans votre compte vibefox.net.

Sans clé active, 2C2P n'est pas affiché aux clients au moment 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 au moment du paiement. Un rappel apparaît dans Modules > Module Manager, sur 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 votre travail 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

2C2P n'apparaît pas au moment du paiement : vérifiez que la licence est active, que Enable/Disable est activé et que le mode en cours dispose d'un Merchant ID et d'une Secret Key : les champs sandbox en mode sandbox, les champs de production en mode production. Vérifiez que la devise du panier est prise en charge. La page des réglages affiche un avertissement dans les deux cas. 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 : aucun résultat valide n'a atteint votre boutique. Vérifiez que le Merchant ID et la Secret Key du mode dans lequel le paiement a été effectué correspondent à votre compte 2C2P, et que Redirect API version correspond à votre compte. Un résultat avec une mauvaise signature ou pour un autre identifiant marchand est rejeté. Activez Enable Logging et recherchez des messages de hash ou d'identifiant marchand dans le champ Log. Vérifiez aussi que votre serveur accepte les requêtes de 2C2P vers l'URL de notification backend.

La notification backend répond 400 FAIL : le résultat contient des champs manquants, une mauvaise signature, un autre identifiant marchand ou un mauvais jeton. 404 FAIL signifie que l'identifiant de commande 2C2P n'a pas été émis par cette boutique. 503 RETRY signifie que la commande était en cours de confirmation par une autre requête au même moment, ou que la commande n'a pas pu être créée (par exemple parce que le module est désactivé) ; 2C2P réessaiera plus tard. Activez Enable Logging pour voir la raison.

L'URL de notification affiche FAIL dans le navigateur : c'est normal. Cette URL n'accepte que les requêtes POST de 2C2P.

2C2P indique que l'identifiant de commande existe déjà : 2C2P n'accepte pas deux fois le même identifiant de commande. Cela arrive lorsque plusieurs boutiques partagent un compte 2C2P ou en sandbox, où les comptes marchands de démonstration sont partagés par de nombreux développeurs. Définissez un Order ID prefix unique.

Un paiement a été effectué mais la commande est en Awaiting 2C2P payment ou 2C2P payment on hold : soit le paiement est toujours en attente chez 2C2P (par exemple un paiement en espèces que le client n'a pas encore effectué), soit le montant ou la devise payés ne correspondaient pas à la commande. Vérifiez les notes de la commande et la transaction dans le portail 2C2P.

Le client voit This payment method is currently unavailable for this order : la devise du panier n'est pas prise en charge, le Merchant ID ou la Secret Key du mode en cours est vide, ou le total du panier est nul.

Please enter your live Merchant ID ou Please enter your live Secret Key à l'enregistrement : le mode sandbox est désactivé et un champ de production est vide. Saisissez les identifiants de production ou gardez Sandbox Mode activé.

Désinstallation

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

2C2P est une marque déposée de son titulaire. Ce module n'est ni affilié à 2C2P ni approuvé par 2C2P.