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.
  • operation originating from the Expert Back Office: registration of a single or recurring payment, cancellation, refund, update, validation of a 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.

This notification consists in calling a URL located on the merchant server. This URL, called the instant notification URL, is defined by the merchant via his or her Expert Back Office (Settings > Notification rules > Instant Payment Notification URL call tab). The payment gateway is able to contact the merchant website URL, regardless of the protocol (HTTP or HTTPS) that was used.

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&aposs 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&aposs browser (step 1).

At the end of the payment, the result can be 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 taken to display the payment summary page. The longer the processing takes, the later the summary will be shown.

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?

In the Expert Back Office, it is possible to view the notification history of a transaction: right click a transaction > History tab. It also contains the status of the call (Sent or Failure).

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).

In case of an execution error of the IPN, a warning e-mail is sent to the address specified in the Expert Back Office (Settings > Notification rules > Instant Payment Notification URL call tab > “E-mail address(es) to notify in case of failure”). By default, it is set to the e-mail of the shop administrator.

This e-mail contains:

  • the HTTP code of the encountered error,
  • analysis parts depending on the error,
  • instructions for resending the notification via the Expert Back Office.

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.

In case of an error in your script, the payment gateway offers you to manually retry the Instant Payment Notification URL via the Expert Back Office, once you have corrected your issue.

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.