VibeFox Pin Payments 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 Pin Payments : un compte marchand Pin Payments (pour les entreprises d'Australie ou de Nouvelle-Zélande ; les clients peuvent payer depuis n'importe où). Il vous faut sa clé publique et sa clé secrète, pour la production et, pour les tests, pour l'environnement de test. Aucun secret de webhook n'est nécessaire : le module n'utilise pas de webhooks. Les données de carte sont envoyées depuis le navigateur du client directement à Pin Payments par Pin.js et n'atteignent jamais votre boutique, de sorte que la boutique relève de PCI SAQ A-EP.

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 Pin Payments Gateway 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. Dans le tableau de bord Pin Payments, ouvrez Account > API Keys et copiez vos clés de test dans Test publishable key et Test secret key. Laissez Test mode activé, activez Enable/Disable et cliquez sur Save.

5. Passez une commande de test avec une carte de test Pin Payments. Lorsque tout fonctionne, saisissez les clés de production, désactivez Test mode et enregistrez.

À l'installation, le module crée le statut de commande Pin Payments payment on hold. PrestaShop propose un nouveau module de paiement pour les devises, les groupes de clients et les pays actifs au moment de l'installation. Vous pouvez modifier cela dans Payment > Preferences ; les pays que vous activez plus tard doivent y être cochés.

Configuration

Tous les réglages se trouvent sur la page du module : Modules > Module Manager > VibeFox Pin Payments Gateway > Configure. Chaque section a son propre bouton Save, qui enregistre la page entière. Au-dessus des champs, la page affiche un avertissement tant que le mode test est activé, une erreur lorsque la clé publique ou la clé secrète du mode actuel est vide, et une erreur lorsque Pin Payments ne prend pas en charge la devise par défaut de la boutique (avec la liste des devises prises en charge). Sans les deux clés du mode actuel, le mode de paiement est masqué sur la page de paiement. Un Title vide n'est pas enregistré : la page affiche Enter a title for the payment method.

Pin Payments

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

Title: le nom du mode de paiement que les clients voient sur la page de paiement. C'est aussi le nom du mode de paiement enregistré dans la commande. Par défaut : Credit card (Pin Payments). Obligatoire.

Description: le texte affiché sous le mode de paiement sur la page de paiement. Par défaut : Pay with your credit card via Pin Payments.

Clés d'API

Retrouvez vos clés dans le tableau de bord Pin Payments, sous Account > API Keys. Les clés de test ne fonctionnent qu'avec l'API de test, les clés de production uniquement avec l'API de production. La clé publique est utilisée par Pin.js dans le navigateur du client. La clé secrète ne quitte jamais votre serveur.

Test mode: utilise l'environnement de test de Pin Payments (test-api.pinpayments.com) et les clés de test. Aucun débit réel n'est effectué, et les clients voient TEST MODE — no real charges will be made. sous le mode de paiement. Lorsqu'il est désactivé, l'API de production et les clés de production sont utilisées. Par défaut : activé.

Test publishable key: la clé publique de votre compte de test Pin Payments.

Test secret key: la clé secrète de votre compte de test Pin Payments.

Live publishable key: la clé publique de votre compte de production Pin Payments.

Live secret key: la clé secrète de votre compte de production Pin Payments.

Les espaces autour des clés sont supprimés. 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. Ne saisissez une nouvelle valeur que pour la modifier.

Clear saved secrets: cochez une clé secrète et cliquez sur Save pour la supprimer. Un champ vide conserve la valeur enregistrée.

Avancé

Debug log: écrit dans logs/wc_ppg_debug.log.php dans le dossier du module. Le fichier ne peut pas être ouvert depuis le web. Les erreurs sont toujours journalisées ; activez ce réglage pour journaliser aussi chaque appel à l'API. Les données de carte, les clés d'API et les données personnelles des 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 du module supprime les réglages de la passerelle et le journal. Les données de paiement des commandes (débits et remboursements) et le statut de commande Pin Payments payment on hold sont toujours conservés. Par défaut : désactivé.

Page de paiement

Le mode de paiement s'affiche lorsqu'il est activé, que les deux clés du mode actuel sont renseignées, que la devise du panier fait partie des 14 devises prises en charge (AUD, USD, NZD, SGD, EUR, GBP, CAD, HKD, JPY, MYR, THB, PHP, ZAR, IDR) et que le module est autorisé pour le panier dans Payment > Preferences.

À l'étape de paiement, le client choisit le mode de paiement (par défaut Credit card (Pin Payments), avec les icônes Visa, Mastercard et American Express) et remplit Card number, Expiry (MM / YY), CVC et Name on card. Avant l'envoi, le formulaire vérifie la longueur du numéro de carte, le mois et l'année d'expiration, un CVC de 3 ou 4 chiffres et le nom.

Lorsque le client passe la commande, Pin.js envoie les données de la carte et l'adresse de facturation du panier directement depuis le navigateur à Pin Payments et obtient un jeton de carte à usage unique. Seul ce jeton est envoyé à votre boutique. Le module crée alors un débit capturé pour le total du panier dans la devise du panier, avec l'adresse e-mail du client et la description <shop name> - Cart <cart number>. Pin Payments répond dans la même requête. Aucune commande n'existe avant cette réponse.

Après un débit réussi, la commande est créée et le client voit la page standard de confirmation de commande avec Your card payment has been received. Si la commande est passée en Pin Payments payment on hold, la page affiche Your card payment has been received and is being reviewed. We will update your order as soon as the review is complete.

Si Pin Payments ne répond pas (délai dépassé, erreur serveur, réponse illisible), un débit peut néanmoins avoir été créé. La commande est alors créée en Pin Payments payment on hold sans paiement, et la page de confirmation affiche We could not confirm your payment with Pin Payments. Please check your e-mail and card statement before paying again, or contact us. Soumettre à nouveau le même panier ne crée jamais un second débit.

Une seule tentative de paiement par panier s'exécute à la fois. Une seconde soumission reçoit This order is already being paid. Please wait a moment and check your e-mail before trying again. Un panier qui a déjà une commande, ou une tentative antérieure qui a encaissé ou a pu encaisser de l'argent, n'est pas débité à nouveau ; la commande est créée à partir de cette tentative. Un jeton de carte ne peut être utilisé qu'une fois : après une tentative échouée, ou lorsque le client modifie les données de sa carte, un nouveau jeton est créé.

Lorsque le paiement échoue, aucune commande n'est créée. Le client reste à l'étape de paiement, le panier est conservé et l'un de ces messages s'affiche : Your card was declined. Please use another card or contact your bank. ; Your card has insufficient funds. Please use another card. ; Your card has expired. Please use another card. ; The card security code (CVC) is incorrect. ; This card type is not accepted. Please use Visa, Mastercard or American Express. ; Payment failed: avec le motif donné par Pin Payments pour les données rejetées ; Your card details have expired. Please enter them again and retry. lorsque le jeton ne peut pas être utilisé ; The secure card form could not be loaded. Please reload the page or choose another payment method. lorsque Pin.js ne se charge pas ; Card payments are temporarily unavailable. Please try again later or choose another payment method. lorsque Pin Payments rejette la clé secrète ; Your payment could not be processed. Please try again or choose another payment method. pour les autres erreurs. Le motif technique est écrit dans le journal.

Le module n'a pas de flux 3-D Secure. Si votre compte Pin Payments exige 3-D Secure, le débit reste en attente, aucune commande n'est créée et le client voit Your card payment could not be completed (additional verification is required). Please try another card or another payment method. Il n'existe pas de mode autorisation seule avec capture ultérieure, ni cartes enregistrées, ni abonnements, ni Apple Pay ou Google Pay, ni webhooks.

Commandes et remboursements

Statuts de commande

No order yet: la carte a été refusée, le débit nécessitait 3-D Secure, ou le client n'a pas payé. Seul le panier existe.

Payment accepted: Pin Payments a signalé un débit réussi et capturé pour exactement le montant et la devise du panier. Le paiement est enregistré avec le jeton de débit Pin Payments comme ID de transaction, et une note affiche le montant et le jeton de débit (et TEST MODE pour les paiements de test).

Pin Payments payment on hold: le débit nécessite votre examen. La note en explique la raison : Pin Payments a débité un montant ou une devise différents de ceux du panier (le paiement du montant débité est enregistré), le panier a changé pendant le paiement, le débit est autorisé mais non capturé (capturez-le dans le tableau de bord Pin Payments, puis passez la commande à Paiement accepté), ou Pin Payments n'a pas donné de réponse claire (aucun paiement n'est enregistré ; recherchez la description du débit dans le tableau de bord Pin Payments avant l'expédition de la commande).

Refunded: le débit a été entièrement remboursé via le module.

Si un second débit est effectué pour un panier qui a déjà une commande, la commande n'est pas modifiée. Une note vous demande de le vérifier et de le rembourser dans le tableau de bord Pin Payments.

Bloc Pin Payments

La page de commande affiche un bloc Pin Payments avec un badge Test mode pour les paiements de test, le jeton de débit, le statut, la marque de carte et les quatre derniers chiffres, le montant débité, le total de la commande et le montant remboursé, la Description at Pin Payments, l'historique des remboursements et les Pin Payments notes de la commande.

Remboursements

Dans le bloc Pin Payments, saisissez le montant (le montant non encore remboursé est prérempli), facultativement un motif, puis cliquez sur Refund via Pin Payments. Confirmez la question Refund this amount through Pin Payments? This cannot be undone. Les remboursements totaux et partiels sont pris en charge. Vous devez disposer du droit de modifier les commandes. Les remboursements sont limités au montant et à la devise effectivement débités par Pin Payments ; ainsi, après un écart de montant ou de devise, vous pouvez rembourser jusqu'à hauteur de ce que le client a payé, et non le total de la commande. Le remboursement est envoyé à l'environnement (test ou production) dans lequel la commande a été payée ; la clé secrète de ce mode doit donc être renseignée. Pin Payments traite les remboursements de manière asynchrone, le statut est donc généralement en attente. Une requête réussie est ajoutée à l'historique des remboursements et aux notes, avec le jeton de remboursement Pin Payments et son statut. Un remboursement total passe la commande à Refunded. Un remboursement partiel ne modifie pas le statut. Si Pin Payments rejette le remboursement ou ne répond pas, le bloc affiche l'erreur et aucun remboursement n'est enregistré.

Lorsqu'aucun débit n'est enregistré pour la commande (Pin Payments n'a donné aucune réponse claire), le bloc n'affiche aucun formulaire de remboursement et indique la description à rechercher dans le tableau de bord Pin Payments.

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 Pin Payments. Les remboursements effectués dans le tableau de bord Pin Payments ne sont pas synchronisés avec PrestaShop : effectuez-les donc depuis la page de commande.

Clé de licence

Le module fonctionne avec une clé de licence VibeFox obtenue sur vibefox.net. Le bloc de licence License — VibeFox Pin Payments Gateway est le premier bloc de Modules > Module Manager > VibeFox Pin Payments Gateway > 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-pinpayments 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, Pin Payments n'est pas affiché 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. La vitrine 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 vous ne pouvez pas le tester à l'étape du paiement. Un rappel apparaît dans Modules > Module Manager, sous l'onglet Alerts. Les commandes existantes ne sont pas affectées : les remboursements de commandes payées auparavant fonctionnent toujours.

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é 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

Pin Payments 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 publishable key et Test secret key en mode test, les clés de production sinon) et que la devise du panier fait partie des 14 devises prises en charge. Dans Payment > Preferences, vérifiez que le module est autorisé pour la devise du panier, le pays du client et le groupe du client. La page des réglages affiche une erreur pour les clés manquantes et pour une devise de boutique non prise en charge.

Le paiement a abouti, mais la commande est en Pin Payments payment on hold : lisez les notes dans le bloc Pin Payments (voir Statuts de commande). Si Pin Payments n'a donné aucune réponse claire, recherchez dans le tableau de bord Pin Payments un débit portant la description <shop name> - Cart <cart number>, puis expédiez la commande ou remboursez le débit dans le tableau de bord.

Le client voit Your payment was received, but the order could not be completed automatically: la carte a été débitée, mais PrestaShop n'a pas pu créer la commande (par exemple, parce que le module a été désactivé entre-temps). La raison figure dans le journal. Le client est invité à ne pas payer à nouveau ; soumettre à nouveau le même panier crée la commande sans nouveau débit.

Les clients voient Card payments are temporarily unavailable: Pin Payments a rejeté la clé secrète, ou la clé du mode actuel est absente. Les clés de test ne fonctionnent qu'en mode test, les clés de production uniquement en mode production. Le journal indique la raison.

Les commandes échouent avec additional verification is required: votre compte Pin Payments exige 3-D Secure, que le module ne prend pas en charge. Demandez à Pin Payments de désactiver le 3-D Secure obligatoire.

Le formulaire de carte sécurisé n'a pas pu être chargé : Pin.js depuis le CDN de Pin Payments ne s'est pas chargé dans le navigateur, par exemple à cause d'un bloqueur de scripts ou d'un module qui combine ou modifie les scripts. Excluez la page de paiement de ces optimisations.

Pin Payments n'a pas répondu : le jeton de carte n'a pas été créé dans les 30 secondes dans le navigateur. Le client peut vérifier la connexion et réessayer ; rien n'a été débité.

Paiement échoué avec un motif de Pin Payments : Pin Payments a rejeté les données du débit, par exemple un montant inférieur à son débit minimum pour la devise. Le client voit le motif, et le journal contient le code d'erreur.

Échec du remboursement : lisez le message dans le bloc. Un message concernant le mode TEST ou LIVE signifie que la clé secrète du mode dans lequel la commande a été payée est vide. Pin Payments did not confirm the refund signifie qu'aucune réponse n'est parvenue ; vérifiez le débit dans le tableau de bord Pin Payments avant de réessayer. at most indique le montant encore remboursable sur le débit.

Paiements de test : le mode test utilise l'environnement de test et les clés de test. Utilisez les cartes de test de la documentation développeur de Pin Payments, par exemple 4200 0000 0000 0000 (réussi) ou 4100 0000 0000 0001 (refusé), avec n'importe quelle date d'expiration future et n'importe quel CVC. Les commandes conservent le mode dans lequel elles ont été payées, de sorte que les remboursements vont dans le bon environnement après un changement de mode.

Où trouver les erreurs : les erreurs sont toujours écrites dans le journal ; voir le champ Log sur la page du module. Activez Debug log pour voir chaque appel à l'API.

Désinstallation

Allez dans Modules > Module Manager, ouvrez le menu à côté de VibeFox Pin Payments Gateway 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 débits et remboursements Pin Payments ainsi que le statut de commande Pin Payments payment on hold 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 et leurs ID de transaction.

Pin Payments est une marque de commerce de son titulaire respectif. Ce module n'est ni affilié à Pin Payments ni approuvé par Pin Payments.