Implementing an IPN listener

Important: NVP/SOAP is a legacy integration method. We accept new integrations and support existing integrations, but there are newer solutions. If you're starting an integration, we recommend our latest solutions.

IPN listeners can be implemented in any programming language that supports scripting and runs on your web server.

PayPal provides sample code for listeners implemented in the languages listed below. These sample listeners show how the PayPal IPN message validation handshaking is performed, and then show you where your listener backend logic should be implemented.

• PHP
• PERL
• ASP.NET
• Cold Fusion

These sample IPN listeners are available on GitHub at the following location: IPN code samples.

IPN listener request-response flow

To receive IPN message data from PayPal, your listener must follow this request-response flow:

1. Your listener listens for the HTTPS POST IPN messages that PayPal sends with each event.

2. After receiving the IPN message from PayPal, your listener returns an empty HTTP 200 response to PayPal. Otherwise, PayPal resends the IPN message.

3. Your listener sends the complete message back to PayPal using HTTPS POST.

   Prefix the returned message with the cmd=_notify-validate variable, but do not change the message fields, the order of the fields, or the character encoding from the original message.

   Send response messages back to PayPal:

   • https://ipnpb.sandbox.paypal.com/cgi-bin/webscr (for Sandbox IPNs)

   • https://ipnpb.paypal.com/cgi-bin/webscr (for live IPNs)

     Please ensure you provide a User-Agent header value that describes your IPN listener, such as, PHP-IPN-VerificationScript. For more information, see the User-Agent specification.

4. PayPal sends one of the following words back to your listener:

   • VERIFIED (if the message matches the original)
   • INVALID (if the message does not match the original)

For an example of an IPN message, you can use a sample IPN message as a starting point.

A list of IPN variables can be found in the IPN Variables reference; however, some of these variables may not be returned to you, depending on the type of transactions and events processed.

For more information about testing and troubleshooting your listener, see IPN Testing.

As a good programming practice, as well as to keep things simple, your IPN listener should listen for a post from PayPal and dispatch it immediately to another routine or process that handles the business logic associated with the message. If your listener is structured in this way, it will be a simple and tight loop that listens for a message and dispatches it for processing by your application logic.

When you have completed your listener, push it to your site and specify the listener URL or notification URL in your account settings. See IPN Setup for more information.