Connecter Payora à un site PHP personnalisé

Comment connecter Payora à un site PHP personnalisé

Si votre site repose sur une application PHP autonome, la marche à suivre est simple : créez un paiement, redirigez le client vers Payora, puis récupérez le résultat dans votre propre système de commandes. Pas besoin de WooCommerce ni de vous perdre dans un labyrinthe d’extensions.

Ce guide explique comment intégrer Payora à un site PHP personnalisé sans transformer votre processus de paiement en projet scientifique. Vous découvrirez précisément où PHP doit lancer le paiement, où récupérer le retour et où votre application doit déterminer si la commande est payée, en attente ou échouée.

1. Confirmez le modèle d’intégration de votre site PHP personnalisé

Commencez par décider ce que vous allez créer : un simple lien de paiement, une demande de paiement côté serveur ou un parcours de paiement complet avec suivi des commandes. Ce n’est pas la même chose. Un site de dons d’une seule page peut se contenter d’un lien de paiement, tandis qu’une boutique avec 20 produits a généralement besoin de créer les commandes côté serveur avant que le client quitte le site.

Pour un site PHP personnalisé, le modèle le plus propre consiste souvent à créer la commande dans votre système, à créer le paiement Payora depuis PHP, à rediriger le client, puis à traiter son retour et à vérifier la confirmation côté serveur. Vous disposez ainsi d’un enregistrement avant que l’argent ne change de mains. La logique du panier et de la facturation reste aussi dans votre application, là où elle doit être.

Si votre processus de paiement est très simple, une redirection vers une page de paiement hébergée par Payora peut suffire. Si vous avez besoin de détails sur les articles, de notes client ou d’identifiants de commande, votre code PHP doit transmettre ces informations avant la redirection. Simple, sans être simpliste.

Un exemple concret : une agence numérique qui vend une formule de maintenance en 3 étapes peut créer la commande en PHP, y associer l’adresse e-mail du client et le rediriger vers Payora avec la référence de facture. Un projet amateur qui vend une seule clé de licence n’aura peut-être besoin que d’un lien de paiement et d’une page de retour. La différence tient à la quantité d’informations d’état à conserver, pas au volume de code.

2. Définissez les pages, les points de terminaison et le parcours de session

Avant d’écrire du code, faites la liste des pages. Il vous en faut au moins trois : une page de paiement, une page de retour et un point de terminaison côté serveur pour confirmer le paiement. Sans cette cartographie, vous finirez par essayer de deviner quelle requête a modifié la commande. Et les suppositions coûtent cher.

Utilisez une session PHP classique pour le parcours dans le navigateur, mais ne vous fiez pas uniquement à la session. Elle peut disparaître si le client change d’appareil, ferme l’onglet ou revient de Payora plus tard. Conservez aussi l’identifiant de commande dans votre base de données, afin que votre code PHP puisse retrouver la transaction même si la session du navigateur n’existe plus.

Un parcours classique se déroule ainsi :

• La page de paiement recueille le produit, l’adresse e-mail et la quantité.
• PHP crée une commande locale avec le statut en attente.
• PHP redirige le client vers Payora.
• Payora renvoie le navigateur vers votre URL de retour.
• Votre serveur vérifie le statut du paiement avant de marquer la commande comme payée.

Ce parcours distingue la page de retour affichée dans le navigateur de la source de vérité côté serveur. Parfait. Elles doivent être distinctes. Le navigateur peut vous indiquer ce que le client a vu ; c’est à votre serveur de déterminer l’état réel de la commande.

Une petite habitude peut vous faire gagner des heures par la suite : enregistrez la référence du paiement Payora à côté de l’identifiant de commande dès la création du paiement. Si vous attendez la fin de la redirection, une erreur réseau ou un rafraîchissement impatient peut vous laisser avec une commande, mais sans référence Payora. Vous devrez alors jouer les détectives en production.

3. Préparez une couche PHP minimale pour les demandes de paiement

Gardez le code de paiement à l’écart des modèles. Une petite classe PHP ou une fonction utilitaire suffit. Une méthode peut construire la charge utile, une autre envoyer la requête HTTP et une troisième analyser la réponse. Cette séparation est importante, car la logique de paiement évolue plus souvent que le balisage des pages.

Par exemple, votre fonction utilitaire peut prendre un tableau contenant amount, currency, order_id et return_url, puis y ajouter vos identifiants Payora depuis des variables d’environnement. La page de paiement ne devrait jamais savoir où se trouve le jeton d’API. Elle doit seulement savoir sur quel bouton le client a cliqué.

Pour créer un paiement Payora en PHP, votre fonction utilitaire peut suivre cette structure générale, sans constituer une implémentation complète :

1. Récupérer la commande dans votre base de données.
2. Construire un tableau de requête Payora.
3. Envoyer la requête avec cURL ou un client HTTP similaire.
4. Enregistrer la référence de paiement Payora renvoyée.
5. Rediriger le client vers l’URL de paiement Payora.

Gardez cette fonction aussi sobre que possible. Un code sans fioritures est plus facile à tester et moins susceptible de casser lorsque vous modifiez le prix d’un produit ou ajoutez un deuxième formulaire de paiement le mois prochain.

Si votre application possède déjà une couche d’abstraction des paiements, utilisez-la. Sinon, créez un fichier et donnez-lui un nom explicite, par exemple PayoraClient.php. Ce fichier doit contenir les identifiants, les appels à l’API et l’analyse des réponses. Rien d’autre. Ni HTML, ni CSS, ni message de remerciement.

4. Redirigez le client vers Payora depuis votre page de paiement personnalisée

Une fois la commande locale créée, envoyez la demande de paiement à Payora, puis redirigez le client vers sa page de paiement. La redirection ne doit avoir lieu qu’après l’enregistrement de la commande sur votre serveur, car le client peut fermer l’onglet dès qu’elle commence.

Transmettez les détails de commande dont vous avez réellement besoin : généralement l’identifiant de commande, le montant, la devise et l’adresse e-mail du client. Vous pouvez aussi envoyer des métadonnées comme le nom du produit ou l’identifiant du compte interne, mais n’envoyez pas tous les champs de votre base de données simplement parce qu’ils sont disponibles. Ces données supplémentaires peuvent compliquer la comparaison des dossiers par le service client.

Une page de paiement personnalisée utilise souvent un formulaire POST avec un bouton « Payer maintenant ». Le formulaire est envoyé à votre point de terminaison PHP, qui crée le paiement Payora puis renvoie une redirection. Le client ne voit jamais la réponse de l’API : il ne voit que Payora.

Un conseil important : ne faites pas confiance aux totaux calculés côté client. Si votre page produit affiche 49 $ et que le navigateur envoie 39 $, votre serveur doit rejeter cet écart. La demande de paiement doit être créée à partir du total de la commande calculé côté serveur, et non à partir de la valeur cachée dans le formulaire. Cette règle est essentielle.

Pour avoir une vue d’ensemble des modèles de configuration des paiements, consultez le guide sur les passerelles de paiement crypto pour le commerce en ligne, qui apporte des éléments utiles sans reprendre ici le parcours PHP.

5. Récupérez et validez le résultat du paiement dans votre application

L’URL de retour dans le navigateur est utile, mais elle ne fait pas foi à elle seule. Elle peut indiquer que la page de paiement a été visitée et transmettre un statut, mais votre application PHP doit considérer ce résultat comme provisoire tant que le serveur ne l’a pas confirmé. « En attente » ne signifie pas « payé ».

Votre page de retour doit gérer trois cas : réussite, attente et échec. Si Payora indique que le paiement a réussi, affichez une page de remerciement et précisez au client que la commande est en cours de confirmation. Si le statut est « en attente », dites-le clairement. En cas d’échec, invitez le client à réessayer sans supprimer la commande. Des messages clairs réduisent le nombre de demandes adressées au service client.

Voici une règle utile : la page de retour ne doit jamais marquer à elle seule la commande comme payée. Elle doit uniquement afficher son état actuel et, éventuellement, proposer un lien vers la page de commande. La mise à jour de la base de données intervient après vérification, et non après une redirection du navigateur. Cette distinction vous protège contre les mises à jour accidentelles en double.

Faites en sorte que le point de terminaison de retour soit assez simple pour être compris d’un coup d’œil. S’il reçoit une référence de paiement Payora, recherchez-la. Si la référence est absente, consignez la requête et arrêtez le traitement. Si la commande est déjà payée, affichez un message aimable sans rien modifier. C’est ainsi qu’un parcours idempotent reste stable malgré les rafraîchissements répétés.

Pour les équipes qui souhaitent aussi comparer différents parcours de paiement, l’article sur l’acceptation des paiements en cryptomonnaie contient des conseils de facturation utiles, notamment si vous vendez des services avec des factures récurrentes ou des validations manuelles.

6. Confirmez la transaction côté serveur avant de marquer la commande comme payée

C’est l’étape la plus sûre. Votre application PHP doit interroger Payora côté serveur et confirmer le statut d’un paiement Payora avant de marquer la commande comme payée. Une redirection dans le navigateur peut omettre des informations ; les vérifications côté serveur, elles, ne se soucient pas de savoir si le client a fermé l’onglet, actualisé la page deux fois ou utilisé un autre appareil.

Utilisez la référence de paiement Payora enregistrée précédemment, puis demandez le statut actuel de la transaction. Comparez le statut renvoyé à celui qui est requis pour traiter la commande. Si la transaction est réglée ou confirmée, mettez à jour la commande. Si elle est en attente, laissez-la en attente. Si elle a échoué ou a été annulée, ne modifiez pas la commande.

Petite remarque : c’est à cette étape que beaucoup de sites PHP personnalisés manquent de rigueur. Ils font confiance à la page de retour parce que c’est plus rapide à coder. Plus rapide, oui. Plus sûr, non. Une vérification de 5 secondes vaut mieux qu’un échange d’e-mails avec le service client par la suite, à tous les coups.

Si Payora propose un rappel signé ou un mécanisme de confirmation serveur à serveur, utilisez-le en complément de la vérification du statut. Vous bénéficiez ainsi de deux contrôles : l’un lié au parcours client et l’autre au parcours serveur. Si votre implémentation nécessite une vérification de signature étape par étape, consultez le guide sur les tests de paiement crypto pour découvrir les bonnes pratiques de validation à appliquer avant le lancement.

Ne marquez la commande comme payée qu’après confirmation du serveur. Pas après l’affirmation du client. Ni après celle du navigateur. Votre base de données doit refléter l’état du paiement confirmé par Payora, car c’est cet état auquel vos équipes de traitement des commandes et de comptabilité se fieront par la suite.

7. Enregistrez le paiement et gérez les demandes en double

Enregistrez dans votre base de données la référence de transaction Payora, l’identifiant de commande local, le montant, la devise et le statut final. Si possible, faites-le en une seule opération d’écriture. Lorsqu’un client vous écrira « J’ai payé deux fois », vous aurez besoin d’un dossier clair, et non de trois mises à jour incomplètes.

Les soumissions en double ont des causes tout à fait ordinaires : le client clique deux fois, utilise le bouton Précédent ou le navigateur réessaie la requête. Votre code PHP doit détecter si une référence Payora est déjà associée à la commande et refuser de créer un deuxième paiement pour la même commande, sauf si le premier a échoué ou a expiré. C’est le principe fondamental de l’idempotence.

Une règle simple fonctionne bien : une commande locale, une transaction Payora active. Si une deuxième requête arrive pour la même commande alors que la première est en attente, affichez le lien de paiement Payora existant au lieu d’en créer un nouveau. Si la commande est déjà payée, ne faites rien. Sans bruit. C’est voulu.

Choisissez des noms précis pour les colonnes de votre base de données. Par exemple, utilisez payora_reference, payment_status, paid_at et last_checked_at. Ces champs sont utiles au service client, à la comptabilité et au débogage. Si vous devez ensuite rapprocher un paiement, ces quatre champs répondront à la plupart des questions sans vous obliger à passer une heure à fouiller les journaux.

Si vous créez un parcours de facturation client plutôt qu’un paiement en boutique, l’article sur les passerelles de paiement crypto pour les travailleurs indépendants peut également vous aider à appliquer la même logique de suivi, notamment lorsque les numéros de facture importent davantage que les paniers.

8. Testez l’ensemble du parcours sur une copie de préproduction du site

Avant la mise en ligne, clonez le site dans un environnement de préproduction et testez toute la chaîne : création de la commande, redirection vers Payora, page de retour, vérification côté serveur et gestion des clics en double. Si vous ne testez que la redirection, vous n’aurez vérifié qu’un tiers du parcours.

Effectuez au moins les vérifications suivantes :

• Créez une commande et vérifiez que la demande de paiement Payora est générée.
• Actualisez la page de retour 2 fois et vérifiez que la commande n’est pas modifiée à nouveau.
• Envoyez le formulaire de paiement deux fois et vérifiez qu’une seule transaction active existe.
• Provoquez un résultat « en attente » ou un échec et vérifiez que la commande reste impayée.
• Vérifiez que la référence Payora enregistrée correspond à celle du dossier dans la base de données.

Effectuez les tests avec la version de PHP et la configuration du serveur que vous comptez utiliser en production. Un parcours qui fonctionne sur un ordinateur local peut échouer sur un serveur de production avec une configuration SSL plus stricte ou des paramètres cURL différents. Ce n’est pas rare. Ça arrive.

Dernier test pratique : ouvrez la commande dans une fenêtre de navigation privée, effectuez le paiement, puis ouvrez la même URL de retour dans un deuxième navigateur. Votre application ne doit pas effectuer une deuxième mise à jour du paiement. Si c’est le cas, corrigez le problème avant le lancement. Sans exception.

Pour les équipes qui proposent le paiement en USDC en plus d’autres moyens de paiement, les conseils de l’article sur l’acceptation des paiements en USDC vous aideront à comparer les attentes des clients avant de mettre en production votre parcours PHP.

Il reste une dernière chose à vérifier : une même commande doit rester cohérente après une redirection, un rafraîchissement et une confirmation côté serveur. Si c’est le cas, votre processus de paiement PHP personnalisé est prêt pour son premier paiement en production.