Généralités sur IPN
Ce document définit le concept d'IPN et explique quand l'utiliser.
Qu'est-ce que l'IPN ?
IPN est l’abréviation d’un terme anglais qui signifie Instant Payment Notification. En français, on parle de notification instantanée de fin de paiement.
L’IPN est une notification de serveur à serveur (serveur de la plateforme de paiement vers le serveur du marchand) qui permet au site marchand d’être notifié en temps réel et de manière automatique lorsqu’un événement se produit, par exemple lorsqu’une transaction est enregistrée.
Il est possible de configurer l’envoi de notifications dans les cas suivants :
- événement ayant lieu sur le formulaire de paiement (formulaire HTTPS) : enregistrement d’un paiement simple ou récurrent, abandon du paiement, etc.
- opération provenant du
Back Office Expert : enregistrement d’un paiement simple ou récurrent, annulation, remboursement, modification, validation d’une transaction, etc.
Pour recevoir les notifications, le marchand doit configurer au moins la règle de notification à la fin du paiement. Cette règle est définie automatiquement à la création de la boutique.
Il n’y a pas d’envoi d’IPN quand les échanges entre le marchand et la plateforme de paiement se font par Web Service (serveur à serveur) puisque dans ce cas, le marchand analyse la réponse du Web Service qu’il reçoit en temps réel.
Cette notification consiste à appeler une URL située sur le serveur marchand. Cette URL
appelée URL de notification instantanée est définie par le marchand depuis son
Le marchand a la possibilité de définir plusieurs règles selon le type d’évènement.
Les données sont envoyées en mode POST et parmi elles, on trouve :
- Le moyen de paiement utilisé par l'acheteur,
- Le code retour autorisation,
- Le type d'autorisation (pré-auto ou full),
- Le détail du moyen de paiement utilisé par l’acheteur (exemple : type, numéro de carte masqué, date d’expiration, etc.),
- Le montant,
- L’adresse e-mail de l’acheteur,
- Le numéro de commande,
- Etc.
Les données transmises dans l’IPN sont reçues et analysées par un script développé par le marchand sur son serveur. L’exécution de ce script permettra également au marchand de mettre à jour son système d’information en fonction des informations reçues.
L’URL de notification instantanée peut également être surchargée dans la requête.
Quel est le principe de fonctionnement d'une IPN ?
Le dialogue entre le serveur marchand et la plateforme de paiement s’effectue par un échange de données. Pour assurer la sécurité des échanges, les données sont signées au moyen d’une clé connue uniquement du marchand et de la plateforme de paiement.
Pour créer un paiement, ces données sont envoyées au moyen d'un formulaire HTML via le navigateur de l’acheteur (étape 1).
A la fin du paiement, le résultat est transmis au site marchand de deux manières :
- automatiquement au moyen de notifications envoyées à l’URL de notification instantanée (étape 2).
- par le navigateur lorsque l’acheteur clique sur le bouton pour revenir au site marchand (étape 3).
Le temps de traitement influe directement sur le délai d’affichage de la page de résumé du paiement. Plus le traitement est long, plus l’affichage est retardé.
Quelle différence entre URL de notification instantanée et URL de retour boutique ?
La gestion du dialogue vers le site marchand est réalisée grâce à deux types d’URL :
- URL de notification instantanée, utilisée pour l’IPN,
- URL de retour vers le site marchand.
L’URL de notification instantanée permet à la plateforme de paiement de notifier automatiquement le site marchand du résultat du paiement. L’URL de retour vers le site marchand est utilisée par le navigateur pour rediriger l’acheteur vers le site marchand lorsque celui-ci clique sur le bouton de retour boutique.
Les données transmises au navigateur sont les mêmes que dans l’IPN. Le retour à la boutique doit permettre uniquement d'afficher un contexte visuel à l'acheteur. Les données reçues ne doivent donc pas être utilisées pour effectuer le traitement en base de données.
Comment vérifier si l’IPN fonctionne ?
Dans le
Que faire en cas d’erreur ?
Si un problème a eu lieu, l’historique des notifications permet d’obtenir plusieurs informations :
- l’heure de la notification (en temps réel à la fin du paiement),
- la durée d'exécution du script d’analyse côté serveur marchand,
- les 100 premiers caractères que votre script écrit sur le canal ouvert entre la plateforme de paiement et le serveur marchand (par récupération des printout sur ce canal).
En cas d'erreur d'exécution de l’IPN, un e-mail d'avertissement est envoyé à l’adresse spécifiée
dans le
Cet e-mail contient :
- le code HTTP de l’erreur rencontrée,
- des éléments d’analyses en fonction de l’erreur,
- la procédure à suivre depuis le
Back Office Expert pour renvoyer la notification.
Il est également possible d’activer une option de rejeu automatique de l’IPN (menu Paramétrage > Règles de notifications > onglet Appel URL de notification > cochez la case « Rejeu automatique en cas d'échec »). C
Cette option permet de renvoyer automatiquement la notification vers le site marchand en cas d'échec, et ce, jusqu'à 4 fois. Les tentatives d'appel sont programmées à heures fixes toutes les 15 minutes (00, 15, 30, 45). Après chaque tentative infructueuse, un e-mail d'alerte est envoyé à l'adresse e-mail comme précédemment. L'e-mail envoyé comporte dans son objet le numéro correspondant à la tentative d'envoi de la notification.
Plusieurs codes retours de type HTTP peuvent apparaître durant ce dialogue entre serveurs. Lorsque le code de retour renvoyé commence par 4xx ou par 5xx, le rejeu automatique n'est pas applicable.
En cas d'erreur de votre script, la plateforme de paiement vous propose de rejouer manuellement l'URL de notification
instantanée depuis le
En résumé, trois conseils à suivre :
- Soyez attentif au paramétrage de vos règles de notification,
- Testez l’IPN,
- Lisez les e-mails de la plateforme de paiement, ils sont très utiles.