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 coming from the
Merchant 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 of calling a URL located on the merchant server. This URL called Instant Notification URL is defined by the merchant from his
The Merchant has the possibility to define several rules depending on the event type.
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-auth or full).
- The details of the payment method used by the buyer (e.g.: type, masked card number, expiry date, etc.).
- Amount
- Buyer's e-mail 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 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
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 IPN execution error, a warning e-mail is sent to the address specified in the
This e-mail contains:
- The HTTP code of the encountered error.
- Analysis parts depending on the error.
- The steps to follow via the
Merchant Back Office to send again the 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”).
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 notification URL via the
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.
