Background information on the IPN

This document defines the concept of the IPN and explains when it should be used.

What is IPN?

IPN stands for Instant Payment Notification. In French it is referred to as instant notification at the end of payment.

IPN is a server to server notification (between the server of the payment gateway and the merchant server) that allows the merchant website to be notified in real time and automatically when an event occurs, for example when a transaction is recorded.

It is possible to configure notifications in the following cases:

  • event occurring within the payment form (HTTPS form): recording of a single or recurring payment, payment cancellation, etc.
  • opération provenant du Back Office Expert : enregistrement d’un paiement simple ou récurrent, annulation, remboursement, modification, validation d’une transaction, etc.

To receive notifications, the merchant must configure at least the end of payment notification rule. This rule is defined automatically when the shop is created.

The IPN is not sent when the data exchange between the merchant and the payment gateway is made via Web Services (server to server), as in this case the merchant analyzes the Web Service response that he or she receives in real time.

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 Back Office Expert (menu Paramétrage > Règles de notifications > onglet Appel URL de notification). La plateforme de paiement est capable de contacter l’URL du site marchand quel que soit le protocole utilisé (HTTP ou HTTPS).

The merchant has the possibility to define several rules depending on the type of the event.

The data is sent in POST mode, including:

  • The payment method used by the buyer,
  • The return code of the authorization,
  • The type of authorization (pre-auto or full),
  • The details of the payment method used by the buyer (e.g.: type, masked card number, expiry date, etc.),
  • Amount,
  • Buyer''s email address,
  • Order ID,
  • Etc.

The data transmitted in the IPN is received and analyzed by a script developed by the merchant on his or her server. Executing this script will also allow the merchant to update his or her information system depending on the received data.

The instant payment notification URL can also be overriden in the request.

How does an IPN work?

The merchant server and the payment platform interact by exchanging data. To guarantee the security of the exchange, the data is signed with a key only known to the merchant and the payment gateway.

To create a payment, this data is sent in an HTML form via the buyer''s browser (step 1).

At the end of the payment, the result is transmitted to the merchant website in two ways:

  • automatically via the notifications sent to the instant notification URL (step 2).
  • by the browser when the buyer clicks the button to return to the merchant website (step 3).

The processing time has a direct influence on the time it takes to display the payment summary page. The longer the processing takes, the more the summary display will be delayed.

What is the difference between the Instant Payment Notification URL and the return to shop URL?

Two types of URL are used to manage dialog with the merchant website:

  • Instant notification URL used for the IPN,
  • URL of return to the merchant website.

The instant payment notification URL allows the payment gateway to automatically notify the merchant website of the payment result. The URL for returning to the merchant website is used by the browser for redirecting the buyer to the merchant website when he or she clicks on the return to shop button.

The data transmitted to the browser is the same as in the IPN. The return to the shop will allow to show only the visual context to the buyer. Therefore, the received data must not be used for processing data in the database.

How can you check if the IPN works?

Dans le Back Office Expert, il est possible de consulter l’historique des notifications sur une transaction : clic droit sur une transaction > onglet Historique. Vous y trouverez notamment le statut de l’appel ( Envoyé ou Echoué ).

What to do in case of an error?

If an error occurred, the notification history allows to obtain various information:

  • time of the notification (in real time at the end of payment),
  • the execution duration of the analysis script on the merchant server side,
  • the 100 first characters that your script writes on the channel opened between the payment gateway and the merchant server (by retrieving printouts for this channel).

En cas d’erreur d’exécution de l’IPN, un e-mail d’avertissement est envoyé à l’adresse spécifiée dans le Back Office Expert (menu Paramétrage > Règles de notifications > onglet Appel URL de notification > « Adresse(s) e-mail à avertir en cas d’échec »). Par défaut, il s’agit de l’e-mail de l’administrateur de la boutique.

This e-mail contains:

  • The HTTP code of the encountered error,
  • analysis parts depending on the error,
  • la procédure à suivre depuis le Back Office Expert pour renvoyer la notification.

It is also possible to enable an option of automatic retry of the IPN (Settings > Notification rules > Instant Payment Notification URL call > check the box “Automatic retry in case of failure”). C

This option allows to automatically send notifications to the merchant website in case of failure (up to 4 times). Call attempts are programmed at fixed intervals every 15 minutes (00, 15, 30, 45). After each failed attempt, a warning e-mail is sent to the e-mail address specified earlier. The subject of this e-mail includes the number corresponding to the attempt of sending the notification.

Several return codes of HTTP type may appear during this exchange between servers. When the return code starts with 4xx or 5xx, the automatic retry does not occur.

En cas d’erreur de votre script, la plateforme de paiement vous propose de rejouer manuellement l’URL de notification instantanée depuis le Back Office Expert, une fois que vous avez corrigé votre problème.

In summary, there are three recommendations:

  • Pay attention to the configuration of your notification rules,
  • Test the IPN,
  • Read the e-mails from the payment gateway, they are very useful.