Une redirection vers la banque n’est pas une preuve de paiement. Une intégration fiable sépare l’expérience du client, la création de la commande et la confirmation technique envoyée par le prestataire.

Préparer le contrat et les URL

L’identifiant marchand, la clé de signature, l’environnement de test et les URL de retour doivent correspondre au dossier CMI. Le site a besoin de HTTPS public pour recevoir la notification serveur. Gardez les clés hors du code, des captures d’écran et des dépôts Git.

Créer la commande sur le serveur

Le navigateur ne doit pas choisir le montant, la devise ou l’identifiant de commande. Le serveur lit le catalogue, crée un identifiant unique, conserve le montant et signe uniquement les champs attendus par la passerelle. Cette frontière empêche un visiteur de modifier le prix avant la redirection.

Faire confiance à la notification signée

La notification serveur à serveur vérifie la signature, l’identifiant, le montant, la devise et le code de retour. Une page de succès ne fait qu’afficher l’état enregistré. Les notifications répétées doivent être acceptées sans créer une deuxième commande ni demander une deuxième capture.

Tester les échecs autant que le succès

Vérifiez une carte refusée, un navigateur fermé, une notification en retard, une valeur modifiée et une signature invalide. Le journal des événements doit permettre de reconstruire le parcours. Les emails client et interne partent après la confirmation, jamais avant.

Comprendre les trois acteurs du parcours

Le client voit votre site, puis la page de paiement hébergée par CMI. Votre serveur reste responsable de la commande : il calcule le montant, génère l’identifiant, conserve le contexte et signe les données transmises. CMI traite la carte, l’authentification bancaire et l’autorisation. Enfin, la notification de rappel informe votre serveur du résultat. Cette séparation évite qu’un formulaire modifié dans le navigateur puisse décider du prix ou du statut.

La page de retour navigateur sert à améliorer l’expérience, pas à prouver le paiement. Elle peut afficher un statut en attente, confirmé ou échoué selon ce que votre serveur a déjà enregistré. Si le client ferme son navigateur après paiement, la notification serveur doit quand même mettre la commande à jour.

Préparer les valeurs marchandes avec méthode

L’identifiant client, la clé de signature, l’environnement, la devise et les URL doivent être cohérents. La clé de signature ne doit jamais être visible dans le HTML, dans Git, dans un message ou dans public_html. Conservez-la dans un fichier privé hors racine web ou dans les variables d’environnement de l’hébergement. Les URL de succès, d’échec et de rappel doivent être en HTTPS public et correspondre exactement au domaine déployé.

Choisissez aussi votre politique de capture. Une réponse ACTION=POSTAUTH peut demander la capture automatique après autorisation. Une approbation simple conserve l’autorisation pour une action manuelle. Ce choix a des conséquences commerciales et comptables : il doit être décidé avant les tests, pas après une commande réelle.

Construire une commande verrouillée

La commande stockée côté serveur doit contenir le plan ou produit, le montant calculé, la devise, la langue, les informations de facturation validées, un identifiant unique et la valeur rnd. Les champs envoyés à CMI sont préparés à partir de cet enregistrement, jamais à partir d’un montant fourni librement par le navigateur. Lorsque la notification revient, le serveur compare la signature, l’identifiant marchand, la devise, le montant, l’identifiant de commande et le rnd original.

Cette verrouillage empêche aussi les doublons. Si la même notification arrive deux fois, la commande existe déjà et le serveur peut répondre correctement sans créer une deuxième demande de capture. L’état doit garder une trace des événements : création, retour navigateur, autorisation, échec, capture demandée et emails envoyés.

Vérifier la signature avant toute décision

La validation de la signature doit précéder toute lecture métier du résultat. Les champs exclus, l’ordre de tri, l’échappement des caractères et l’encodage doivent suivre la documentation CMI exacte. Une signature invalide termine la requête ; on ne tente pas de « deviner » la commande à partir du navigateur ou d’un identifiant partiel.

Après signature, le code retour ProcReturnCode=00 signifie une autorisation réussie. Les autres codes doivent rester des échecs ou des états non confirmés, même si une page de retour paraît positive. Les détails comme TransId, HostRefNum, la carte masquée et la marque peuvent être conservés pour le suivi sans stocker de données de carte sensibles.

Tester les cas qui arrivent réellement

Le test ne se limite pas à une carte de succès. Prévoyez une autorisation réussie, un refus, une interruption du navigateur, un retour avant notification, une notification répétée, un montant modifié, une commande inconnue et une signature fausse. Vérifiez que les emails ne partent qu’après autorisation vérifiée et que l’utilisateur voit un message clair si la confirmation est en attente.

Contrôlez aussi la partie hébergement : PHP disponible, écriture dans le dossier privé, envoi mail() ou SMTP, journaux d’erreur, fuseau horaire et HTTPS. Sur un hébergement mutualisé, un détail comme une règle .htaccess, un proxy ou un dossier non accessible peut suffire à empêcher le callback d’arriver.

Checklist avant mise en production

  • Domaine HTTPS final en place et redirections propres.
  • Identifiants de test CMI configurés dans un fichier privé.
  • Une vraie transaction de test réussie et une transaction refusée.
  • Callback reçu depuis le domaine public et signature validée.
  • Commande stockée hors public_html, sans données de carte.
  • Emails client et administrateur reçus.
  • Mode de capture choisi et documenté.
  • Processus de remboursement, litige et support défini.
  • Identifiants de production séparés, jamais mélangés au test.

Une fois ces points validés, remplacez uniquement les valeurs d’environnement : identifiant, clé et URL de passerelle de production. Ne laissez jamais une configuration de test active sur une boutique qui encaisse réellement.

Questions à poser avant l’activation

Confirmez l’identifiant marchand, l’environnement, la clé de signature, les URL autorisées, la devise, la méthode 3D Pay Hosting et la politique de capture. Demandez comment consulter les transactions, traiter un remboursement et contacter le support. Vérifiez également si des IP ou domaines doivent être enregistrés pour le callback.

Plan d’action raisonnable

Déployez d’abord sur un domaine HTTPS, configurez les clés privées, puis effectuez une transaction de test réussie et une transaction refusée. Examinez la commande stockée, les événements et les emails. Documentez la procédure de bascule vers la production et conservez une copie des journaux utiles sans exposer la clé ou les données bancaires.

Checklist de sécurité

  • Clé de signature hors code, hors Git et hors racine publique.
  • Commande et montant créés côté serveur, jamais par le navigateur.
  • Signature, devise, client, montant, commande et rnd vérifiés au callback.
  • Notifications répétées acceptées sans double capture ni double email.
  • Journal des événements exploitable par le support et la technique.

Le signal que l’intégration est prête

L’intégration est prête lorsque le succès, l’échec, l’interruption et le doublon ont été observés sur le domaine réel. Un simple formulaire qui redirige vers CMI ne suffit pas. La commande doit exister avant le départ, l’autorisation doit être vérifiée après retour du prestataire et l’utilisateur doit recevoir un statut honnête.